dynamic-openapi-mcp

Any OpenAPI spec. Instant AI tools.

Point it at a spec — your AI agent can call the API. OpenAPI v3 • JSON & YAML • Auto-auth • Zero config Every endpoint becomes a tool. Every schema becomes a resource.

Quick Start · Agent Setup · Auth · Programmatic API · CLI

Quick Start

npx dynamic-openapi-mcp -s https://petstore3.swagger.io/api/v3/openapi.json

That's it. The MCP server starts, your AI agent discovers all the tools, and can call the Petstore API.

For Claude Code, add it in one command:

claude mcp add petstore -- npx dynamic-openapi-mcp -s https://petstore3.swagger.io/api/v3/openapi.json

Now ask Claude: "list all available pets" — it will call listPets and return real data.

Table of Contents

• Quick Start
• What's Inside
• Setup with AI Agents
  • Claude Code
  • Cursor
  • Windsurf
  • Claude Desktop
  • Multiple APIs
• Authentication
  • Environment Variables
  • Supported Schemes
• Programmatic Usage
  • Custom Base URL
  • Inline Spec
  • Inspecting the Spec
• CLI Reference
• How the Mapping Works
  • Operations → Tools
  • Schemas → Resources
  • Prompts
• License

What's Inside

| Category | What you get | |:---------|:-------------| | Tools | One per operation — GET /pets becomes listPets, with fully typed inputs | | Resources | Full spec as openapi://spec + each schema as openapi://schemas/{name} | | Prompts | describe-api for an overview, explore-endpoint for details on any operation | | Auth | Bearer, API Key (header/query/cookie), Basic, OAuth2 client credentials | | Sources | URL, local file (JSON/YAML), inline string, or JavaScript object |

The flow is simple: AI calls a tool → dynamic-openapi-mcp makes the real HTTP request → response comes back as MCP content.

Setup with AI Agents

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["dynamic-openapi-mcp", "-s", "https://api.example.com/openapi.json"],
      "env": {
        "OPENAPI_AUTH_TOKEN": "your-bearer-token"
      }
    }
  }
}

Or add via CLI:

claude mcp add my-api -- npx dynamic-openapi-mcp -s https://api.example.com/openapi.json

Cursor

Go to Settings → MCP and add a new server, or add to .cursor/mcp.json:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["dynamic-openapi-mcp", "-s", "./specs/api.yaml"],
      "env": {
        "OPENAPI_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["dynamic-openapi-mcp", "-s", "https://api.example.com/openapi.json"],
      "env": {
        "OPENAPI_AUTH_TOKEN": "sk-..."
      }
    }
  }
}

Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["dynamic-openapi-mcp", "-s", "/absolute/path/to/spec.yaml"],
      "env": {
        "OPENAPI_AUTH_TOKEN": "your-token"
      }
    }
  }
}

Multiple APIs

Connect several APIs at once — each runs as a separate MCP server, and the AI sees all their tools combined:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["dynamic-openapi-mcp", "-s", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"],
      "env": { "OPENAPI_AUTH_TOKEN": "ghp_..." }
    },
    "stripe": {
      "command": "npx",
      "args": ["dynamic-openapi-mcp", "-s", "./specs/stripe.yaml"],
      "env": { "OPENAPI_AUTH_TOKEN": "sk_..." }
    },
    "internal-api": {
      "command": "npx",
      "args": ["dynamic-openapi-mcp", "-s", "https://internal.company.com/api/v1/openapi.json"],
      "env": { "OPENAPI_API_KEY": "key-..." }
    }
  }
}

Authentication

Via environment variables

# Bearer token (most common)
OPENAPI_AUTH_TOKEN=sk-123 npx dynamic-openapi-mcp -s ./spec.yaml

# API key
OPENAPI_API_KEY=key-456 npx dynamic-openapi-mcp -s ./spec.yaml

# Per-scheme (matches securitySchemes names in your spec)
OPENAPI_AUTH_BEARERAUTH_TOKEN=sk-123 npx dynamic-openapi-mcp -s ./spec.yaml

Or set them in the MCP config env block — same effect, cleaner setup.

Supported schemes

| Scheme | Env var | Programmatic config | |:-------|:--------|:--------------------| | Bearer | OPENAPI_AUTH_TOKEN | auth.bearerToken | | API Key (header/query/cookie) | OPENAPI_API_KEY | auth.apiKey | | Basic | OPENAPI_AUTH_TOKEN (as user:pass) | auth.basicAuth | | OAuth2 (client credentials) | — | auth.oauth2 | | Custom | — | auth.custom (function) |

Resolution order: programmatic config → per-scheme env var → global env var.

Programmatic Usage

pnpm add dynamic-openapi-mcp

import { createOpenApiMcp } from 'dynamic-openapi-mcp'

const mcp = await createOpenApiMcp({
  source: 'https://petstore3.swagger.io/api/v3/openapi.json',
  auth: { bearerToken: 'my-token' },
})

// Start as MCP server over stdio
await mcp.serve()

Custom base URL

const mcp = await createOpenApiMcp({
  source: './spec.yaml',
  baseUrl: 'http://localhost:3000',
  headers: { 'X-Custom-Header': 'value' },
})

From an inline spec

const mcp = await createOpenApiMcp({
  source: {
    openapi: '3.0.3',
    info: { title: 'My API', version: '1.0.0' },
    servers: [{ url: 'https://api.example.com' }],
    paths: {
      '/hello': {
        get: {
          operationId: 'sayHello',
          summary: 'Say hello',
          responses: { '200': { description: 'OK' } },
        },
      },
    },
  },
})

Inspecting the parsed spec

const mcp = await createOpenApiMcp({ source: './spec.yaml' })

console.log(mcp.spec.title)       // "My API"
console.log(mcp.spec.operations)  // ParsedOperation[]
console.log(mcp.spec.schemas)     // { Pet: {...}, User: {...} }

CLI Reference

dynamic-openapi-mcp [options] [source]

Options:
  -s, --source <url|file>   OpenAPI spec URL or file path
  -b, --base-url <url>      Override the base URL from the spec
  -h, --help                Show help

| Environment Variable | Description | |:---------------------|:------------| | OPENAPI_SOURCE | Spec URL or file path (alternative to -s) | | OPENAPI_BASE_URL | Override base URL | | OPENAPI_AUTH_TOKEN | Bearer token for authentication | | OPENAPI_API_KEY | API key for authentication |

How the Mapping Works

Operations → Tools

Each operation in the spec becomes one MCP tool:

| OpenAPI | MCP Tool | |:--------|:---------| | operationId: listPets | Tool name: listPets | | GET /pets/{petId} (no operationId) | Tool name: get_pets_by_petId | | summary or description | Tool description (truncated to 200 chars) | | Path + query + header params | Top-level input properties | | Request body | Input property under body key |

Schemas → Resources

| OpenAPI | MCP Resource URI | |:--------|:-----------------| | Full dereferenced spec | openapi://spec | | components.schemas.Pet | openapi://schemas/Pet | | components.schemas.User | openapi://schemas/User |

Prompts

| Prompt | Args | What it returns | |:-------|:-----|:----------------| | describe-api | — | Overview with title, version, all endpoints, auth schemes, schemas | | explore-endpoint | operationId | Full details: parameters, request body schema, responses, security |

License

MIT