# openapi-atlas-mcp

`openapi-atlas-mcp` aggregates multiple OpenAPI/Swagger specifications from your
backend services into a single searchable, documentation-focused
[Model Context Protocol](https://modelcontextprotocol.io) 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

```bash
# 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:

```bash
openapi-atlas-mcp init
```

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

```json
{
  "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:

```bash
export BILLING_API_TOKEN=your-secret-token
```

3. Start the server:

```bash
openapi-atlas-mcp serve
```

## Agent-host integration

### Claude Desktop (`claude_desktop_config.json`)

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

### Cursor (`.cursor/mcp.json`)

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

### Claude Code

```bash
claude mcp add openapi-atlas -- openapi-atlas-mcp serve
```

### VS Code

Add to `.vscode/mcp.json`:

```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`](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`](docs/errors.md) for the full warning catalog.

## License

MIT