MCP Integration

openapi.city exposes a Model Context Protocol server so AI coding assistants can search and query OpenAPI specs natively — no custom HTTP calls needed.

What is MCP?

MCP is a standard protocol for connecting AI tools to external data sources. AI assistants like Cursor, Claude Code, and Windsurf use MCP servers to access real-time information during conversations.

Configuration

Add openapi.city to your MCP client configuration:

OpenCode

Edit ~/.config/opencode/opencode.json (global) or opencode.json in your project root. See OpenCode config docs for details.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openapi-city": {
      "type": "remote",
      "url": "https://openapi.city/mcp",
      "headers": {
        "Authorization": "Bearer oac_live_YOUR_KEY"
      }
    }
  }
}

Claude Code

Run the MCP add command:

claude mcp add --transport http openapi-city https://openapi.city/mcp \
  --header "Authorization: Bearer oac_live_YOUR_KEY"

Or edit .mcp.json in your project root for team sharing:

{
  "mcpServers": {
    "openapi-city": {
      "type": "http",
      "url": "https://openapi.city/mcp",
      "headers": {
        "Authorization": "Bearer oac_live_YOUR_KEY"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "openapi-city": {
      "url": "https://openapi.city/mcp",
      "headers": {
        "Authorization": "Bearer oac_live_YOUR_KEY"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "openapi-city": {
      "serverUrl": "https://openapi.city/mcp",
      "headers": {
        "Authorization": "Bearer oac_live_YOUR_KEY"
      }
    }
  }
}

Discovery

The MCP server metadata is available without authentication:

GET https://openapi.city/.well-known/mcp

Returns a spec-compliant discovery document:

{
  "mcp": {
    "spec_version": "2026-01-21",
    "status": "stable",
    "servers": [{
      "name": "openapi-city",
      "url": "https://openapi.city/mcp",
      "transport": "http",
      "auth": {
        "type": "api-key",
        "header": "Authorization",
        "prefix": "Bearer",
        "key_format": "oac_live_*"
      }
    }],
    "tools": [...],
    "prompts": [...]
  }
}

Agent instructions are also available:

GET https://openapi.city/.well-known/skills

Returns a markdown file with usage tips, rate limits, and common patterns.

Available tools

`search_apis`

Search for API providers by name or keyword.

{
  "query": "payment",
  "category": "fintech"
}

`list_endpoints`

List all endpoints for a provider.

{
  "provider": "stripe",
  "method": "GET"
}

`get_endpoints`

Get full details for one or more endpoints. Returns OpenAPI-standard operation data with $ref references preserved.

{
  "provider": "stripe",
  "endpoints": "POST /v1/charges"
}

Parameters:

Param Type Description provider string Provider slug (required) endpoints string Comma-separated METHOD PATH pairs (required) depth integer Component depth 0-3 (default 2) part string Response part: full, response, request, params_only (default full) omit string Comma-separated fields to exclude: schemas, responses, description, request_body include_schemas string Comma-separated schema names to include (only these + deps)

`get_schemas`

Get schema definitions with $ref references preserved. Use depth to include transitive references.

{
  "provider": "stripe",
  "names": "Charge"
}

Parameters:

Param Type Description provider string Provider slug (required) names string Comma-separated schema names (required) depth integer Resolution depth 0-3 (default 0)

`get_spec_summary`

Get an AI-generated summary of a provider’s spec.

{
  "provider": "stripe"
}

`get_auth_requirements`

Get authentication schemes required by a provider.

{
  "provider": "stripe"
}

`get_version_diff`

Get diff between a spec version and its predecessor.

{
  "provider": "stripe",
  "version_id": 123,
  "detail": "compact"
}

Parameters:

Param Type Description provider string Provider slug (required) version_id integer Spec version ID (required) detail string compact or full (default compact)

`resolve_spec`

Submit a new OpenAPI spec URL for ingestion. Returns provider_slug to poll status.

{
  "url": "https://petstore3.swagger.io/api/v3/openapi.json"
}

`get_ingestion_status`

Check ingestion progress after resolve_spec. Poll until state is completed or failed.

{
  "provider_slug": "petstore3"
}

Response:

Field Description state completed, in_progress, or failed progress downloading, finalizing, completed, or failed endpoint_count Number of endpoints ingested schema_count Number of schemas ingested error Error message if state is failed

Available prompts

`integrate_api`

Generate an integration guide for a specific API:

{
  "provider": "stripe",
  "use_case": "accept payments on a checkout page"
}

`compare_apis`

Compare two APIs for a specific use case:

{
  "provider_a": "stripe",
  "provider_b": "paypal",
  "use_case": "recurring subscriptions"
}

`health_check`

Verify API key and MCP connection. Returns account status, plan, and remaining calls.

{}

All tools that query a specific provider accept an optional version parameter to target a historical spec version instead of the current one:

{
  "provider": "stripe",
  "version": "2024-01-01",
  "method": "GET"
}

Applies to: list_endpoints, get_endpoints, get_schemas, get_spec_summary, get_auth_requirements.

Resource templates

The server exposes resources via openapi:// URI templates:

Template Description openapi://providers/{slug} Provider metadata openapi://providers/{slug}/spec Full OpenAPI spec (current) openapi://providers/{slug}/endpoints Endpoint index (current) openapi://providers/{slug}/tags/{tag} Tag-grouped endpoints (current) openapi://providers/{slug}/versions/{version}/spec Spec for a specific version openapi://providers/{slug}/versions/{version}/endpoints Endpoints for a specific version

Usage example

Once configured, ask your AI assistant:

“Find me a payments API and show me how to create a charge”

The assistant will use search_apis, get_endpoints, and get_schemas tools to find Stripe, retrieve the charge endpoint, and show you the schema — all through MCP.

Next: Billing →