Skip to main content
Glama
mbvillaverde

openapi-atlas-mcp

by mbvillaverde
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

Related MCP server: Public API MCP Server

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"
      }
    }
  ]
}

  1. Set any required environment variables:

export BILLING_API_TOKEN=your-secret-token

  1. 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

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mbvillaverde/openapi-atlas-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server