Skip to main content

​
Supported formats

MCP Blacksmith accepts OpenAPI specifications in:
FormatVersionsFile types
OpenAPI2.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 or google-discovery-to-openapi, then upload the result.
Support for additional API specification formats is planned, including GraphQL, gRPC (Protocol Buffers), AsyncAPI, RAML, and API Blueprint.

​
How to upload

In the 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 or 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 — Authentication handlers are auto-generated
  • Use component schemas — Shared references produce deduplicated models
  • Specify response schemas — Enables response validation at runtime