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):

Field	Type	Required	Description
services	ServiceConfig[]	Yes	One or more backend services to aggregate
auth	AuthConfig | null	No	Global default auth (overridable per-service)
allow_insecure_http_hosts	string[]	No	Hosts allowed for plain HTTP (e.g. ["localhost"])
cache.spec_ttl_seconds	int	No	Spec cache TTL in seconds (default: 60)
cache.disk_cache_dir	string | null	No	Custom disk cache directory

ServiceConfig

Field	Type	Required	Description
name	string	Yes	Unique service identifier
url	string	Yes	Base URL of the service (must include scheme)
spec_path	string | null	No	Explicit spec path (e.g. /api/openapi.json). Auto-discovered if omitted.
auth	AuthConfig | null	No	Per-service auth override

AuthConfig

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

Type	Required fields	Behavior
none	(none)	No auth headers sent
bearer	token_env	Sends Authorization: Bearer <env value>
basic	username_env, password_env	Sends Authorization: Basic <base64>
headers	headers_env	Sends custom headers from a JSON env var

Tools

Tool	Description
search_endpoints	Keyword-search operations across all services. Returns ranked matches with scores.
get_endpoint_detail	Returns the fully $ref-resolved schema for one endpoint.
list_services	Lists all configured services with health, version, and freshness metadata.
refresh_specs	Force a fresh fetch of one or all services. Clears caches.

When things go wrong

Symptom	Likely cause	Fix
ConfigNotFoundError	No .openapi-atlas.json found	Run openapi-atlas-mcp init or set OPENAPI_ATLAS_CONFIG
MissingEnvVarError	Referenced env var not set	export BILLING_API_TOKEN=...
InsecureHttpHostError	Plain HTTP to non-localhost	Add host to allow_insecure_http_hosts
Service shows unhealthy	Service unreachable	Check URL, auth, and network connectivity
Service shows degraded	Serving stale cache	Service was up before; check if it restarted
Empty search results	No services indexed yet	Call refresh_specs or check service health

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

License

MIT