mcp-openapi-proxy

mcp-openapi-proxy is a Python package that implements a Model Context Protocol (MCP) server, designed to dynamically expose REST APIs—defined by OpenAPI specifications—as MCP tools. This facilitates seamless integration of OpenAPI-described APIs into MCP-based workflows.

What's New in 0.2.0

Works with every modern MCP-enabled client we tested. Strict MCP clients can now discover and call tools — the low-level server advertises correct capabilities and no longer crashes during resource/prompt discovery, and a slow spec download no longer crash-loops short-timeout clients. Verified live against the full list of mainstream agent CLIs:

✅ Codex, Gemini, Qwen, Kilocode, opencode — native tool calls over stdio
✅ Vibe — native discovery and read calls (writes were CLI-flaky, not a proxy issue)
✅ Letta — Cloud (via a remote streamable-HTTP MCP URL) and self-hosted (via stdio)

See the client matrix for attach mechanisms, models, and exact results.

📄 Full write-up: Verification case study — what the proxy is, the API + client matrices, and every defect found & fixed.

Prompts and resources are real now — including custom resources. Both MCP surfaces are functional and tested: the summarize_spec / whimsical_blog prompts and the spec_file resource, plus a new ADDITIONAL_RESOURCES env var that serves your own use-case documents (e.g. a NetBox naming policy or an Asana project-layout guide) as MCP resources — see examples/resources/.

Bug fixes (every one live-verified):

MCP client discovery: empty capability set + a crash in resource discovery left strict clients seeing zero tools (#23) — fixed, with a full stdio-handshake test harness.
IGNORE_SSL_TOOLS was ignored by the low-level dispatcher (#14) — fixed (original patch by @robbycochran, #15).
Server crash-loop when a slow spec fetch outran a client's connect timeout (#28) — handshake now answers immediately, spec loads lazily, closed streams exit cleanly.
API_AUTH_TYPE custom schemes (e.g. NetBox Token) sent no auth header at all (#24) — fixed.
TOOL_WHITELIST never matched Slack-style dot paths like /users.list (#27) — fixed.
TOOL_NAME_MAX_LENGTH was not respected, and name-truncation collisions silently dropped tools (#11) — fixed.
Array parameters were emitted without items, which the OpenAI API rejects (#16) — fixed.
EXTRA_HEADERS now accepts a JSON array and literal \n separators, not just real newlines (#17).
Dead Render spec URL (#26) and incomplete ElevenLabs example (#29) — fixed; the GetZep example is documented for self-hosted Zep CE since the hosted endpoint now 401s (#38).
Added a Dockerfile + glama.json for the Glama listing (#13); collapsible README examples + a verified-client/API matrix (#35).

Full environment-variable reference is in Environment Variables.

Overview
Features
Installation
- MCP Ecosystem Integration
Modes of Operation
- FastMCP Mode (Simple Mode)
- Low-Level Mode (Default)
Environment Variables
Verified Clients & Live Results (2026-06-12)
- Tips
Examples — Glama, Fly.io, Render, Slack, GetZep, Virustotal, Notion, Asana, APIs.guru, NetBox, Box, WolframAlpha, WordPress (collapsed)
Troubleshooting
License

Overview

The package offers two operational modes:

Low-Level Mode (Default): Dynamically registers tools corresponding to all valid API endpoints specified in an OpenAPI document (e.g. /chat/completions becomes chat_completions()).
FastMCP Mode (Simple Mode): Provides a streamlined approach by exposing a predefined set of tools (e.g. list_functions() and call_function()) based on static configurations.

Features

Dynamic Tool Generation: Automatically creates MCP tools from OpenAPI endpoint definitions.
Simple Mode Option: Offers a static configuration alternative via FastMCP mode.
OpenAPI Specification Support: Compatible with OpenAPI v3 with potential support for v2.
Flexible Filtering: Allows endpoint filtering through whitelisting by paths or other criteria.
Payload Authentication: Supports custom authentication via JMESPath expressions (e.g. for APIs like Slack that expect tokens in the payload not the HTTP header).
Header Authentication: Uses Bearer by default for API_KEY in the Authorization header, customizable for APIs like Fly.io requiring Api-Key.
MCP Integration: Seamlessly integrates with MCP ecosystems for invoking REST APIs as tools.

Installation

Install the package directly from PyPI using the following command:

uvx mcp-openapi-proxy

MCP Ecosystem Integration

To incorporate mcp-openapi-proxy into your MCP ecosystem configure it within your mcpServers settings. Below is a generic example:

{
    "mcpServers": {
        "mcp-openapi-proxy": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
                "API_KEY": "${API_OPENAPI_KEY}"
            }
        }
    }
}

Refer to the Examples section below for practical configurations tailored to specific APIs.

Modes of Operation

FastMCP Mode (Simple Mode)

Enabled by: Setting the environment variable OPENAPI_SIMPLE_MODE=true.
Description: Exposes a fixed set of tools derived from specific OpenAPI endpoints as defined in the code.
Configuration: Relies on environment variables to specify tool behavior.

Low-Level Mode (Default)

Description: Automatically registers all valid API endpoints from the provided OpenAPI specification as individual tools.
Tool Naming: Derives tool names from normalized OpenAPI paths and methods.
Behavior: Generates tool descriptions from OpenAPI operation summaries and descriptions.

Environment Variables

OPENAPI_SPEC_URL: (Required) The URL to the OpenAPI specification JSON file (e.g. https://example.com/spec.json or file:///path/to/local/spec.json).
OPENAPI_SIMPLE_MODE: (Optional) Set to true to enable FastMCP mode.
TOOL_WHITELIST: (Optional) A comma-separated list of endpoint paths to expose as tools.
ADDITIONAL_RESOURCES: (Optional) Comma-separated name=/path/to/file entries served as extra MCP resources (use-case docs such as naming policies or layout conventions; see examples/resources/).
TOOL_NAME_PREFIX: (Optional) A prefix to prepend to all tool names.
API_KEY: (Optional) Authentication token for the API sent as Bearer <API_KEY> in the Authorization header by default.
API_AUTH_TYPE: (Optional) Overrides the default Bearer Authorization scheme. api-key sends the key in the header named by API_AUTH_HEADER; any other value is used as a custom scheme prefix (e.g. Token for NetBox → Authorization: Token <key>).
STRIP_PARAM: (Optional) JMESPath expression to strip unwanted parameters (e.g. token for Slack).
DEBUG: (Optional) Enables verbose debug logging when set to "true", "1", or "yes".
EXTRA_HEADERS: (Optional) One or more outgoing HTTP headers. Accepts a JSON array (["X-A: 1","X-B: 2"]), one Header: Value per line, or literal \n-separated entries (for configs that cannot embed newlines).
SERVER_URL_OVERRIDE: (Optional) Overrides the base URL from the OpenAPI specification when set, useful for custom deployments.
TOOL_NAME_MAX_LENGTH: (Optional) Truncates tool names to a max length.
Additional Variable: OPENAPI_SPEC_URL_<hash> – a variant for unique per-test configurations (falls back to OPENAPI_SPEC_URL).
IGNORE_SSL_SPEC: (Optional) Set to true to disable SSL certificate verification when fetching the OpenAPI spec.
IGNORE_SSL_TOOLS: (Optional) Set to true to disable SSL certificate verification for API requests made by tools.
API_AUTH_HEADER: (Optional) Header name used when API_AUTH_TYPE=api-key (e.g. x-apikey for VirusTotal, xi-api-key for ElevenLabs). Defaults to Authorization.
OPENAPI_SPEC_FORMAT: (Optional) Set to yaml to parse file:// specs as YAML (remote specs auto-detect). Default json.
OPENAPI_SPEC_CACHE_TTL_SECONDS: (Optional) Live-first disk cache for remote specs: the cached copy is served only when the live fetch fails or stalls (and respawned servers fail fast to it). Default 86400; set 0 to disable.
ENABLE_TOOLS / ENABLE_PROMPTS / ENABLE_RESOURCES: (Optional) Feature gates for the three MCP surfaces in low-level mode; each defaults to enabled. Disabling a feature removes its handlers and its capability advertisement.
CAPABILITIES_TOOLS / CAPABILITIES_PROMPTS / CAPABILITIES_RESOURCES: (Optional) Advertise listChanged on the corresponding capability (for clients that key on it). Default false.

Verified Clients & Live Results (2026-06-12)

The example configurations below were exercised against the live APIs, and the proxy was attached to a range of agent CLIs over stdio MCP. Results from that verification run:

API example results

API example	Tools	Sample call proven	Extra env needed
glama	6	`get_v1_attributes`	none
apis.guru	7	`get_metrics_json`	none
wolframalpha	2	`get_v1_llm_api`	`API_KEY`
virustotal	4	IP report	`API_KEY` + `API_AUTH_TYPE=api-key` + `API_AUTH_HEADER=x-apikey`
asana	73 (whitelist `/workspaces,/projects,/tasks`)	created project + 11 tasks	`SERVER_URL_OVERRIDE` + `API_KEY`
render	52	`get_services`	`API_KEY` (NEW spec URL `render-public-api-1.json`)
notion	4–5 (whitelist `/v1/users,/v1/search` or `/v1/pages`)	page create + title read-back	`SERVER_URL_OVERRIDE` + `EXTRA_HEADERS` (`Notion-Version`) + `API_KEY`
elevenlabs	19	TTS mp3 generated	`SERVER_URL_OVERRIDE` + `API_AUTH_TYPE=api-key` + `API_AUTH_HEADER=xi-api-key`
flyio	34–35	apps + machine health	`API_KEY`
slack	7 (exact dot-path whitelist until #27 fix)	`auth.test` + `postMessage`	`API_KEY`
netbox	9 (whitelist `/ipam/ip-addresses`)	IPAM write + read	`API_KEY` + `API_AUTH_TYPE=Token`
homeassistant	21	`get_config` (200) + `call_service` (light.turn_on, 200)	`SERVER_URL_OVERRIDE` + `API_KEY` (`${HA_TOKEN}`, sent as Bearer)

Client matrix

Agent CLI	Model used (live test)	MCP attach mechanism	Tool calls	Prompts/Resources surfaced to model?
opencode	(CLI default)	`~/.config/opencode/opencode.json` `mcp`	✅ native	prompts: ✅ (slash) · resources: ✅ — most complete ‖
Codex	`gpt-5-codex` (OpenAI API)	`codex exec -c mcp_servers.*`	✅ native	prompts: ❌ low-level · ✅ fastmcp (via `call_function`→`get_prompt`) · resources: ✅ (`read_mcp_resource`) ‖
Kilocode	`kilo-auto/free`	global `settings/mcp_settings.json`	✅ native	prompts: ❌ (no prompt mechanism) · resources: ✅ (`access_mcp_resource`) ‖
Qwen	`agent` group via local LiteLLM gateway	project `.qwen/settings.json`	✅ native (live invoke auth-blocked)	prompts: ✅ (slash `/summarize_spec`) · resources: ❌ (no client support) ‖
Gemini	Google OAuth free tier (CLI default model)	project `.gemini/settings.json` `mcpServers`	✅ native	prompts: interactive slash only · resources: interactive `@` only (neither reaches the model headless) ‖
Vibe	`mistral-medium-3.5`	`~/.vibe/config.toml` `[[mcp_servers]]`	✅ discovery + reads	prompts: ❌ · resources: ❌ (tools-only client) ‖
agy	—	—	❌ headless cannot enable MCP	n/a
letta (cloud / self-hosted)	Letta Cloud / `PUT /v1/tools/mcp/servers`	streamable-HTTP / stdio	✅ (per prior sweep)	unknown — needs a running Letta server to test ‡

How to read the prompts/resources column. MCP has three surfaces — tools, prompts, resources. mcp-openapi-proxy serves all three, advertised by default since 0.3.0. Whether they reach the model is up to the client, and that varies:

‖ re-verified 2026-06-15 against the published 0.3.3 release with no flags set (validating the default-on advertising), driving each real client binary, in both server modes (low-level and FastMCP simple). Per-client results were the same across modes except where noted.

Tools work on every client tested. Prompts→model: opencode & Qwen (slash commands); Gemini interactive-only. Resources→model: opencode, Codex, Kilocode. opencode is the only client that surfaces all three in any mode.

FastMCP simple mode exception: a client with no native prompt surface can still reach prompts through the static call_function→get_prompt indirection. Observed with Codex (prompts ❌ in low-level, ✅ in FastMCP simple mode). Vibe stays tools-only regardless of mode.

‡ unknown — Letta can't be exercised without standing up a Letta server + model; left untested rather than guessed.

Every cell on the proxy side was confirmed via a raw stdio handshake (initialize advertises tools+prompts+resources; prompts/get and resources/read return content). The remaining ❌ are client-side gaps, not proxy limitations.

(All pre-0.3.0 prompt/resource findings were voided — they were measured while advertising defaulted off, so they reflected the server default, not the clients.)

Minimal sanitized configs per client (the no-auth Glama spec is used as the smallest working example; substitute your own spec URL and $YOUR_KEY as needed):

Codex — inline -c mcp_servers.* overrides

codex exec \
  -c 'mcp_servers.glama.command="uvx"' \
  -c 'mcp_servers.glama.args=["mcp-openapi-proxy"]' \
  -c 'mcp_servers.glama.env.OPENAPI_SPEC_URL="https://glama.ai/api/mcp/openapi.json"' \
  "list the available tools"

Gemini — project .gemini/settings.json

{
  "mcpServers": {
    "glama": {
      "command": "uvx",
      "args": ["mcp-openapi-proxy"],
      "env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
    }
  }
}

Qwen — project .qwen/settings.json

{
  "mcpServers": {
    "glama": {
      "command": "uvx",
      "args": ["mcp-openapi-proxy"],
      "env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
    }
  }
}

Kilocode — global settings/mcp_settings.json (use a clean workspace)

{
  "mcpServers": {
    "glama": {
      "command": "uvx",
      "args": ["mcp-openapi-proxy"],
      "env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
    }
  }
}

opencode — ~/.config/opencode/opencode.json mcp block

{
  "mcp": {
    "glama": {
      "type": "local",
      "command": ["uvx", "mcp-openapi-proxy"],
      "environment": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
    }
  }
}

Vibe — ~/.vibe/config.toml [[mcp_servers]]

[[mcp_servers]]
name = "glama"
command = "uvx"
args = ["mcp-openapi-proxy"]

[mcp_servers.env]
OPENAPI_SPEC_URL = "https://glama.ai/api/mcp/openapi.json"

agy (headless) and letta cloud could not attach a stdio MCP server at all, so no config snippet applies: agy provides no way to enable MCP in headless mode, and letta cloud only accepts remote MCP servers.

Tips

Big specs need TOOL_WHITELIST. Large APIs (Asana, Render, Fly.io, Slack, NetBox) expose dozens of endpoints; whitelist the paths you need to keep the tool count manageable for clients.
Dot-style paths need exact whitelist entries for now. Slack-style paths like /chat.postMessage are not matched by prefix whitelisting — list each path exactly (issue #27 / PR #32).
Slow remote specs can crash-loop short-timeout clients. If a client kills the server before a large spec finishes downloading, fetch the spec once and point OPENAPI_SPEC_URL at a local file:// copy (issue #28).
Custom auth schemes are handled via API_AUTH_TYPE (PR #25), e.g. Token for NetBox, or api-key with API_AUTH_HEADER for Virustotal/ElevenLabs-style header keys.

Examples

For testing you can run the uvx command as demonstrated in the examples then interact with the MCP server via JSON-RPC messages to list tools and resources. See the "JSON-RPC Testing" section below.

Each example below is collapsed — click to expand.

Glama Example — the most minimal config: just OPENAPI_SPEC_URL, no auth

Glama offers the most minimal configuration for mcp-openapi-proxy requiring only the OPENAPI_SPEC_URL environment variable. This simplicity makes it ideal for quick testing.

1. Verify the OpenAPI Specification

Retrieve the Glama OpenAPI specification:

curl https://glama.ai/api/mcp/openapi.json

Ensure the response is a valid OpenAPI JSON document.

2. Configure mcp-openapi-proxy for Glama

Add the following configuration to your MCP ecosystem settings:

{
    "mcpServers": {
        "glama": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json"
            }
        }
    }
}

3. Testing

Start the service with:

OPENAPI_SPEC_URL="https://glama.ai/api/mcp/openapi.json" uvx mcp-openapi-proxy

Then refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Fly.io Example — machines API with an API token

Fly.io provides a simple API for managing machines making it an ideal starting point. Obtain an API token from Fly.io documentation.

1. Verify the OpenAPI Specification

Retrieve the Fly.io OpenAPI specification:

curl https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json

Ensure the response is a valid OpenAPI JSON document.

2. Configure mcp-openapi-proxy for Fly.io

Update your MCP ecosystem configuration:

{
    "mcpServers": {
        "flyio": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
                "API_KEY": "<your_flyio_token_here>"
            }
        }
    }
}

OPENAPI_SPEC_URL: Points to the Fly.io OpenAPI specification.
API_KEY: Your Fly.io API token (replace <your_flyio_token_here>).
API_AUTH_TYPE: Set to Api-Key for Fly.io’s header-based authentication (overrides default Bearer).

3. Testing

After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Render Example — manage hosted services with a tool whitelist

Render offers infrastructure hosting that can be managed via an API. The provided configuration file examples/render-claude_desktop_config.json demonstrates how to set up your MCP ecosystem quickly with minimal settings.

1. Verify the OpenAPI Specification

Retrieve the Render OpenAPI specification:

curl https://api-docs.render.com/openapi/render-public-api-1.json

Ensure the response is a valid OpenAPI document.

2. Configure mcp-openapi-proxy for Render

Add the following configuration to your MCP ecosystem settings:

{
    "mcpServers": {
        "render": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://api-docs.render.com/openapi/render-public-api-1.json",
                "TOOL_WHITELIST": "/services,/maintenance",
                "API_KEY": "your_render_token_here"
            }
        }
    }
}

3. Testing

Launch the proxy with your Render configuration:

OPENAPI_SPEC_URL="https://api-docs.render.com/openapi/render-public-api-1.json" TOOL_WHITELIST="/services,/maintenance" API_KEY="your_render_token_here" uvx mcp-openapi-proxy

Then refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Slack Example — payload token stripping via JMESPath (STRIP_PARAM)

Slack’s API showcases stripping unnecessary token payload using JMESPath. Obtain a bot token from Slack API documentation.

1. Verify the OpenAPI Specification

Retrieve the Slack OpenAPI specification:

curl https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json

Ensure it’s a valid OpenAPI JSON document.

2. Configure mcp-openapi-proxy for Slack

Update your configuration:

{
    "mcpServers": {
        "slack": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json",
                "TOOL_WHITELIST": "/chat,/bots,/conversations,/reminders,/files,/users",
                "API_KEY": "<your_slack_bot_token, starts with xoxb>",
                "STRIP_PARAM": "token",
                "TOOL_NAME_PREFIX": "slack_"
            }
        }
    }
}

OPENAPI_SPEC_URL: Slack’s OpenAPI spec URL.
TOOL_WHITELIST: Limits tools to useful endpoint groups (e.g. chat, conversations, users).
API_KEY: Your Slack bot token (e.g. xoxb-..., replace <your_slack_bot_token>).
STRIP_PARAM: Removes the token field from the request payload.
TOOL_NAME_PREFIX: Prepends slack_ to tool names.

3. Testing

After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.

GetZep Example — project-generated spec with Api-Key auth

Note (2026): GetZep's hosted endpoint (api.getzep.com) returns 401 for previously-working keys — the hosted free tier no longer accepts API keys. The example now targets a self-hosted Zep CE: see examples/zep-ce/docker-compose.yml (zep built from source tag v1.0.2 + pgvector/pgvector:pg17; the delisted zepai/zep image must be rebuilt via the official Dockerfile.ce). Auth quirk: Zep's scheme is literally Api-Key, which collides with the proxy's special api-key mode — use API_AUTH_TYPE=api-key with API_KEY="Api-Key <your-secret>". Live-verified: 8 tools via TOOL_WHITELIST=/sessions; session create + read-back through the bridge.

GetZep offers a free cloud API for memory management with detailed endpoints. Since GetZep did not provide an official OpenAPI specification, this project includes a generated spec hosted on GitHub for convenience. Users can similarly generate OpenAPI specs for any REST API and reference them locally (e.g. file:///path/to/spec.json). Obtain an API key from GetZep's documentation.

1. Verify the OpenAPI Specification

Retrieve the project-provided GetZep OpenAPI specification:

curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json

Ensure it’s a valid OpenAPI JSON document. Alternatively, generate your own spec and use a file:// URL to reference a local file.

2. Configure mcp-openapi-proxy for GetZep

Update your configuration:

{
    "mcpServers": {
        "getzep": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json",
                "TOOL_WHITELIST": "/sessions",
                "API_KEY": "<your_getzep_api_key>",
                "API_AUTH_TYPE": "Api-Key",
                "TOOL_NAME_PREFIX": "zep_"
            }
        }
    }
}

OPENAPI_SPEC_URL: Points to the project-provided GetZep Swagger spec (or use file:///path/to/your/spec.json for a local file).
TOOL_WHITELIST: Limits to /sessions endpoints.
API_KEY: Your GetZep API key.
API_AUTH_TYPE: Uses Api-Key for header-based authentication.
TOOL_NAME_PREFIX: Prepends zep_ to tool names.

3. Testing

After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Virustotal Example — YAML spec + custom x-apikey auth header

This example demonstrates:

Using a YAML OpenAPI specification file
Using custom HTTP auth header, "x-apikey"

1. Verify the OpenAPI Specification

Retrieve the Virustotal OpenAPI specification:

curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml

Ensure that the response is a valid OpenAPI YAML document.

2. Configure mcp-openapi-proxy for Virustotal

Add the following configuration to your MCP ecosystem settings:

{
    "mcpServers": {
        "virustotal": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml",
                "EXTRA_HEADERS": "x-apikey: ${VIRUSTOTAL_API_KEY}",
                "OPENAPI_SPEC_FORMAT": "yaml"
            }
        }
    }
}

Key configuration points:

By default, the proxy expects a JSON specification and sends the API key with a Bearer prefix.
To use a YAML OpenAPI specification, include OPENAPI_SPEC_FORMAT="yaml".
Note: VirusTotal requires a special authentication header; EXTRA_HEADERS is used to transmit the API key as "x-apikey: ${VIRUSTOTAL_API_KEY}".

3. Testing

Launch the proxy with the Virustotal configuration:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml" API_KEY="your_virustotal_api_key" API_AUTH_HEADER="x-apikey" API_AUTH_TYPE="" OPENAPI_SPEC_FORMAT="yaml" uvx mcp-openapi-proxy

After starting the service, refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Notion Example — API version header via EXTRA_HEADERS

Notion’s API requires specifying a particular version via HTTP headers. This example uses the EXTRA_HEADERS environment variable to include the required header, and focuses on verifying the OpenAPI specification.

1. Verify the OpenAPI Specification

Retrieve the Notion OpenAPI specification:

curl https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml

Ensure the response is a valid YAML document.

2. Configure mcp-openapi-proxy for Notion

Add the following configuration to your MCP ecosystem settings:

{
  "mcpServers": {
    "notion": {
      "command": "uvx",
      "args": [
        "mcp-openapi-proxy"
      ],
      "env": {
          "API_KEY": "ntn_<your_key>",
          "OPENAPI_SPEC_URL": "https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml",
          "SERVER_URL_OVERRIDE": "https://api.notion.com",
          "EXTRA_HEADERS": "Notion-Version: 2022-06-28"
      }
    }
  }
}

3. Testing

Launch the proxy with the Notion configuration:

OPENAPI_SPEC_URL="https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml" SERVER_URL_OVERRIDE="https://api.notion.com" EXTRA_HEADERS="Notion-Version: 2022-06-28" API_KEY="ntn_<your_key>" uvx mcp-openapi-proxy

After starting the service, refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Asana Example — workspaces/tasks/projects with a whitelist and SERVER_URL_OVERRIDE

Asana provides a rich set of endpoints for managing workspaces, tasks, projects, and users. The integration tests demonstrate usage of endpoints such as GET /workspaces, GET /tasks, and GET /projects.

1. Verify the OpenAPI Specification

Retrieve the Asana OpenAPI specification:

curl https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml

Ensure the response is a valid YAML (or JSON) document.

2. Configure mcp-openapi-proxy for Asana

Add the following configuration to your MCP ecosystem settings:

{
  "mcpServers": {
    "asana": {
      "command": "uvx",
      "args": [
        "mcp-openapi-proxy"
      ],
      "env": {
        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml",
        "SERVER_URL_OVERRIDE": "https://app.asana.com/api/1.0",
        "TOOL_WHITELIST": "/workspaces,/tasks,/projects,/users",
        "API_KEY": "${ASANA_API_KEY}"
      }
    }
  }
}

Note: Most Asana API endpoints require authentication. Set ASANA_API_KEY in your environment or .env file with a valid token.

3. Testing

Start the service with:

ASANA_API_KEY="<your_asana_api_key>" OPENAPI_SPEC_URL="https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml" SERVER_URL_OVERRIDE="https://app.asana.com/api/1.0" TOOL_WHITELIST="/workspaces,/tasks,/projects,/users" uvx mcp-openapi-proxy

You can then use the MCP ecosystem to list and invoke tools for endpoints like /dcim/devices/ and /ipam/ip-addresses/.

APIs.guru Example — directory of thousands of public OpenAPI definitions, no auth

APIs.guru provides a directory of OpenAPI definitions for thousands of public APIs. This example shows how to use mcp-openapi-proxy to expose the APIs.guru directory as MCP tools.

1. Verify the OpenAPI Specification

Retrieve the APIs.guru OpenAPI specification:

curl https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml

Ensure the response is a valid OpenAPI YAML document.

2. Configure mcp-openapi-proxy for APIs.guru

Add the following configuration to your MCP ecosystem settings:

{
    "mcpServers": {
        "apisguru": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml"
            }
        }
    }
}

3. Testing

Start the service with:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml" uvx mcp-openapi-proxy

You can then use the MCP ecosystem to list and invoke tools such as listAPIs, getMetrics, and getProviders that are defined in the APIs.guru directory.

NetBox Example — IPAM/DCIM API with Token auth

NetBox is an open-source IP address management (IPAM) and data center infrastructure management (DCIM) tool. This example demonstrates how to use mcp-openapi-proxy to expose the NetBox API as MCP tools.

1. Verify the OpenAPI Specification

Retrieve the NetBox OpenAPI specification:

curl https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml

Ensure the response is a valid OpenAPI YAML document.

2. Configure mcp-openapi-proxy for NetBox

Add the following configuration to your MCP ecosystem settings:

{
    "mcpServers": {
        "netbox": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml",
                "API_KEY": "${NETBOX_API_KEY}"
            }
        }
    }
}

Note: Most NetBox API endpoints require authentication. Set NETBOX_API_KEY in your environment or .env file with a valid token.

3. Testing

Start the service with:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml" API_KEY="$NETBOX_API_KEY" uvx mcp-openapi-proxy

You can then use the MCP ecosystem to list and invoke tools for endpoints like /dcim/devices/ and /ipam/ip-addresses/.

Box API Example — developer-token access to Box content

You can integrate the Box Platform API using your own developer token for authenticated access to your Box account. This example demonstrates how to expose Box API endpoints as MCP tools.

Example config: `examples/box-claude_desktop_config.json`

"env": {
  "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/box.com/2.0.0/openapi.yaml",
  "TOOL_WHITELIST": "/folders/{folder_id}/items,/files/{file_id},/search,/recent_items",
  "API_KEY": "${BOX_API_KEY}"
}

Set your Box developer token as an environment variable in .env:
```
BOX_API_KEY=your_box_developer_token
```

Or run the proxy with a one-liner:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/box.com/2.0.0/openapi.yaml" API_KEY="$BOX_API_KEY" uvx mcp-openapi-proxy

You can now use the MCP ecosystem to list and invoke Box API tools. For integration tests, see tests/integration/test_box_integration.py.

Note: developer api keys for free tier box users are limited to 60 minutes :(.

WolframAlpha API Example — computation API keyed by App ID

You can integrate the WolframAlpha API using your own App ID for authenticated access. This example demonstrates how to expose WolframAlpha API endpoints as MCP tools.

Example config: `examples/wolframalpha-claude_desktop_config.json`

{
  "mcpServers": {
    "wolframalpha": {
      "command": "uvx",
      "args": [
        "mcp-openapi-proxy"
      ],
      "env": {
        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/wolframalpha.com/v0.1/openapi.yaml",
        "API_KEY": "${WOLFRAM_LLM_APP_ID}"
      }
    }
  }
}

Set your WolframAlpha App ID as an environment variable in .env:
```
WOLFRAM_LLM_APP_ID=your_wolfram_app_id
```

Or run the proxy with a one-liner:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/wolframalpha.com/v0.1/openapi.yaml" API_KEY="$WOLFRAM_LLM_APP_ID" uvx mcp-openapi-proxy

You can now use the MCP ecosystem to list and invoke WolframAlpha API tools. For integration tests, see tests/integration/test_wolframalpha_integration.py.

Letta (self-hosted + Cloud) — agent platform; stdio for self-hosted, authenticated remote HTTP for Cloud

Letta runs agents on a server, so attachment differs by deployment:

Self-hosted Letta accepts a stdio MCP server via PUT /v1/tools/mcp/servers — no network exposure.
Letta Cloud rejects stdio and needs a remote streamable-HTTP MCP URL behind authentication.

Both were verified live (an agent autonomously called get_v1_attributes from the Glama spec through the proxy). Full setup for both paths, including the supergateway wrapper and the security note for the Cloud endpoint, is in examples/letta/README.md.

WordPress Example — publish to a real WordPress blog from any MCP agent

This example turns the WordPress REST API into MCP tools so an agent can create, read, update, and trash blog posts. It is the example behind a real-world demonstration: a fleet of agent CLIs published to the live blog at matthewhand.mywebcommunity.org through this proxy — see the write-up “Turning Any API into Agent Tools”, itself posted via the proxy.

Example config — examples/wordpress-claude_desktop_config.json:

{
  "mcpServers": {
    "wordpress": {
      "command": "uvx",
      "args": ["mcp-openapi-proxy"],
      "env": {
        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/main/examples/wordpress-openapi.json",
        "SERVER_URL_OVERRIDE": "https://your-site.example.com/wp-json",
        "EXTRA_HEADERS": "Authorization: Basic BASE64_OF_USERNAME_COLON_APPLICATION_PASSWORD",
        "IGNORE_SSL_TOOLS": "false",
        "TOOL_WHITELIST": "/wp/v2/posts"
      }
    }
  }
}

Exposed tools (from the bundled examples/wordpress-openapi.json): get_wp_v2_posts, post_wp_v2_posts (create), get_wp_v2_posts_by_id, post_wp_v2_posts_by_id (update), and delete_wp_v2_posts_by_id (trash) — the full post lifecycle.

Auth — use a WordPress Application Password, not your login password. WordPress REST rejects login passwords for Basic auth. In wp-admin → Users → (your user) → Application Passwords, create one, then base64-encode username:application-password for the EXTRA_HEADERS value:

printf 'myuser:xxxx xxxx xxxx xxxx xxxx xxxx' | base64 -w0

Tips: set IGNORE_SSL_TOOLS=true only if your host serves a self-signed/mismatched cert; give each agent its own (revocable) application password; keep TOOL_WHITELIST=/wp/v2/posts so the agent can touch only posts.

Home Assistant Example — control your smart home; call_service needs the >= 0.3.3 path-param body fix

Exposes a generic slice of the Home Assistant REST API (21 operations) — read state (get_config, list_states, get_state, list_services, get_history/get_history_now, get_logbook, list_calendars, get_calendar_events, get_camera_image, get_error_log, list_components, list_events, get_api_status) and act (call_service, set_state, delete_state, fire_event, render_template, check_config, handle_intent). HA ships no official OpenAPI spec, so this is hand-rolled from the official docs.

1. Verify the OpenAPI specification

curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json

2. Configure mcp-openapi-proxy for Home Assistant

{
    "mcpServers": {
        "homeassistant": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json",
                "SERVER_URL_OVERRIDE": "http://homeassistant.local:8123",
                "API_KEY": "${HA_TOKEN}"
            }
        }
    }
}

Key configuration points:

SERVER_URL_OVERRIDE — your instance base URL, e.g. http://homeassistant.local:8123 or http://<ha-host>:8123.
HA_TOKEN — a Home Assistant long-lived access token (Profile → Long-Lived Access Tokens), passed via API_KEY; the proxy sends it as Authorization: Bearer <token> (its default scheme), so no EXTRA_HEADERS needed. Never commit the token; keep it in your environment.
call_service requires mcp-openapi-proxy >= 0.3.3: earlier versions leaked the {domain}/{service} path params into the JSON body, which Home Assistant rejects with HTTP 400.

3. Testing

get_config should return your HA configuration (200). call_service for light/turn_on with body {"entity_id": "light.kitchen"} should return 200 — the path params land in the URL (/api/services/light/turn_on), not the body.

Troubleshooting

JSON-RPC Testing

For alternative testing, you can interact with the MCP server via JSON-RPC. After starting the server, paste the following initialization message:

{"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-ai","version":"0.1.0"}},"jsonrpc":"2.0","id":0}

Expected response:

{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2024-11-05","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"sqlite","version":"0.1.0"}}}

Then paste these follow-up messages:

{"method":"notifications/initialized","jsonrpc":"2.0"}
{"method":"resources/list","params":{},"jsonrpc":"2.0","id":1}
{"method":"tools/list","params":{},"jsonrpc":"2.0","id":2}

Missing OPENAPI_SPEC_URL: Ensure it’s set to a valid OpenAPI JSON URL or local file path.
Invalid Specification: Verify the OpenAPI document is standard-compliant.
Tool Filtering Issues: Check TOOL_WHITELIST matches desired endpoints.
Authentication Errors: Confirm API_KEY and API_AUTH_TYPE are correct.
Logging: Set DEBUG=true for detailed output to stderr.
Test Server: Run directly:

uvx mcp-openapi-proxy

License

MIT License

MCP OpenAPI ProxyOpenAPI Proxy

mcp-openapi-proxy

What's New in 0.2.0

Table of Contents

Overview

Features

Installation

MCP Ecosystem Integration

Modes of Operation

FastMCP Mode (Simple Mode)

Low-Level Mode (Default)

Environment Variables

Verified Clients & Live Results (2026-06-12)

API example results

Client matrix

Tips

Examples

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for Glama

3. Testing

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for Fly.io

3. Testing

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for Render

3. Testing

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for Slack

3. Testing

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for GetZep

3. Testing

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for Virustotal

3. Testing

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for Notion

3. Testing

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for Asana

3. Testing

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for APIs.guru

3. Testing

1. Verify the OpenAPI Specification

2. Configure mcp-openapi-proxy for NetBox

3. Testing

Example config: examples/box-claude_desktop_config.json

Example config: examples/wolframalpha-claude_desktop_config.json

1. Verify the OpenAPI specification

2. Configure mcp-openapi-proxy for Home Assistant

3. Testing

Troubleshooting

JSON-RPC Testing

License

Example config: `examples/box-claude_desktop_config.json`

Example config: `examples/wolframalpha-claude_desktop_config.json`