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](#overview)
- [Highlights](#highlights)
- [Requirements](#requirements)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Client Setup](#client-setup)
- [CLI](#cli)
- [Authentication](#authentication)
- [Environment Variables](#environment-variables)
- [Working with Responses](#working-with-responses)
- [Files and Binary Data](#files-and-binary-data)
- [MCP Tools](#mcp-tools)
- [Development](#development)
- [License](#license)
## 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:
```bash
npx -y openapi-dynamic-mcp@latest --config ./config.yaml
```
Minimal config:
```yaml
version: 1
apis:
- name: pet-api
specPath: ./pet-api.yaml
```
You can also point at a remote spec:
```yaml
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.
```yaml
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:
- `name`: the API name shown in MCP and CLI commands
- `specPath` or `specUrl`: where to load the OpenAPI spec from
- `baseUrl`: override the server URL from the spec
- `headers`: headers to send on every request
- `timeoutMs`: default request timeout
- `retry429`: retry behavior for rate-limited APIs
- `oauth2Schemes`: per-scheme OAuth settings when the spec defines OAuth security
### Per-Scheme OAuth2 Configuration
Use `oauth2Schemes` when an API defines one or more OAuth2 security schemes and you want to set token URLs, scopes, or interactive auth preferences for a specific scheme.
The scheme name must match the name in the OpenAPI spec. Common options are:
- `tokenUrl`
- `scopes`
- `tokenEndpointAuthMethod`
- `authMethod`
- `deviceAuthorizationEndpoint`
- `pkce`
If you only need credentials, environment variables are often enough. Use `oauth2Schemes` when you want reusable config checked into the project.
## Client Setup
### Claude Desktop / Claude Code
```json
{
"mcpServers": {
"openapi": {
"command": "npx",
"args": [
"-y",
"openapi-dynamic-mcp@latest",
"--config",
"/absolute/path/to/config.yaml"
],
"env": {
"PET_API_BASE_URL": "http://localhost:3000"
}
}
}
}
```
### Cursor
```json
{
"mcpServers": {
"openapi": {
"command": "npx",
"args": [
"-y",
"openapi-dynamic-mcp@latest",
"--config",
"/absolute/path/to/config.yaml"
]
}
}
}
```
## CLI
Server mode is available as either the root command or the explicit `serve` subcommand:
```bash
openapi-dynamic-mcp --config ./config.yaml
openapi-dynamic-mcp serve --config ./config.yaml
```
Use the CLI when you want the same API access outside your MCP client, for scripting, debugging, or auth setup.
### Tool Commands
Every MCP tool is also available as a CLI subcommand that accepts one JSON object and emits JSON output:
```bash
openapi-dynamic-mcp list_apis --config ./config.yaml --input '{}'
openapi-dynamic-mcp list_api_endpoints --config ./config.yaml --input '{"apiName":"pet-api"}'
openapi-dynamic-mcp get_api_endpoint --config ./config.yaml --input '{"apiName":"pet-api","endpointId":"listPets"}'
openapi-dynamic-mcp get_api_schema --config ./config.yaml --input '{"apiName":"pet-api","pointer":"/info"}'
openapi-dynamic-mcp make_endpoint_request --config ./config.yaml --input '{"apiName":"pet-api","endpointId":"listPets","dryRun":true}'
```
Shared flags:
- `--input