@sondv5/swagger-mcp

@sondv5/swagger-mcp is a Node.js + TypeScript MCP server that reads a Swagger/OpenAPI JSON document and exposes token-efficient tools for finding and inspecting API endpoints.

It is designed for agent workflows:

1. Search endpoints first with compact results.
2. List everything only when search keywords are unknown or search returns nothing.
3. Fetch full endpoint detail only after the exact path and method are known.
4. Fetch multiple endpoint details in one call only when you already know the exact endpoints.

Features

• MCP server over stdio
• Uses @modelcontextprotocol/sdk
• Supports Swagger 2.0 and OpenAPI 3.x
• Lazy loads the spec on first tool call
• Caches the fetched spec in memory
• Supports bearer auth via environment variable
• Returns compact responses for discovery tools

Install / Run

Run directly with npx:

npx -y @sondv5/swagger-mcp@latest

For local development:

pnpm install
pnpm build
node dist/index.js

Configuration

Required environment variables:

• SWAGGER_URL: either:
  • a full Swagger/OpenAPI JSON URL, or
  • a host/base URL that the server will auto-resolve to a likely JSON endpoint

Optional environment variables:

• SWAGGER_AUTH_TOKEN: sent as Authorization: Bearer <token>

When SWAGGER_URL is only a host or base URL, the server tries the input URL first, then common JSON locations such as:

• /swagger.json
• /openapi.json
• /v2/swagger.json
• /v1/swagger.json
• /swagger/v2/swagger.json
• /swagger/v1/swagger.json
• /api-docs
• /docs/json

The resolved URL is cached in memory for the current process, keyed by the input host/base URL.

MCP Client Config

{
  "mcpServers": {
    "swagger-search": {
      "command": "npx",
      "args": ["-y", "@sondv5/swagger-mcp@latest"],
      "env": {
        "SWAGGER_URL": "https://example.com",
        "SWAGGER_AUTH_TOKEN": "optional-token"
      }
    }
  }
}

Local Project Setup

Below are project-local configuration examples for common MCP clients.

Ready-made templates are also included in this repository:

.cursor/mcp.json
.mcp.json
.codex/config.toml
opencode.json

Replace https://example.com with your real host or full Swagger JSON URL before using them.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "swagger-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sondv5/swagger-mcp@latest"],
      "env": {
        "SWAGGER_URL": "https://example.com",
        "SWAGGER_AUTH_TOKEN": "optional-token"
      }
    }
  }
}

Claude Code

Option 1: add it with the CLI from the project root:

claude mcp add --transport stdio --scope project \
  --env SWAGGER_URL=https://example.com \
  --env SWAGGER_AUTH_TOKEN=optional-token \
  swagger-search -- npx -y @sondv5/swagger-mcp@latest

Option 2: commit a project-level .mcp.json:

{
  "mcpServers": {
    "swagger-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sondv5/swagger-mcp@latest"],
      "env": {
        "SWAGGER_URL": "https://example.com",
        "SWAGGER_AUTH_TOKEN": "optional-token"
      }
    }
  }
}

Codex

Official Codex docs clearly document user-level MCP config in ~/.codex/config.toml:

[mcp_servers.swagger-search]
command = "npx"
args = ["-y", "@sondv5/swagger-mcp@latest"]
env = { SWAGGER_URL = "https://example.com", SWAGGER_AUTH_TOKEN = "optional-token" }

Current Codex builds may also load project-local config from .codex/config.toml for trusted projects. If you want repo-local setup, use the same snippet in:

.codex/config.toml

Example:

[mcp_servers.swagger-search]
command = "npx"
args = ["-y", "@sondv5/swagger-mcp@latest"]
env = { SWAGGER_URL = "https://example.com", SWAGGER_AUTH_TOKEN = "optional-token" }

If project-local Codex config is not picked up, fall back to ~/.codex/config.toml.

OpenCode

Create opencode.json in your project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "swagger-search": {
      "type": "local",
      "command": ["npx", "-y", "@sondv5/swagger-mcp@latest"],
      "enabled": true,
      "environment": {
        "SWAGGER_URL": "https://example.com",
        "SWAGGER_AUTH_TOKEN": "optional-token"
      }
    }
  }
}

Recommended Repo Files

If you want this server wired into a repository for multiple tools at once, the usual layout is:

.cursor/mcp.json
.mcp.json
.codex/config.toml
opencode.json

You typically commit .cursor/mcp.json, .mcp.json, and opencode.json when the MCP server is part of team workflow. For Codex, prefer ~/.codex/config.toml unless your team has verified project-local .codex/config.toml with the Codex version they use.

Tools

1. search_endpoints

Use this first when the user can describe what they need.

Input:

{
  "keywords": ["users", "create"]
}

Behavior:

• Searches across path, method, summary, description, operationId, and tags
• Prefers AND matching when possible, then falls back to OR matching
• Ranks exact path and strong path/operationId matches higher
• Returns compact results only

Example result shape:

{
  "totalMatched": 2,
  "results": [
    {
      "method": "POST",
      "path": "/api/users",
      "summary": "Create user",
      "operationId": "createUser",
      "tags": ["Users"]
    }
  ]
}

2. list_endpoints

Use this only when search keywords are unknown or search_endpoints returns empty.

Input:

{}

Behavior:

• Returns a compact list of strings such as "GET /api/users"
• Sorts by path, then method
• Does not return endpoint details

Example result shape:

{
  "totalCount": 3,
  "endpoints": ["GET /api/users", "POST /api/users", "GET /api/users/{id}"]
}

3. get_endpoint_detail

Use this after finding the exact path and method.

Input:

{
  "path": "/api/users",
  "method": "post"
}

Behavior:

• Returns the original operation object for the endpoint
• Includes path-level parameters separately when present
• If method is omitted and the path has multiple operations, the tool returns the available methods and asks the caller to specify one

Example result shape:

{
  "path": "/api/users",
  "method": "POST",
  "detail": {
    "summary": "Create user"
  },
  "pathParameters": []
}

4. get_multiple_endpoint_details

Use this when you already know several exact paths/methods and want full detail in one call.

Input:

{
  "items": [
    { "path": "/api/users", "method": "get" },
    { "path": "/api/users", "method": "post" }
  ]
}

Behavior:

• Resolves up to 10 endpoints per call
• Returns partial success instead of failing the whole request when one item is invalid
• Each successful item returns the same detail shape as get_endpoint_detail

Example result shape:

{
  "totalRequested": 2,
  "totalSucceeded": 2,
  "totalFailed": 0,
  "successes": [
    {
      "index": 0,
      "input": { "path": "/api/users", "method": "get" },
      "result": {
        "path": "/api/users",
        "method": "GET",
        "detail": {}
      }
    }
  ],
  "errors": []
}

Notes

• search_endpoints and list_endpoints are intentionally compact to reduce token usage.
• get_endpoint_detail and get_multiple_endpoint_details are the tools that return full endpoint detail.
• The server fetches the Swagger/OpenAPI document lazily and keeps it in memory for the lifetime of the process.
• If SWAGGER_URL is a host/base URL instead of a JSON URL, the server auto-resolves and caches the discovered JSON endpoint in memory for that host/base URL.