Agenten stärken
Installation vom Herausgeber. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
Noch kein paketiertes Release in der Registry. Folgen Sie der README des Repositorys.
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
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.
v0.4.0 — tagged September 6, 2026; GitHub Release published October 15, 2026 (AEDT): MCP SDK 2.x / protocol 2026-07-28, with native stateless Streamable HTTP and legacy stdio support.
MCP server that dynamically exposes REST APIs defined by OpenAPI specs. Dual-stack MCP 1.x/2.x with native Streamable HTTP.
MCP 2026-07-28 (SDK 2.x). The proxy is dual-stack: modern clients send
self-contained requests (no initialize, no Mcp-Session-Id) and list results
carry ttlMs / cacheScope. Legacy stdio clients that still handshake keep
working. Native Streamable HTTP is available with MCP_TRANSPORT=streamable-http
and is stateless — round-robin load balancing needs no sticky sessions.
See docs/MIGRATION-0.4.md for breaking changes, new
env vars, and gateway cutover notes. 0.3.4 remains the last release on
mcp 1.x (mcp>=1.2.0,<2).
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:
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):
IGNORE_SSL_TOOLS was ignored by the low-level dispatcher (#14) — fixed (original patch by @robbycochran, #15).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.items, which the OpenAI API rejects (#16) — fixed.EXTRA_HEADERS now accepts a JSON array and literal \n separators, not just real newlines (#17).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.
The package offers two operational modes:
/chat/completions becomes chat_completions()).list_functions() and call_function()) based on static configurations.annotations (title, plus readOnlyHint / idempotentHint for GET and clearly read-ish POST, or destructiveHint for other methods) so clients such as Gemini Spark see the same fingerprint as Notion/Linear.Bearer by default for API_KEY in the Authorization header, customizable for APIs like Fly.io requiring Api-Key.Install the package directly from PyPI using the following command:
uvx mcp-openapi-proxy
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.
OPENAPI_SIMPLE_MODE=true.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". Native Streamable HTTP also emits one INFO line per inbound JSON-RPC method (mcp rpc method=tools/list, mcp rpc method=tools/call name=…) without arguments or Authorization.
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.
PROMPT: (Optional) JSON object that registers one extra MCP prompt next to summarize_spec and whimsical_blog, in both low-level and simple mode. Example: {"name":"asana_prompt","description":"Asana helper","messages":[{"user":"What is Asana?","assistant":"Asana is a work management platform."}]}. Each message may include user, assistant, or both. Invalid JSON is logged and ignored. summarize_spec and whimsical_blog are reserved names. Restart the server after changing it. Low-level mode also requires prompts to stay enabled (ENABLE_PROMPTS, default on). Custom prompt content is returned to connected MCP clients: do not put credentials or other private data in PROMPT, and protect public HTTP ingress with authentication and host/origin controls.
CAPABILITIES_TOOLS / CAPABILITIES_PROMPTS / CAPABILITIES_RESOURCES: (Optional) Advertise listChanged on the corresponding capability (for clients that key on it). Default false.
MCP_SERVER_NAME: (Optional) Identity advertised in serverInfo / server/discover. Set this to the proxied API (e.g. gpt-terminal-plus, flyio) so multiple instances are not all called openapi-proxy. Falls back to the OpenAPI file stem or spec-URL host, then openapi-proxy.
MCP_SERVER_TITLE / MCP_SERVER_DESCRIPTION: (Optional) Display title and description alongside the name.
MCP_TRANSPORT: (Optional) stdio (default) or streamable-http for native stateless Streamable HTTP (MCP 2026-07-28; no Mcp-Session-Id).
MCP_HOST / MCP_PORT / MCP_PATH: (Optional) HTTP bind address (127.0.0.1), port (8000), and path (/mcp) when MCP_TRANSPORT=streamable-http. Native Streamable HTTP also serves GET /healthz → {"ok":true,"name":<MCP_SERVER_NAME or fallback>,"port":<MCP_PORT>} without taking the MCP request lock (no spec fetch, no initialize).
MCP_JSON_RESPONSE: (Optional) true (default) returns JSON instead of SSE on Streamable HTTP.
MCP_LIST_TTL_MS / MCP_READ_TTL_MS: (Optional) ttlMs for list results (default 60000) and resources/read (default 5000).
MCP_ALLOWED_HOSTS: (Optional) Comma-separated Host allow-list for DNS-rebinding protection. Default * (protection off — typical behind nginx).
MCP_REQUEST_STATE_KEY: (Optional) Shared HMAC key so MRTR requestState verifies across instances. Unset = process-local.
Unreleased on main (not in tagged/PyPI v0.4.0): The next two raw-command logging settings are available only in newer source.
MCP_LOG_RAW_COMMANDS: (Optional, default off) 1/true/yes adds one extra INFO record per shell-execution tool call, emitted before the command runs:
mcp raw-command tool=post_command_execute_shell
cd /srv/app && npm run build # <- the verbatim command, unmodified
The command is logged byte-for-byte — whitespace, blank lines, tabs and quoting are preserved; nothing is normalised, reconstructed, or redacted. The existing mcp rpc method=… name=… line is unchanged and still the only record when this is off. ⚠️ This can write secrets into your logs: shell commands routinely carry credentials (export TOKEN=…, curl -H 'Authorization: Bearer …', ssh/psql invocations). It is opt-in for that reason — enable it only where the log sink is trusted, and scrub or rotate the log afterwards. Only the command body is dumped, never Authorization headers or unrelated tool arguments. Scoped to the allow-list below; not a general tool-argument dump.
MCP_LOG_RAW_COMMAND_TOOLS: (Optional) Comma-separated tool names eligible for raw-command logging, overriding the default post_command_execute_shell,executeShell. Entries that are not valid tool names are ignored. Use this when a new terminal-style upstream lands.
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:
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_promptindirection. 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 (
initializeadvertises tools+prompts+resources;prompts/getandresources/readreturn 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 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"
{
"mcpServers": {
"glama": {
"command": "uvx",
"args": ["mcp-openapi-proxy"],
"env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
}
}
}
{
"mcpServers": {
"glama": {
"command": "uvx",
"args": ["mcp-openapi-proxy"],
"env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
}
}
}
{
"mcpServers": {
"glama": {
"command": "uvx",
"args": ["mcp-openapi-proxy"],
"env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
}
}
}
{
"mcp": {
"glama": {
"type": "local",
"command": ["uvx", "mcp-openapi-proxy"],
"environment": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
}
}
}
[[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.
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./chat.postMessage are not matched by prefix whitelisting — list each path exactly (issue #27 / PR #32).OPENAPI_SPEC_URL at a local file:// copy (issue #28).API_AUTH_TYPE (PR #25), e.g. Token for NetBox, or api-key with API_AUTH_HEADER for Virustotal/ElevenLabs-style header keys.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 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.
Retrieve the Glama OpenAPI specification:
curl https://glama.ai/api/mcp/openapi.json
Ensure the response is a valid OpenAPI JSON document.
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"
}
}
}
}
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 provides a simple API for managing machines making it an ideal starting point. Obtain an API token from Fly.io documentation.
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.
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>"
}
}
}
}
<your_flyio_token_here>).Api-Key for Fly.io’s header-based authentication (overrides default Bearer).After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.
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.
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.
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"
}
}
}
}
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’s API showcases stripping unnecessary token payload using JMESPath. Obtain a bot token from Slack API documentation.
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.
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_"
}
}
}
}
xoxb-..., replace <your_slack_bot_token>).slack_ to tool names.After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.
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: seeexamples/zep-ce/docker-compose.yml(zep built from source tag v1.0.2 +pgvector/pgvector:pg17; the delistedzepai/zepimage must be rebuilt via the officialDockerfile.ce). Auth quirk: Zep's scheme is literallyApi-Key, which collides with the proxy's specialapi-keymode — useAPI_AUTH_TYPE=api-keywithAPI_KEY="Api-Key <your-secret>". Live-verified: 8 tools viaTOOL_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.
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.
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_"
}
}
}
}
file:///path/to/your/spec.json for a local file)./sessions endpoints.Api-Key for header-based authentication.zep_ to tool names.After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.
This example demonstrates:
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.
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:
OPENAPI_SPEC_FORMAT="yaml".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’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.
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.
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"
}
}
}
}
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 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.
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.
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.
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 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.
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.
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"
}
}
}
}
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 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.
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.
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.
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/.
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.
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 :(.
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.
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 runs agents on a server, so attachment differs by deployment:
PUT /v1/tools/mcp/servers — no network exposure.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.
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.
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.
curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json
{
"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.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.
For legacy stdio testing, you can interact with the MCP server via JSON-RPC. After starting the server, send the following initialization message. Native Streamable HTTP in v0.4.0 uses self-contained requests and does not require an initialize handshake; see the migration guide:
{"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-ai","version":"0.1.0"}},"jsonrpc":"2.0","id":0}
The response should contain a JSON-RPC result with a negotiated protocolVersion, advertised capabilities, and serverInfo identifying this proxy (not sqlite). Exact names, versions and capabilities depend on the active SDK, configuration and client; the old fixed example did not describe this project's response.
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}
TOOL_WHITELIST matches desired endpoints.API_KEY and API_AUTH_TYPE are correct.DEBUG=true for detailed output to stderr. On native Streamable HTTP (MCP_TRANSPORT=streamable-http), INFO always includes mcp rpc method=… (and name= for tools/call) so POST /mcp 200 can be attributed without enabling DEBUG.uvx mcp-openapi-proxy
MCP server that dynamically exposes REST APIs defined by OpenAPI specs. Dual-stack MCP 1.x/2.x with native Streamable HTTP.
Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
MCP Openapi Proxy läuft lokal über stdio.
Zuletzt geprüft: 2026-11-05. MCP server that dynamically exposes REST APIs defined by OpenAPI specs. Dual-stack MCP 1.x/2.x with native Streamable HTTP.
