Skip to main content
If 0mcp can’t parse your API specification, the document may contain formatting errors, unsupported structures, or missing required fields. The checks below resolve most import issues.

​
Verify the file format

Make sure your specification:
  • Is in JSON or YAML
  • Uses a .json, .yaml, or .yml extension
  • Is 10 MB or smaller

​
Verify the OpenAPI version

Your document must contain one of the following top-level fields:
  • openapi for OpenAPI 3.x
  • swagger for Swagger 2.0
Other specification formats aren’t currently supported. Do not upload a GraphQL schema or Postman Collection through the OpenAPI importer.

​
Check for syntax errors

Invalid syntax is one of the most common causes of failed imports. Verify that:
  • JSON is well-formed
  • YAML indentation is consistent
  • Brackets, braces, and quotation marks are balanced

​
Review your operations

For the best import experience:
  • Give every operation a unique operationId
  • Write clear summaries and descriptions
  • Remove duplicate operation IDs
Unique operation IDs help 0mcp generate clear MCP tool names.

​
Validate references

Check that all referenced schemas and components exist. Common issues include:
  • Missing $ref targets
  • Broken schema references
  • Circular references that cannot be resolved

​
Verify your server URL

Ensure your specification defines a valid upstream API endpoint. For example:
  • OpenAPI 3.x uses the servers section.
  • Swagger 2.0 uses host, basePath, and schemes.
0mcp uses this information when generating requests to your API.

​
Importing from a URL

If you’re importing from a public URL:
  • The URL must be publicly accessible.
  • It should return the OpenAPI document directly.
  • It must not redirect to a login page or HTML documentation.
A quick test is to open the URL in a private browser window. If you see the raw JSON or YAML document, 0mcp should be able to access it as well.
A URL that works only after you sign in to a browser is not publicly accessible to the importer.

​
Isolate the problem

If the error isn’t obvious:
  1. Create a smaller version of the specification containing a single endpoint.
  2. Import the reduced document.
  3. Gradually add paths and components back until the error reappears.
This approach makes it much easier to identify the section causing the import to fail. See OpenAPI specification for supported import methods and quality recommendations.