Openapi Dynamic MCP server

openapi-dynamic-mcp

Connect AI clients to OpenAPI APIs quickly, with one MCP server, direct CLI access, and built-in auth support.

Table of Contents

• Overview
• Highlights
• Requirements
• Quick Start
• Configuration
• Client Setup
• CLI
• Authentication
• Environment Variables
• Working with Responses
• Files and Binary Data
• MCP Tools

Overview

openapi-dynamic-mcp lets MCP clients and shell users work with OpenAPI APIs without writing custom glue code for each service. Point it at one or more OpenAPI specs, then list APIs, inspect endpoints, authenticate, and make requests through a consistent interface.

It is designed for common user workflows:

• Connect multiple APIs through one MCP server
• Use local specs or hosted specUrl definitions
• Work with OpenAPI 3.0, 3.1, and Swagger 2.0
• Handle API key, bearer, basic, and OAuth2 auth
• Reuse stored tokens across sessions
• Filter large responses down to the fields you need
• Preview requests safely before sending them

Highlights

• Get from spec to usable tools fast: start from a YAML config and immediately browse endpoints or call them from MCP or the CLI.
• Authenticate the way your API expects: supports API keys, bearer/basic auth, and OAuth2 client credentials, password, device code, and auth code with PKCE.
• Avoid repeated sign-in work: store tokens once and reuse them later.
• Handle interactive OAuth cleanly: device-code and browser-based auth return instructions an agent can present to the user.
• Keep responses focused: project large outputs with JSONPath selectors.
• Inspect before you send: use dry runs to preview request shape without network I/O.
• Upload files when needed: supports multipart form uploads and raw binary bodies.
• Stay resilient against rate limits: configurable retries for 429 Too Many Requests.

Requirements

• Node.js 20+

Quick Start

Run the MCP server directly:

npx -y openapi-dynamic-mcp@latest --config ./config.yaml

Minimal config:

version: 1
apis:
  - name: pet-api
    specPath: ./pet-api.yaml

You can also point at a remote spec:

version: 1
apis:
  - name: pet-api
    specUrl: https://api.example.com/openapi.json

Configuration

Add each API you want to use under apis. Each entry can point to a local spec file or a remote spec URL.

version: 1

apis:
  - name: pet-api
    specPath: ./pet-api.yaml
    # specUrl: https://api.example.com/openapi.yaml
    baseUrl: https://api.example.com/v1
    timeoutMs: 30000
    headers:
      X-Client: openapi-dynamic-mcp
    retry429:
      maxRetries: 2
      baseDelayMs: 250
      maxDelayMs: 5000
      jitterRatio: 0.2
      respectRetryAfter: true
    oauth2Schemes:
      OAuthCC:
        tokenUrl: https://auth.example.com/oauth2/token
        scopes: [read:pets, write:pets]
        tokenEndpointAuthMethod: client_secret_basic
      UserAuth:
        authMethod: device_code
        deviceAuthorizationEndpoint: https://auth.example.com/oauth/device
        pkce: true

Common options:

Shortened. The full README is on GitHub.