{
  "markdown": "<div align=\"center\">\n  <h1>openapi-dynamic-mcp</h1>\n\n  <p>\n    <strong>Connect AI clients to OpenAPI APIs quickly, with one MCP server, direct CLI access, and built-in auth support.</strong>\n  </p>\n\n  <p>\n    <a href=\"https://www.npmjs.com/package/openapi-dynamic-mcp\"><img src=\"https://img.shields.io/npm/v/openapi-dynamic-mcp?color=blue&style=flat-square\" alt=\"NPM Version\" /></a>\n    <a href=\"https://github.com/mayorandrew/openapi-dynamic-mcp/blob/main/LICENSE\"><img src=\"https://img.shields.io/npm/l/openapi-dynamic-mcp?style=flat-square\" alt=\"License\" /></a>\n    <img src=\"https://img.shields.io/node/v/openapi-dynamic-mcp?style=flat-square\" alt=\"Node.js Version\" />\n  </p>\n</div>\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Highlights](#highlights)\n- [Requirements](#requirements)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Client Setup](#client-setup)\n- [CLI](#cli)\n- [Authentication](#authentication)\n- [Environment Variables](#environment-variables)\n- [Working with Responses](#working-with-responses)\n- [Files and Binary Data](#files-and-binary-data)\n- [MCP Tools](#mcp-tools)\n- [Development](#development)\n- [License](#license)\n\n## Overview\n\n`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.\n\nIt is designed for common user workflows:\n\n- Connect multiple APIs through one MCP server\n- Use local specs or hosted `specUrl` definitions\n- Work with OpenAPI `3.0`, `3.1`, and Swagger `2.0`\n- Handle API key, bearer, basic, and OAuth2 auth\n- Reuse stored tokens across sessions\n- Filter large responses down to the fields you need\n- Preview requests safely before sending them\n\n## Highlights\n\n- **Get from spec to usable tools fast**: start from a YAML config and immediately browse endpoints or call them from MCP or the CLI.\n- **Authenticate the way your API expects**: supports API keys, bearer/basic auth, and OAuth2 client credentials, password, device code, and auth code with PKCE.\n- **Avoid repeated sign-in work**: store tokens once and reuse them later.\n- **Handle interactive OAuth cleanly**: device-code and browser-based auth return instructions an agent can present to the user.\n- **Keep responses focused**: project large outputs with JSONPath selectors.\n- **Inspect before you send**: use dry runs to preview request shape without network I/O.\n- **Upload files when needed**: supports multipart form uploads and raw binary bodies.\n- **Stay resilient against rate limits**: configurable retries for `429 Too Many Requests`.\n\n## Requirements\n\n- Node.js `20+`\n\n## Quick Start\n\nRun the MCP server directly:\n\n```bash\nnpx -y openapi-dynamic-mcp@latest --config ./config.yaml\n```\n\nMinimal config:\n\n```yaml\nversion: 1\napis:\n  - name: pet-api\n    specPath: ./pet-api.yaml\n```\n\nYou can also point at a remote spec:\n\n```yaml\nversion: 1\napis:\n  - name: pet-api\n    specUrl: https://api.example.com/openapi.json\n```\n\n## Configuration\n\nAdd each API you want to use under `apis`. Each entry can point to a local spec file or a remote spec URL.\n\n```yaml\nversion: 1\n\napis:\n  - name: pet-api\n    specPath: ./pet-api.yaml\n    # specUrl: https://api.example.com/openapi.yaml\n    baseUrl: https://api.example.com/v1\n    timeoutMs: 30000\n    headers:\n      X-Client: openapi-dynamic-mcp\n    retry429:\n      maxRetries: 2\n      baseDelayMs: 250\n      maxDelayMs: 5000\n      jitterRatio: 0.2\n      respectRetryAfter: true\n    oauth2Schemes:\n      OAuthCC:\n        tokenUrl: https://auth.example.com/oauth2/token\n        scopes: [read:pets, write:pets]\n        tokenEndpointAuthMethod: client_secret_basic\n      UserAuth:\n        authMethod: device_code\n        deviceAuthorizationEndpoint: https://auth.example.com/oauth/device\n        pkce: true\n```\n\nCommon options:\n\n- `name`: the API name shown in MCP and CLI commands\n- `specPath` or `specUrl`: where to load the OpenAPI spec from\n- `baseUrl`: override the server URL from the spec\n- `headers`: headers to send on every request\n- `timeoutMs`: default request timeout\n- `retry429`: retry behavior for rate-limited APIs\n- `oauth2Schemes`: per-scheme OAuth settings when the spec defines OAuth security\n\n### Per-Scheme OAuth2 Configuration\n\nUse `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.\n\nThe scheme name must match the name in the OpenAPI spec. Common options are:\n\n- `tokenUrl`\n- `scopes`\n- `tokenEndpointAuthMethod`\n- `authMethod`\n- `deviceAuthorizationEndpoint`\n- `pkce`\n\nIf you only need credentials, environment variables are often enough. Use `oauth2Schemes` when you want reusable config checked into the project.\n\n## Client Setup\n\n### Claude Desktop / Claude Code\n\n```json\n{\n  \"mcpServers\": {\n    \"openapi\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"openapi-dynamic-mcp@latest\",\n        \"--config\",\n        \"/absolute/path/to/config.yaml\"\n      ],\n      \"env\": {\n        \"PET_API_BASE_URL\": \"http://localhost:3000\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"openapi\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"openapi-dynamic-mcp@latest\",\n        \"--config\",\n        \"/absolute/path/to/config.yaml\"\n      ]\n    }\n  }\n}\n```\n\n## CLI\n\nServer mode is available as either the root command or the explicit `serve` subcommand:\n\n```bash\nopenapi-dynamic-mcp --config ./config.yaml\nopenapi-dynamic-mcp serve --config ./config.yaml\n```\n\nUse the CLI when you want the same API access outside your MCP client, for scripting, debugging, or auth setup.\n\n### Tool Commands\n\nEvery MCP tool is also available as a CLI subcommand that accepts one JSON object and emits JSON output:\n\n```bash\nopenapi-dynamic-mcp list_apis --config ./config.yaml --input '{}'\nopenapi-dynamic-mcp list_api_endpoints --config ./config.yaml --input '{\"apiName\":\"pet-api\"}'\nopenapi-dynamic-mcp get_api_endpoint --config ./config.yaml --input '{\"apiName\":\"pet-api\",\"endpointId\":\"listPets\"}'\nopenapi-dynamic-mcp get_api_schema --config ./config.yaml --input '{\"apiName\":\"pet-api\",\"pointer\":\"/info\"}'\nopenapi-dynamic-mcp make_endpoint_request --config ./config.yaml --input '{\"apiName\":\"pet-api\",\"endpointId\":\"listPets\",\"dryRun\":true}'\n```\n\nShared flags:\n\n- `--input <json>`: JSON object with command arguments\n- `--fields <jsonpath>`: repeatable selector for filtering successful output\n- `--describe`: print the command schema and help metadata\n- `--auth-file <path>`: override the auth-store path\n\n### Auth Command\n\nUse `auth` to pre-authenticate one configured security scheme and persist its token for later MCP or CLI calls:\n\n```bash\nopenapi-dynamic-mcp auth --config ./config.yaml --api pet-api --scheme OAuthCC\nopenapi-dynamic-mcp auth --config ./config.yaml --api pet-api --scheme ApiKeyAuth --token secret\n```\n\nFor API key and bearer auth, `--token` provides the secret directly. For OAuth2, the command uses your configured credentials, completes the flow, and stores the result for later use.\n\n## Authentication\n\nSupported authentication types:\n\n- API key\n- HTTP bearer\n- HTTP basic\n- OAuth2 client credentials\n- OAuth2 password grant (ROPC)\n- OAuth2 device code\n- OAuth2 authorization code with PKCE\n\nTypical auth flow:\n\n1. Provide credentials through environment variables or config\n2. Run `auth` once if the scheme needs a stored token\n3. Reuse that token from MCP or the CLI until it expires or changes\n\n### Auth Store\n\nBy default, tokens are stored beside your config file in:\n\n```text\n.openapi-dynamic-mcp-auth.json\n```\n\nYou can override that path with either:\n\n- `--auth-file`\n- `OPENAPI_DYNAMIC_MCP_AUTH_FILE`\n\nThis makes repeated API use much smoother, especially for MCP clients that need to reconnect often.\n\n### Interactive OAuth2 Flows\n\nWhen a request needs user interaction, the tool returns structured guidance that an MCP agent can relay to the user. Typical device-code output looks like:\n\n```json\n{\n  \"status\": \"authorization_required\",\n  \"method\": \"device_code\",\n  \"message\": \"User authorization required. Ask the user to visit the URL and enter the code.\",\n  \"verificationUri\": \"https://auth.example.com/device\",\n  \"userCode\": \"ABCD-1234\",\n  \"instruction\": \"After the user confirms, call this endpoint again.\"\n}\n```\n\nThis is especially useful for MCP agents because the auth step becomes a normal part of the user workflow instead of a dead-end error.\n\n## Environment Variables\n\nEnvironment variables are useful for secrets, base URL overrides, and CI setups.\n\nNames are derived from normalized API and scheme names:\n\n- Uppercase\n- Non-alphanumeric characters become `_`\n- Repeated `_` are collapsed\n- Leading and trailing `_` are removed\n\nExamples:\n\n- `pet-api` -> `PET_API`\n- `OAuth2` -> `OAUTH2`\n\n### API-Level Variables\n\n- `<API>_BASE_URL`\n- `<API>_HEADERS` as a JSON object string\n- `OPENAPI_DYNAMIC_MCP_AUTH_FILE`\n\n### API Key\n\n- `<API>_<SCHEME>_API_KEY`\n\n### HTTP Auth\n\n- `<API>_<SCHEME>_TOKEN`\n- `<API>_<SCHEME>_USERNAME`\n- `<API>_<SCHEME>_PASSWORD`\n\n### OAuth2\n\n- `<API>_<SCHEME>_ACCESS_TOKEN`\n- `<API>_<SCHEME>_CLIENT_ID`\n- `<API>_<SCHEME>_CLIENT_SECRET`\n- `<API>_<SCHEME>_TOKEN_URL`\n- `<API>_<SCHEME>_SCOPES` as a space-delimited list\n- `<API>_<SCHEME>_TOKEN_AUTH_METHOD` as `client_secret_basic` or `client_secret_post`\n- `<API>_<SCHEME>_USERNAME`\n- `<API>_<SCHEME>_PASSWORD`\n- `<API>_<SCHEME>_AUTH_METHOD` as `device_code` or `authorization_code`\n- `<API>_<SCHEME>_DEVICE_AUTHORIZATION_ENDPOINT`\n- `<API>_<SCHEME>_REDIRECT_PORT`\n- `<API>_<SCHEME>_PKCE` as `true` or `false`\n\nUseful behaviors:\n\n- `_ACCESS_TOKEN` bypasses OAuth grant flows entirely.\n- `_AUTH_METHOD` forces `device_code` or `authorization_code` when both are possible.\n- `_USERNAME` and `_PASSWORD` are used for both HTTP basic auth and OAuth password grant, depending on the security scheme.\n\n## Working with Responses\n\n### JSONPath Filtering\n\nCLI `--fields` and MCP `fields: string[]` let you keep only the parts of a successful response you care about. This is helpful when specs or payloads are too large to inspect comfortably.\n\nExamples:\n\n```bash\nopenapi-dynamic-mcp list_apis --config ./config.yaml --fields '$.apis[*].name'\nopenapi-dynamic-mcp get_api_endpoint --config ./config.yaml --input '{\"apiName\":\"pet-api\",\"endpointId\":\"listPets\"}' --fields '$.responses'\n```\n\nSelectors support quoted member escaping, array indexes, and wildcards.\n\n### Large Schema Warnings\n\n`get_api_schema` adds a `_sizeWarning` advisory field when the response is very large, prompting you to narrow the JSON Pointer.\n\n### Dry Runs\n\n`make_endpoint_request` supports `dryRun: true` so you can confirm the URL, headers, auth, and serialized body before sending a real request.\n\n## Files and Binary Data\n\n`make_endpoint_request` supports both `multipart/form-data` and raw binary uploads.\n\nEach file entry must provide exactly one content source: `base64`, `text`, or `filePath`.\n\n```json\n{\n  \"name\": \"avatar.png\",\n  \"contentType\": \"image/png\",\n  \"filePath\": \"/absolute/path/to/avatar.png\"\n}\n```\n\nMultipart example:\n\n```json\n{\n  \"apiName\": \"pet-api\",\n  \"endpointId\": \"uploadProfile\",\n  \"contentType\": \"multipart/form-data\",\n  \"body\": {\n    \"description\": \"A photo of Fido\"\n  },\n  \"files\": {\n    \"profileImage\": {\n      \"name\": \"fido.jpg\",\n      \"contentType\": \"image/jpeg\",\n      \"filePath\": \"/Users/local/images/fido.jpg\"\n    }\n  }\n}\n```\n\nRaw binary example:\n\n```json\n{\n  \"apiName\": \"pet-api\",\n  \"endpointId\": \"uploadRaw\",\n  \"contentType\": \"application/octet-stream\",\n  \"files\": {\n    \"body\": {\n      \"filePath\": \"/Users/local/data.bin\"\n    }\n  }\n}\n```\n\n## MCP Tools\n\nThese five tools cover the main user workflows:\n\n| Tool                    | Purpose                                                        |\n| ----------------------- | -------------------------------------------------------------- |\n| `list_apis`             | List configured APIs                                           |\n| `list_api_endpoints`    | Search or paginate endpoints in one API                        |\n| `get_api_endpoint`      | Inspect endpoint metadata, parameters, responses, and security |\n| `get_api_schema`        | Return a schema object or JSON Pointer target from the spec    |\n| `make_endpoint_request` | Preview or execute an endpoint request                         |\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nUseful commands:\n\n```bash\nnpm run lint\nnpm run format\nnpm run test:watch\n```\n\n## License\n\nMIT\n",
  "bytes": 12580,
  "sha": "87453f5bbe0e40a72ac0bf1b688c5523d5367fcc43ada1e16e8789db8c72d839",
  "repo_slug": "mayorandrew/openapi-dynamic-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mayorandrew_openapi_dynamic_ffa18a5c/readme"
}