Troubleshooting
Troubleshoot OpenAPI to MCP generation
Fix common OpenAPI to MCP generation issues: missing specs, invalid schemas, auth confusion, oversized tool lists, and broken execute calls.
Steps
Confirm the raw spec is reachable
Many generation failures are discovery failures. Fetch the raw JSON or YAML URL outside the dashboard and confirm it returns OpenAPI or Swagger content, not HTML, login pages, or a blocked response.
curl -i https://example.com/openapi.json | sed -n '1,20p'Check parser diagnostics
Look for invalid JSON, unsupported YAML, missing paths, circular schemas, and content types that do not describe JSON request bodies clearly.
Reduce oversized specs
Very large APIs can produce noisy tool surfaces. Start with an endpoint subset or rely on search_docs and execute rather than exposing every operation as a top-level tool.
Separate auth errors from schema errors
A 401 from upstream means the call reached the API. A local validation error means the generated MCP runtime rejected the request before upstream. Debug those paths separately.
Capture one failing MCP request
Keep the exact JSON-RPC body that fails. It lets you reproduce the issue without the agent in the loop.
curl -sS -X POST https://astrail.dev/api/mcp/SERVER_ID \
-H "Content-Type: application/json" \
-d @failing-request.jsonProduction checks
FAQ
Why does my Swagger UI page fail while the API docs look fine?
Swagger UI is HTML. The generator needs to discover the raw spec URL linked by that page. Use the direct JSON or YAML URL when possible.
Why does tools/list look too large?
The source API may be too broad for a direct tool list. Use search_docs, endpoint subsets, or reviewed route groups for better agent behavior.