> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpblacksmith.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload

> Supported specification formats and how to upload your OpenAPI specification.

## Supported formats

MCP Blacksmith accepts OpenAPI specifications in:

| Format  | Versions                           | File types               |
| ------- | ---------------------------------- | ------------------------ |
| OpenAPI | 2.0 (Swagger), 3.0.x, 3.1.x, 3.2.x | `.json`, `.yaml`, `.yml` |

Have a Postman Collection or Google Discovery document instead? You can convert them to OpenAPI using [postman-to-openapi](https://joolfe.github.io/postman-to-openapi/) or [google-discovery-to-openapi](https://github.com/stackql/google-discovery-to-openapi), then upload the result.

<Note>
  Support for additional API specification formats is planned, including GraphQL, gRPC (Protocol Buffers), AsyncAPI, RAML, and API Blueprint.
</Note>

## How to upload

In the [dashboard](https://mcpblacksmith.com/dashboard):

1. Create a new project
2. Drag and drop your specification file into the upload zone, or click to browse
3. MCP Blacksmith parses and validates the specification immediately

## Where to find specifications

Most APIs publish their OpenAPI specification. Common locations:

* **API documentation pages** — Look for "OpenAPI", "Swagger", or "API Reference" links
* **Common URL patterns** — `/openapi.json`, `/swagger.json`, `/api-docs`, `/v3/api-docs`
* **GitHub repositories** — Many companies publish specifications in their public repos
* **Public registries** — [SwaggerHub](https://app.swaggerhub.com/search) or [APIs.guru](https://apis.guru)

## Specification quality tips

While any valid specification should result in a fully functional server, better specifications produce better servers:

* **Include descriptions** — These become tool descriptions for AI agents
* **Define [security schemes](/reference/oas-3-0#security-scheme-object)** — Authentication handlers are auto-generated
* **Use [component schemas](/reference/oas-3-0#components-object)** — Shared references produce deduplicated models
* **Specify [response schemas](/reference/oas-3-0#responses)** — Enables response validation at runtime