Overview

This MCP (Model Context Protocol) server exposes OpenAPI v3.0 and Swagger v2.0 specifications via token-efficient MCP Resource Templates. Instead of loading an entire (potentially huge) API spec into a language model’s context, MCP clients can request only the specific parts they need (paths, schemas, operations, metadata) using parameterized template URIs. Swagger v2.0 specs are converted to OpenAPI v3.0 automatically on load.

That design makes it much easier for LLM-enabled developer tools (Claude Desktop, Cline, Windsurf, etc.) to explore large APIs without exhausting model context windows or requiring pre-enumeration of every path and component. The server accepts local file paths or HTTP/HTTPS URLs for specs and exposes structured, read-only exploration endpoints via the MCP resources/templates/list and resources/get workflows.

Features

Serve OpenAPI v3.0 and convert Swagger v2.0 → OpenAPI v3.0 transparently
Expose parameterized MCP Resource Templates (no pre-enumeration)
Load specs from local files or remote URLs
Output formats: JSON or YAML
Simple CLI entry suitable for MCP clients (npx, Docker, node, global install)
Read-only, token-efficient exploration for LLM-driven workflows

Installation / Configuration

No manual install is required for recommended usage (npx or Docker). Below are common ways to run the server.

Using npx (recommended)

# Run with a remote spec URL, outputs YAML
npx -y mcp-openapi-schema-explorer@latest https://example.com/openapi.yaml --output-format yaml

Docker

# Pull and run (mount local file or provide URL as argument)
docker run --rm kadykov/mcp-openapi-schema-explorer:latest https://example.com/openapi.yaml --output-format json

Global install

npm install -g mcp-openapi-schema-explorer
mcp-openapi-schema-explorer /path/to/local/openapi.yaml --output-format yaml

Local development

git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
cd mcp-openapi-schema-explorer
npm install
npm run build
node ./dist/cli.js /path/to/openapi.yaml --output-format json

Example MCP client configuration (npx)

{
  "mcpServers": {
    "My API Spec (npx)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-openapi-schema-explorer@latest",
        "https://example.com/openapi.yaml",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

Available Resources (Resource Templates)

This server provides Resource Templates (parameterized URIs) rather than pre-enumerated resources. MCP clients should call resources/templates/list to discover templates and then request specific resources using the templated URIs.

Common templates exposed (examples):

Template URI	Description	Example value
openapi://info	API metadata (title, version, description)	openapi://info
openapi://servers	Server list	openapi://servers
openapi://paths/{path}/{method}	Single path operation object	openapi://paths//pets/get
openapi://paths/list?prefix={prefix}	List path keys with optional prefix	openapi://paths/list?prefix=/pets
openapi://components/schemas/{schema}	Schema object by name	openapi://components/schemas/Pet
openapi://components/parameters/{name}	Reusable parameter	openapi://components/parameters/limit
openapi://components/responses/{name}	Reusable response	openapi://components/responses/NotFound

Notes:

Clients receive template patterns via the MCP resources/templates/list method and then use resources/get with a concrete URI (substituting parameters).
Because templates are parameterized, the server avoids enumerating thousands of possible resources, which saves tokens and speeds discovery.

How it helps with token-efficiency

Pull only the minimal JSON/YAML needed (single path, single schema) instead of an entire spec.
LLMs can reason against targeted resource fragments, keeping context small.
Useful for large public APIs (thousands of endpoints) or internal APIs where you want focused exploration.

Use Cases

Explore a single operation before calling an API
- Workflow: list templates → get openapi://paths/{path}/{method} for the desired endpoint → render parameters and example payloads in the UI.
Inspect a schema used in responses
- Workflow: get openapi://components/schemas/{schema} to show shape to a model or developer.
Generate a client snippet for a single operation
- Workflow: retrieve operation object and servers, then synthesize a request example (no need to load full spec).
On-demand documentation in chatbots or IDE assistants
- Chatbot requests only the endpoint being discussed, preserving model tokens and speeding responses.
LLM-driven API testing
- LLM pulls only the necessary path + schema to generate test cases for an operation.

Tips & Notes

Swagger v2.0 files are converted to OpenAPI v3.0 automatically — you can point the server at v2 specs without manual conversion.
The server is read-only; it exposes resources for exploration but not as Tools for executing HTTP calls. For code generation or execution, combine this server (for spec exploration) with a separate tool that performs calls.
To discover what templates are available, use the MCP resources/templates/list RPC defined in the Model Context Protocol.

For developers integrating MCP clients, this server provides a straightforward, token-conscious way to make large API specifications accessible to models and tooling without overwhelming context windows.

Token-Efficient OpenAPI & Swagger MCP Server