OpenAPI

Generate an MCP server from OpenAPI

A practical tutorial for turning an OpenAPI or Swagger spec into a hosted MCP endpoint agents can inspect and call.

Jun 25, 20269 min readBeginner

Steps

Start with a stable spec URL

Use the canonical OpenAPI JSON or YAML URL when you have it. Swagger UI and Redoc pages can work, but the generator is more predictable when it can fetch the raw contract directly.

Example

https://petstore.swagger.io/v2/swagger.json

Preview the spec before generating

Run a preview first so you can confirm the discovered URL, parser mode, endpoint count, and obvious schema errors before creating a saved server.

Example

curl -sS -X POST https://astrail.dev/api/spec-preview \
  -H "Content-Type: application/json" \
  -d '{"sourceType":"openapi_url","sourceUrl":"https://petstore.swagger.io/v2/swagger.json"}'

Generate the hosted MCP endpoint

Create the server from the validated source. Keep the first pass narrow: generate from one spec, review the tool names, then add credentials only after the endpoint map looks right.

Example

curl -sS -X POST https://astrail.dev/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "openapi_url",
    "source_url": "https://petstore.swagger.io/v2/swagger.json",
    "generation_mode": "code"
  }'

Initialize the MCP server

Use initialize to confirm that the endpoint is live and returning the server metadata your client will see.

Example

curl -sS -X POST https://astrail.dev/api/mcp/SERVER_ID \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Search docs before executing

For generated Code Mode servers, search_docs gives the agent route-level context without dumping the whole API into one prompt.

Example

curl -sS -X POST https://astrail.dev/api/mcp/SERVER_ID \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_docs",
      "arguments": { "query": "list available pets" }
    }
  }'

Production checks

The preview reports the expected OpenAPI version and endpoint count.

tools/list does not expose private or destructive routes you did not intend to ship.

search_docs returns route names, parameters, auth requirements, and examples.

tools/call returns structured errors for missing parameters instead of upstream mystery failures.

FAQ

Can Swagger become an MCP server?

Yes. Swagger and OpenAPI specs are strong inputs because they already describe methods, paths, parameters, request bodies, and responses.

Should every OpenAPI route become an MCP tool?

Usually no. Large APIs work better with search_docs and execute patterns so the agent can find a route before calling it.