openapi-mcp

An MCP (Model Context Protocol) server that parses OpenAPI/Swagger documentation and exposes structured query tools, allowing AI agents to efficiently query API docs without loading the entire spec into context.

Problem

Swagger/OpenAPI files can be very large and may exceed an LLM's context window. Loading the full spec is wasteful when an agent only needs information about a specific endpoint, tag, or schema.

Solution

openapi-mcp parses and indexes your OpenAPI spec at startup, then exposes 8 focused MCP tools. The agent queries only what it needs.

Supported Formats

• Swagger 2.0 (JSON or YAML)
• OpenAPI 3.0.x (JSON or YAML)
• Local file or remote URL

Installation

# Clone and build
git clone https://github.com/thanhtunguet/openapi-mcp
cd openapi-mcp
npm install
npm run build

# Or install globally (after publishing)
npm install -g openapi-mcp

Usage

# From a local file
node dist/index.js --file ./swagger.yaml

# From a remote URL
node dist/index.js --url https://api.example.com/v3/api-docs

Cursor / MCP Configuration

Add to your .cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "openapi": {
      "command": "node",
      "args": [
        "/absolute/path/to/openapi-mcp/dist/index.js",
        "--file",
        "/absolute/path/to/your/swagger.yaml"
      ]
    }
  }
}

Or with a remote URL:

{
  "mcpServers": {
    "openapi": {
      "command": "node",
      "args": [
        "/absolute/path/to/openapi-mcp/dist/index.js",
        "--url",
        "https://api.example.com/v3/api-docs"
      ]
    }
  }
}

Available Tools

get_api_info

Get general metadata about the loaded API.

Parameters: none

Returns: title, version, description, servers/basePath.

list_tags

List all tags (controllers/groups) with endpoint count and description.

Parameters: none

Returns:

{
  "total": 3,
  "tags": [
    { "name": "pet", "description": "Everything about your Pets", "endpointCount": 8 },
    { "name": "store", "description": "Access to Petstore orders", "endpointCount": 4 }
  ]
}

get_endpoints_by_tag

Get all endpoints that belong to a specific tag/controller.

Parameters: | Name | Type | Required | Description | | ----- | ------ | -------- | --------------------------- | | tag | string | yes | Tag name. Case-insensitive. |

Returns: Array of endpoints with full details (parameters, request body, responses).

get_endpoint

Get full details of a single endpoint.

Parameters: | Name | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------- | | path | string | yes | API path, e.g. /api/v1/users/{id} | | method | string | yes | HTTP method, e.g. GET, POST. Case-insensitive. |

Returns: Full endpoint details including parameters, request body schema, and all response schemas.

search_endpoints

Search endpoints by keyword across path, summary, description, operationId, and tags.

Parameters: | Name | Type | Required | Description | | ------- | ------- | -------- | ------------------------------- | | query | string | yes | Search keyword(s) | | limit | integer | no | Max results (1–100, default 10) |

Returns: List of matching endpoints (compact format: method, path, operationId, summary, tags).

get_endpoints_by_prefix

Get all endpoints whose path starts with a given prefix.

Parameters: | Name | Type | Required | Description | | -------- | ------ | -------- | --------------------------------- | | prefix | string | yes | Path prefix, e.g. /api/v1/users |

Returns: List of matching endpoints (compact format).

list_schemas

List all schemas/models defined in the API.

Parameters: none

Returns:

{
  "total": 5,
  "schemas": [
    { "name": "User", "description": "A user account", "type": "object" },
    { "name": "Order", "description": "An order", "type": "object" }
  ]
}

get_schema

Get the full definition of a specific schema/model.

Parameters: | Name | Type | Required | Description | | ------ | ------ | -------- | ------------------------------ | | name | string | yes | Schema name. Case-insensitive. |

Returns: Full schema with all properties, required fields, enums, allOf/anyOf/oneOf, and examples.

Architecture

OpenAPI file/URL
       │
       ▼
  SwaggerParser.dereference()   ← resolves all $ref pointers
       │
       ▼
    indexer.ts                  ← builds Maps: tagMap, pathMap, prefixMap, schemaMap
       │
       ▼
 StructuredSearchProvider       ← keyword search + structured lookup
       │
       ▼
  MCP Tools (stdio)             ← 8 tools registered via @modelcontextprotocol/sdk
       │
       ▼
   AI Agent (Cursor)

Key Design Decisions

• Dereferencing: All $ref pointers are resolved at parse time so every endpoint includes fully expanded schemas. The agent never needs to chase references.
• Structured indexing: In-memory Map structures for O(1) tag/path lookups and fast prefix matching.
• Compact search results: search_endpoints and get_endpoints_by_prefix return a compact format (method, path, summary). Use get_endpoint to drill into details.
• Future-ready: The SearchProvider interface is designed to be extended with a vector/semantic implementation without changing any tool code.

Development

# Type-check without building
npm run typecheck

# Run in dev mode (no build needed)
npm run dev -- --file ./swagger.yaml

# Build
npm run build

Extending with Vector Search (Future)

Implement SearchProvider from src/search.ts and pass your implementation to the MCP server:

import type { SearchProvider } from './search.js';

class VectorSearchProvider implements SearchProvider {
  // implement using OpenAI embeddings or a local model
}

The SpecIndex built by buildIndex() gives you access to all EndpointInfo and SchemaInfo objects to embed.