dynamic-openapi-mcp

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