apispec-mcp

An MCP server that lets AI agents explore and understand OpenAPI/Swagger specifications. Point it at any spec URL and use 12 tools to browse endpoints, schemas, auth, and generate examples — without the agent ever loading the raw JSON into context.

Supports Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1 (JSON or YAML).

Quick start

No installation needed. Add this to your MCP client config and you're done.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "apispec-mcp": {
      "command": "npx",
      "args": ["-y", "apispec-mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "apispec-mcp": {
      "command": "npx",
      "args": ["-y", "apispec-mcp"]
    }
  }
}

Other MCP clients

Any client that supports stdio MCP servers can run it with:

npx apispec-mcp

Usage

Once configured, tell the agent to load a spec — it will prompt you for the URL:

Load the API spec and show me all endpoints.

When the agent calls load_spec, you will be prompted to enter the spec URL (if your client supports interactive input). If it doesn't, paste the URL in chat and the agent will use it.

Example URLs:

• https://petstore3.swagger.io/api/v3/openapi.json
• /path/to/local/openapi.yaml

Tools

Spec Loading

| Tool | Description | |-------------|-------------| | load_spec | Fetch and parse an OpenAPI spec. Pass the URL if you have it, or omit it and the user will be prompted to enter it. Must be called before any other tool. |

Core Discovery

| Tool | Params | Description | |------|--------|-------------| | get_endpoints | path_prefix?, tag?, limit?, offset? | List endpoints grouped by tag, or filter by path prefix / tag with pagination. | | get_endpoint_detail | path, method | Full operation detail: parameters, request body, responses, auth. | | get_endpoint_parameters | path, method | Just the parameters (path, query, header, cookie) — lightweight fallback when detail is too large. | | get_schemas | -- | List all named schemas with type and property count. | | get_schema_detail | schema_name | Full expanded schema with all $refs resolved. |

Search

| Tool | Params | Description | |------|--------|-------------| | search_endpoints | query, limit?, offset? | Multi-keyword ranked search. Words match independently; path matches score highest. | | get_endpoints_by_tag | tag, limit?, offset? | Filter endpoints by tag with pagination. |

Context & Auth

| Tool | Params | Description | | ------------------ | ------ | -------------------------------------------------- | | get_auth_schemes | -- | Security schemes and which endpoints require them. | | get_servers | -- | Base URLs / environments defined in the spec. |

Examples

| Tool | Params | Description | | ---------------------- | ------------------------------------------------- | ---------------------------------------------------- | | get_request_example | path, method, content_type? | Generate an example request body from the schema. | | get_response_example | path, method, status_code?, content_type? | Generate an example response body for a status code. |

How it works

1. The agent calls load_spec (no URL needed as an argument).
2. If your MCP client supports interactive input, you are prompted to enter the spec URL or file path.
3. If interactive input is not supported, the agent asks you to paste the URL in chat and passes it along.
4. The server fetches, parses, and fully dereferences the spec (all $ref pointers resolved) — the full JSON never enters the agent's context.
5. All other tools query the parsed spec in memory.

Requirements

• Node.js 18+
• An MCP-compatible client (Cursor, Claude Desktop, etc.)

Tech stack

• @modelcontextprotocol/sdk — MCP server framework (stdio transport)
• @apidevtools/swagger-parser — OpenAPI parsing and $ref resolution
• zod — Input schema validation
• TypeScript, Node.js 18+