openapi-atlas-mcp

openapi-atlas-mcp aggregates multiple OpenAPI/Swagger specifications from your backend services into a single searchable, documentation-focused Model Context Protocol server. It lets an AI agent (Claude Desktop, Cursor, Claude Code, VS Code) answer questions like "show me the payload for submit order" across all of your configured services in one query — instead of making you hunt through N separate Swagger UIs.

Install

# pip
pip install openapi-atlas-mcp

# uv (recommended for MCP servers)
uv tool install openapi-atlas-mcp

Quick start

1. Create a config file (.openapi-atlas.json) in your project root:

openapi-atlas-mcp init

This launches an interactive wizard. Or write the file manually:

{
  "services": [
    {
      "name": "orders",
      "url": "http://localhost:8000"
    },
    {
      "name": "billing",
      "url": "https://billing.internal.example.com",
      "auth": {
        "type": "bearer",
        "token_env": "BILLING_API_TOKEN"
      }
    }
  ]
}

2. Set any required environment variables:

export BILLING_API_TOKEN=your-secret-token

3. Start the server:

openapi-atlas-mcp serve

Agent-host integration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "openapi-atlas": {
      "command": "uv",
      "args": ["tool", "run", "openapi-atlas-mcp", "serve"]
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "openapi-atlas": {
      "command": "openapi-atlas-mcp",
      "args": ["serve"]
    }
  }
}

Claude Code

claude mcp add openapi-atlas -- openapi-atlas-mcp serve

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "openapi-atlas": {
      "command": "openapi-atlas-mcp",
      "args": ["serve"]
    }
  }
}

Configuration reference

The config file (.openapi-atlas.json or path via OPENAPI_ATLAS_CONFIG env var):

ServiceConfig

AuthConfig

Secrets are referenced by env-var name — never inline. See docs/auth.md for patterns.

Tools

When things go wrong

See docs/errors.md for the full warning catalog.

License

MIT