Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/matthewhand/mcp-openapi-proxy with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/matthewhand/mcp-openapi-proxy'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/matthewhand--mcp-openapi-proxy/badge.svg)](/listings/matthewhand--mcp-openapi-proxy)

HTML

<a href="/listings/matthewhand--mcp-openapi-proxy"><img src="/api/listings/matthewhand--mcp-openapi-proxy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,039 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ![OpenAPI endpoints become LLM tools through MCP OpenAPI Proxy](docs/assets/mcp-openapi-proxy-banner.png)
  2. # mcp-openapi-proxy
  3. **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.
  4. **v0.4.0 — tagged September 6, 2026; [GitHub Release published October 15, 2026 (AEDT)](https://github.com/matthewhand/mcp-openapi-proxy/releases/tag/v0.4.0):** MCP SDK 2.x / protocol 2026-07-28, with native stateless Streamable HTTP and legacy stdio support.
  5. ## What's New in 0.4.0
  6. **MCP 2026-07-28 (SDK 2.x).** The proxy is dual-stack: modern clients send
  7. self-contained requests (no `initialize`, no `Mcp-Session-Id`) and list results
  8. carry `ttlMs` / `cacheScope`. Legacy stdio clients that still handshake keep
  9. working. Native Streamable HTTP is available with `MCP_TRANSPORT=streamable-http`
  10. and is stateless — round-robin load balancing needs no sticky sessions.
  11. See [docs/MIGRATION-0.4.md](docs/MIGRATION-0.4.md) for breaking changes, new
  12. env vars, and gateway cutover notes. **0.3.4** remains the last release on
  13. mcp 1.x (`mcp>=1.2.0,<2`).
  14. ## What's New in 0.2.0
  15. **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:
  16. - ✅ **Codex**, **Gemini**, **Qwen**, **Kilocode**, **opencode** — native tool calls over stdio
  17. - ✅ **Vibe** — native discovery and read calls (writes were CLI-flaky, not a proxy issue)
  18. - ✅ **Letta** — Cloud (via a remote streamable-HTTP MCP URL) and self-hosted (via stdio)
  19. See the [client matrix](#client-matrix) for attach mechanisms, models, and exact results.
  20. > 📄 Full write-up: [**Verification case study**](docs/verification-case-study.md) — what the proxy is, the API + client matrices, and every defect found & fixed.
  21. **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/`.
  22. **Bug fixes (every one live-verified):**
  23. - 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.
  24. - `IGNORE_SSL_TOOLS` was ignored by the low-level dispatcher (#14) — fixed (original patch by [@robbycochran](https://github.com/robbycochran), #15).
  25. - 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.
  26. - `API_AUTH_TYPE` custom schemes (e.g. NetBox `Token`) sent **no auth header at all** (#24) — fixed.
  27. - `TOOL_WHITELIST` never matched Slack-style dot paths like `/users.list` (#27) — fixed.
  28. - `TOOL_NAME_MAX_LENGTH` was not respected, and name-truncation collisions silently dropped tools (#11) — fixed.
  29. - Array parameters were emitted without `items`, which the OpenAI API rejects (#16) — fixed.
  30. - `EXTRA_HEADERS` now accepts a JSON array and literal `\n` separators, not just real newlines (#17).
  31. - 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).
  32. - Added a `Dockerfile` + `glama.json` for the Glama listing (#13); collapsible README examples + a verified-client/API matrix (#35).
  33. Full environment-variable reference is in [Environment Variables](#environment-variables).
  34. ## Table of Contents
  35. - [Overview](#overview)
  36. - [Features](#features)
  37. - [Installation](#installation)
  38. - [MCP Ecosystem Integration](#mcp-ecosystem-integration)
  39. - [Modes of Operation](#modes-of-operation)
  40. - [FastMCP Mode (Simple Mode)](#fastmcp-mode-simple-mode)
  41. - [Low-Level Mode (Default)](#low-level-mode-default)
  42. - [Environment Variables](#environment-variables)
  43. - [Verified Clients & Live Results (2026-06-12)](#verified-clients--live-results-2026-06-12)
  44. - [Tips](#tips)
  45. - [Examples](#examples) — Glama, Fly.io, Render, Slack, GetZep, Virustotal, Notion, Asana, APIs.guru, NetBox, Box, WolframAlpha, WordPress (collapsed)
  46. - [Troubleshooting](#troubleshooting)
  47. - [License](#license)
  48. ## Overview
  49. The package offers two operational modes:
  50. - **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()`).
  51. - **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.
  52. ## Features
  53. - **Dynamic Tool Generation:** Automatically creates MCP tools from OpenAPI endpoint definitions.
  54. - **Tool Annotations:** Every OpenAPI-derived tool includes MCP `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.
  55. - **Simple Mode Option:** Offers a static configuration alternative via FastMCP mode.
  56. - **OpenAPI Specification Support:** Compatible with OpenAPI v3 with potential support for v2.
  57. - **Flexible Filtering:** Allows endpoint filtering through whitelisting by paths or other criteria.
  58. - **Payload Authentication:** Supports custom authentication via JMESPath expressions (e.g. for APIs like Slack that expect tokens in the payload not the HTTP header).
  59. - **Header Authentication:** Uses `Bearer` by default for `API_KEY` in the Authorization header, customizable for APIs like Fly.io requiring `Api-Key`.
  60. - **MCP Integration:** Seamlessly integrates with MCP ecosystems for invoking REST APIs as tools.
  61. ## Installation
  62. Install the package directly from PyPI using the following command:
  63. ```bash
  64. uvx mcp-openapi-proxy
  65. ```
  66. ### MCP Ecosystem Integration
  67. To incorporate **mcp-openapi-proxy** into your MCP ecosystem configure it within your `mcpServers` settings. Below is a generic example:
  68. ```json
  69. {
  70. "mcpServers": {
  71. "mcp-openapi-proxy": {
  72. "command": "uvx",
  73. "args": ["mcp-openapi-proxy"],
  74. "env": {
  75. "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
  76. "API_KEY": "${API_OPENAPI_KEY}"
  77. }
  78. }
  79. }
  80. }
  81. ```
  82. Refer to the **Examples** section below for practical configurations tailored to specific APIs.
  83. ## Modes of Operation
  84. ### FastMCP Mode (Simple Mode)
  85. - **Enabled by:** Setting the environment variable `OPENAPI_SIMPLE_MODE=true`.
  86. - **Description:** Exposes a fixed set of tools derived from specific OpenAPI endpoints as defined in the code.
  87. - **Configuration:** Relies on environment variables to specify tool behavior.
  88. ### Low-Level Mode (Default)
  89. - **Description:** Automatically registers all valid API endpoints from the provided OpenAPI specification as individual tools.
  90. - **Tool Naming:** Derives tool names from normalized OpenAPI paths and methods.
  91. - **Behavior:** Generates tool descriptions from OpenAPI operation summaries and descriptions.
  92. ## Environment Variables
  93. - `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`).
  94. - `OPENAPI_SIMPLE_MODE`: (Optional) Set to `true` to enable FastMCP mode.
  95. - `TOOL_WHITELIST`: (Optional) A comma-separated list of endpoint paths to expose as tools.
  96. - `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/`).
  97. - `TOOL_NAME_PREFIX`: (Optional) A prefix to prepend to all tool names.
  98. - `API_KEY`: (Optional) Authentication token for the API sent as `Bearer <API_KEY>` in the Authorization header by default.
  99. - `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>`).
  100. - `STRIP_PARAM`: (Optional) JMESPath expression to strip unwanted parameters (e.g. `token` for Slack).
  101. - `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.
  102. - `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).
  103. - `SERVER_URL_OVERRIDE`: (Optional) Overrides the base URL from the OpenAPI specification when set, useful for custom deployments.
  104. - `TOOL_NAME_MAX_LENGTH`: (Optional) Truncates tool names to a max length.
  105. - Additional Variable: `OPENAPI_SPEC_URL_<hash>` – a variant for unique per-test configurations (falls back to `OPENAPI_SPEC_URL`).
  106. - `IGNORE_SSL_SPEC`: (Optional) Set to `true` to disable SSL certificate verification when fetching the OpenAPI spec.
  107. - `IGNORE_SSL_TOOLS`: (Optional) Set to `true` to disable SSL certificate verification for API requests made by tools.
  108. - `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`.
  109. - `OPENAPI_SPEC_FORMAT`: (Optional) Set to `yaml` to parse `file://` specs as YAML (remote specs auto-detect). Default `json`.
  110. - `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.
  111. - `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.
  112. - `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.
  113. - `CAPABILITIES_TOOLS` / `CAPABILITIES_PROMPTS` / `CAPABILITIES_RESOURCES`: (Optional) Advertise `listChanged` on the corresponding capability (for clients that key on it). Default `false`.
  114. - `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`.
  115. - `MCP_SERVER_TITLE` / `MCP_SERVER_DESCRIPTION`: (Optional) Display title and description alongside the name.
  116. - `MCP_TRANSPORT`: (Optional) `stdio` (default) or `streamable-http` for native stateless Streamable HTTP (MCP 2026-07-28; no `Mcp-Session-Id`).
  117. - `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`).
  118. - `MCP_JSON_RESPONSE`: (Optional) `true` (default) returns JSON instead of SSE on Streamable HTTP.
  119. - `MCP_LIST_TTL_MS` / `MCP_READ_TTL_MS`: (Optional) `ttlMs` for list results (default `60000`) and `resources/read` (default `5000`).
  120. - `MCP_ALLOWED_HOSTS`: (Optional) Comma-separated Host allow-list for DNS-rebinding protection. Default `*` (protection off — typical behind nginx).
  121. - `MCP_REQUEST_STATE_KEY`: (Optional) Shared HMAC key so MRTR `requestState` verifies across instances. Unset = process-local.
  122. **Unreleased on `main` (not in tagged/PyPI v0.4.0):** The next two raw-command logging settings are available only in newer source.
  123. - `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:
  124. ```text
  125. mcp raw-command tool=post_command_execute_shell
  126. cd /srv/app && npm run build # <- the verbatim command, unmodified
  127. ```
  128. 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.
  129. - `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.
  130. ## Verified Clients & Live Results (2026-06-12)
  131. 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:
  132. ### API example results
  133. | API example | Tools | Sample call proven | Extra env needed |
  134. |---|---|---|---|
  135. | glama | 6 | `get_v1_attributes` | none |
  136. | apis.guru | 7 | `get_metrics_json` | none |
  137. | wolframalpha | 2 | `get_v1_llm_api` | `API_KEY` |
  138. | virustotal | 4 | IP report | `API_KEY` + `API_AUTH_TYPE=api-key` + `API_AUTH_HEADER=x-apikey` |
  139. | asana | 73 (whitelist `/workspaces,/projects,/tasks`) | created project + 11 tasks | `SERVER_URL_OVERRIDE` + `API_KEY` |
  140. | render | 52 | `get_services` | `API_KEY` (NEW spec URL `render-public-api-1.json`) |
  141. | 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` |
  142. | elevenlabs | 19 | TTS mp3 generated | `SERVER_URL_OVERRIDE` + `API_AUTH_TYPE=api-key` + `API_AUTH_HEADER=xi-api-key` |
  143. | flyio | 34–35 | apps + machine health | `API_KEY` |
  144. | slack | 7 (exact dot-path whitelist until #27 fix) | `auth.test` + `postMessage` | `API_KEY` |
  145. | netbox | 9 (whitelist `/ipam/ip-addresses`) | IPAM write + read | `API_KEY` + `API_AUTH_TYPE=Token` |
  146. | homeassistant | 21 | `get_config` (200) + `call_service` (light.turn_on, 200) | `SERVER_URL_OVERRIDE` + `API_KEY` (`${HA_TOKEN}`, sent as Bearer) |
  147. ### Client matrix
  148. | Agent CLI | Model used (live test) | MCP attach mechanism | Tool calls | Prompts/Resources surfaced to model? |
  149. |---|---|---|---|---|
  150. | **opencode** | (CLI default) | `~/.config/opencode/opencode.json` `mcp` | ✅ native | **prompts: ✅ (slash) · resources: ✅** — most complete ‖ |
  151. | 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`) ‖ |
  152. | Kilocode | `kilo-auto/free` | global `settings/mcp_settings.json` | ✅ native | prompts: ❌ (no prompt mechanism) · resources: ✅ (`access_mcp_resource`) ‖ |
  153. | Qwen | `agent` group via local LiteLLM gateway | project `.qwen/settings.json` | ✅ native (live invoke auth-blocked) | prompts: ✅ (slash `/summarize_spec`) · resources: ❌ (no client support) ‖ |
  154. | 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) ‖ |
  155. | Vibe | `mistral-medium-3.5` | `~/.vibe/config.toml` `[[mcp_servers]]` | ✅ discovery + reads | prompts: ❌ · resources: ❌ (tools-only client) ‖ |
  156. | agy | — | — | ❌ headless cannot enable MCP | n/a |
  157. | 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 ‡ |
  158. > **How to read the prompts/resources column.** MCP has three surfaces — tools, prompts,
  159. > resources. **mcp-openapi-proxy serves all three, advertised by default since 0.3.0.**
  160. > Whether they reach the model is up to the *client*, and that varies:
  161. >
  162. > - **‖ re-verified 2026-06-15 against the published 0.3.3 release** with **no** flags set
  163. > (validating the default-on advertising), driving each **real client binary**, in
  164. > **both** server modes (low-level and FastMCP simple). Per-client results were the
  165. > same across modes except where noted.
  166. > - **Tools** work on every client tested. **Prompts→model**: opencode & Qwen (slash
  167. > commands); Gemini interactive-only. **Resources→model**: opencode, Codex, Kilocode.
  168. > **opencode is the only client that surfaces all three** in any mode.
  169. > - **FastMCP simple mode exception:** a client with no native prompt surface can still
  170. > reach prompts through the static `call_function`→`get_prompt` indirection. Observed
  171. > with **Codex** (prompts ❌ in low-level, ✅ in FastMCP simple mode). Vibe stays
  172. > tools-only regardless of mode.
  173. > - **‡ unknown** — Letta can't be exercised without standing up a Letta server + model;
  174. > left untested rather than guessed.
  175. > - Every cell on the proxy side was confirmed via a raw stdio handshake (`initialize`
  176. > advertises tools+prompts+resources; `prompts/get` and `resources/read` return content).
  177. > The remaining ❌ are **client-side** gaps, not proxy limitations.
  178. >
  179. > *(All pre-0.3.0 prompt/resource findings were voided — they were measured while
  180. > advertising defaulted off, so they reflected the server default, not the clients.)*
  181. 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):
  182. <details>
  183. <summary><b>Codex</b> — inline <code>-c mcp_servers.*</code> overrides</summary>
  184. ```bash
  185. codex exec \
  186. -c 'mcp_servers.glama.command="uvx"' \
  187. -c 'mcp_servers.glama.args=["mcp-openapi-proxy"]' \
  188. -c 'mcp_servers.glama.env.OPENAPI_SPEC_URL="https://glama.ai/api/mcp/openapi.json"' \
  189. "list the available tools"
  190. ```
  191. </details>
  192. <details>
  193. <summary><b>Gemini</b> — project <code>.gemini/settings.json</code></summary>
  194. ```json
  195. {
  196. "mcpServers": {
  197. "glama": {
  198. "command": "uvx",
  199. "args": ["mcp-openapi-proxy"],
  200. "env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
  201. }
  202. }
  203. }
  204. ```
  205. </details>
  206. <details>
  207. <summary><b>Qwen</b> — project <code>.qwen/settings.json</code></summary>
  208. ```json
  209. {
  210. "mcpServers": {
  211. "glama": {
  212. "command": "uvx",
  213. "args": ["mcp-openapi-proxy"],
  214. "env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
  215. }
  216. }
  217. }
  218. ```
  219. </details>
  220. <details>
  221. <summary><b>Kilocode</b> — global <code>settings/mcp_settings.json</code> (use a clean workspace)</summary>
  222. ```json
  223. {
  224. "mcpServers": {
  225. "glama": {
  226. "command": "uvx",
  227. "args": ["mcp-openapi-proxy"],
  228. "env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
  229. }
  230. }
  231. }
  232. ```
  233. </details>
  234. <details>
  235. <summary><b>opencode</b> — <code>~/.config/opencode/opencode.json</code> <code>mcp</code> block</summary>
  236. ```json
  237. {
  238. "mcp": {
  239. "glama": {
  240. "type": "local",
  241. "command": ["uvx", "mcp-openapi-proxy"],
  242. "environment": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
  243. }
  244. }
  245. }
  246. ```
  247. </details>
  248. <details>
  249. <summary><b>Vibe</b> — <code>~/.vibe/config.toml</code> <code>[[mcp_servers]]</code></summary>
  250. ```toml
  251. [[mcp_servers]]
  252. name = "glama"
  253. command = "uvx"
  254. args = ["mcp-openapi-proxy"]
  255. [mcp_servers.env]
  256. OPENAPI_SPEC_URL = "https://glama.ai/api/mcp/openapi.json"
  257. ```
  258. </details>
  259. 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.
  260. ### Tips
  261. - **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.
  262. - **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).
  263. - **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).
  264. - **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.
  265. ## Examples
  266. 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.
  267. Each example below is collapsed — click to expand.
  268. <details>
  269. <summary><b>Glama Example</b> — the most minimal config: just <code>OPENAPI_SPEC_URL</code>, no auth</summary>
  270. ![image](https://github.com/user-attachments/assets/84afdaa8-7b4f-4726-835f-64255ca970b7)
  271. 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.
  272. #### 1. Verify the OpenAPI Specification
  273. Retrieve the Glama OpenAPI specification:
  274. ```bash
  275. curl https://glama.ai/api/mcp/openapi.json
  276. ```
  277. Ensure the response is a valid OpenAPI JSON document.
  278. #### 2. Configure mcp-openapi-proxy for Glama
  279. Add the following configuration to your MCP ecosystem settings:
  280. ```json
  281. {
  282. "mcpServers": {
  283. "glama": {
  284. "command": "uvx",
  285. "args": ["mcp-openapi-proxy"],
  286. "env": {
  287. "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json"
  288. }
  289. }
  290. }
  291. }
  292. ```
  293. #### 3. Testing
  294. Start the service with:
  295. ```bash
  296. OPENAPI_SPEC_URL="https://glama.ai/api/mcp/openapi.json" uvx mcp-openapi-proxy
  297. ```
  298. Then refer to the [JSON-RPC Testing](#json-rpc-testing) section for instructions on listing resources and tools.
  299. </details>
  300. <details>
  301. <summary><b>Fly.io Example</b> — machines API with an API token</summary>
  302. ![image](https://github.com/user-attachments/assets/80abd7fa-ccca-4e35-b0dd-36ef82a236c5)
  303. Fly.io provides a simple API for managing machines making it an ideal starting point. Obtain an API token from [Fly.io documentation](https://fly.io/docs/hands-on/install-flyctl/).
  304. #### 1. Verify the OpenAPI Specification
  305. Retrieve the Fly.io OpenAPI specification:
  306. ```bash
  307. curl https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json
  308. ```
  309. Ensure the response is a valid OpenAPI JSON document.
  310. #### 2. Configure mcp-openapi-proxy for Fly.io
  311. Update your MCP ecosystem configuration:
  312. ```json
  313. {
  314. "mcpServers": {
  315. "flyio": {
  316. "command": "uvx",
  317. "args": ["mcp-openapi-proxy"],
  318. "env": {
  319. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
  320. "API_KEY": "<your_flyio_token_here>"
  321. }
  322. }
  323. }
  324. }
  325. ```
  326. - **OPENAPI_SPEC_URL**: Points to the Fly.io OpenAPI specification.
  327. - **API_KEY**: Your Fly.io API token (replace `<your_flyio_token_here>`).
  328. - **API_AUTH_TYPE**: Set to `Api-Key` for Fly.io’s header-based authentication (overrides default `Bearer`).
  329. #### 3. Testing
  330. After starting the service refer to the [JSON-RPC Testing](#json-rpc-testing) section for instructions on listing resources and tools.
  331. </details>
  332. <details>
  333. <summary><b>Render Example</b> — manage hosted services with a tool whitelist</summary>
  334. ![image](https://github.com/user-attachments/assets/f1dee1bf-e330-41f1-a700-6386edd8895e)
  335. 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.
  336. #### 1. Verify the OpenAPI Specification
  337. Retrieve the Render OpenAPI specification:
  338. ```bash
  339. curl https://api-docs.render.com/openapi/render-public-api-1.json
  340. ```
  341. Ensure the response is a valid OpenAPI document.
  342. #### 2. Configure mcp-openapi-proxy for Render
  343. Add the following configuration to your MCP ecosystem settings:
  344. ```json
  345. {
  346. "mcpServers": {
  347. "render": {
  348. "command": "uvx",
  349. "args": ["mcp-openapi-proxy"],
  350. "env": {
  351. "OPENAPI_SPEC_URL": "https://api-docs.render.com/openapi/render-public-api-1.json",
  352. "TOOL_WHITELIST": "/services,/maintenance",
  353. "API_KEY": "your_render_token_here"
  354. }
  355. }
  356. }
  357. }
  358. ```
  359. #### 3. Testing
  360. Launch the proxy with your Render configuration:
  361. ```bash
  362. 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
  363. ```
  364. Then refer to the [JSON-RPC Testing](#json-rpc-testing) section for instructions on listing resources and tools.
  365. </details>
  366. <details>
  367. <summary><b>Slack Example</b> — payload token stripping via JMESPath (<code>STRIP_PARAM</code>)</summary>
  368. ![image](https://github.com/user-attachments/assets/706adad5-3f1c-4f32-aef5-6a1af794aef3)
  369. Slack’s API showcases stripping unnecessary token payload using JMESPath. Obtain a bot token from [Slack API documentation](https://api.slack.com/authentication/token-types#bot).
  370. #### 1. Verify the OpenAPI Specification
  371. Retrieve the Slack OpenAPI specification:
  372. ```bash
  373. curl https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json
  374. ```
  375. Ensure it’s a valid OpenAPI JSON document.
  376. #### 2. Configure mcp-openapi-proxy for Slack
  377. Update your configuration:
  378. ```json
  379. {
  380. "mcpServers": {
  381. "slack": {
  382. "command": "uvx",
  383. "args": ["mcp-openapi-proxy"],
  384. "env": {
  385. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json",
  386. "TOOL_WHITELIST": "/chat,/bots,/conversations,/reminders,/files,/users",
  387. "API_KEY": "<your_slack_bot_token, starts with xoxb>",
  388. "STRIP_PARAM": "token",
  389. "TOOL_NAME_PREFIX": "slack_"
  390. }
  391. }
  392. }
  393. }
  394. ```
  395. - **OPENAPI_SPEC_URL**: Slack’s OpenAPI spec URL.
  396. - **TOOL_WHITELIST**: Limits tools to useful endpoint groups (e.g. chat, conversations, users).
  397. - **API_KEY**: Your Slack bot token (e.g. `xoxb-...`, replace `<your_slack_bot_token>`).
  398. - **STRIP_PARAM**: Removes the token field from the request payload.
  399. - **TOOL_NAME_PREFIX**: Prepends `slack_` to tool names.
  400. #### 3. Testing
  401. After starting the service refer to the [JSON-RPC Testing](#json-rpc-testing) section for instructions on listing resources and tools.
  402. </details>
  403. <details>
  404. <summary><b>GetZep Example</b> — project-generated spec with <code>Api-Key</code> auth</summary>
  405. > **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.
  406. ![image](https://github.com/user-attachments/assets/9a4fdabb-fa3d-4626-a50f-438147eadc9f)
  407. 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](https://docs.getzep.com/).
  408. #### 1. Verify the OpenAPI Specification
  409. Retrieve the project-provided GetZep OpenAPI specification:
  410. ```bash
  411. curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json
  412. ```
  413. Ensure it’s a valid OpenAPI JSON document. Alternatively, generate your own spec and use a `file://` URL to reference a local file.
  414. #### 2. Configure mcp-openapi-proxy for GetZep
  415. Update your configuration:
  416. ```json
  417. {
  418. "mcpServers": {
  419. "getzep": {
  420. "command": "uvx",
  421. "args": ["mcp-openapi-proxy"],
  422. "env": {
  423. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json",
  424. "TOOL_WHITELIST": "/sessions",
  425. "API_KEY": "<your_getzep_api_key>",
  426. "API_AUTH_TYPE": "Api-Key",
  427. "TOOL_NAME_PREFIX": "zep_"
  428. }
  429. }
  430. }
  431. }
  432. ```
  433. - **OPENAPI_SPEC_URL**: Points to the project-provided GetZep Swagger spec (or use `file:///path/to/your/spec.json` for a local file).
  434. - **TOOL_WHITELIST**: Limits to `/sessions` endpoints.
  435. - **API_KEY**: Your GetZep API key.
  436. - **API_AUTH_TYPE**: Uses `Api-Key` for header-based authentication.
  437. - **TOOL_NAME_PREFIX**: Prepends `zep_` to tool names.
  438. #### 3. Testing
  439. After starting the service refer to the [JSON-RPC Testing](#json-rpc-testing) section for instructions on listing resources and tools.
  440. </details>
  441. <details>
  442. <summary><b>Virustotal Example</b> — YAML spec + custom <code>x-apikey</code> auth header</summary>
  443. ![image](https://github.com/user-attachments/assets/d1760e58-a299-4004-9593-6dbaf3b685a1)
  444. This example demonstrates:
  445. - Using a YAML OpenAPI specification file
  446. - Using custom HTTP auth header, "x-apikey"
  447. #### 1. Verify the OpenAPI Specification
  448. Retrieve the Virustotal OpenAPI specification:
  449. ```bash
  450. curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml
  451. ```
  452. Ensure that the response is a valid OpenAPI YAML document.
  453. #### 2. Configure mcp-openapi-proxy for Virustotal
  454. Add the following configuration to your MCP ecosystem settings:
  455. ```json
  456. {
  457. "mcpServers": {
  458. "virustotal": {
  459. "command": "uvx",
  460. "args": ["mcp-openapi-proxy"],
  461. "env": {
  462. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml",
  463. "EXTRA_HEADERS": "x-apikey: ${VIRUSTOTAL_API_KEY}",
  464. "OPENAPI_SPEC_FORMAT": "yaml"
  465. }
  466. }
  467. }
  468. }
  469. ```
  470. Key configuration points:
  471. - By default, the proxy expects a JSON specification and sends the API key with a Bearer prefix.
  472. - To use a YAML OpenAPI specification, include `OPENAPI_SPEC_FORMAT="yaml"`.
  473. - Note: VirusTotal requires a special authentication header; EXTRA_HEADERS is used to transmit the API key as "x-apikey: ${VIRUSTOTAL_API_KEY}".
  474. #### 3. Testing
  475. Launch the proxy with the Virustotal configuration:
  476. ```bash
  477. 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
  478. ```
  479. After starting the service, refer to the [JSON-RPC Testing](#json-rpc-testing) section for instructions on listing resources and tools.
  480. </details>
  481. <details>
  482. <summary><b>Notion Example</b> — API version header via <code>EXTRA_HEADERS</code></summary>
  483. ![image](https://github.com/user-attachments/assets/45038bcf-9537-4337-8a90-8553ad3aa81b)
  484. 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.
  485. #### 1. Verify the OpenAPI Specification
  486. Retrieve the Notion OpenAPI specification:
  487. ```bash
  488. curl https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml
  489. ```
  490. Ensure the response is a valid YAML document.
  491. #### 2. Configure mcp-openapi-proxy for Notion
  492. Add the following configuration to your MCP ecosystem settings:
  493. ```json
  494. {
  495. "mcpServers": {
  496. "notion": {
  497. "command": "uvx",
  498. "args": [
  499. "mcp-openapi-proxy"
  500. ],
  501. "env": {
  502. "API_KEY": "ntn_<your_key>",
  503. "OPENAPI_SPEC_URL": "https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml",
  504. "SERVER_URL_OVERRIDE": "https://api.notion.com",
  505. "EXTRA_HEADERS": "Notion-Version: 2022-06-28"
  506. }
  507. }
  508. }
  509. }
  510. ```
  511. #### 3. Testing
  512. Launch the proxy with the Notion configuration:
  513. ```bash
  514. 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
  515. ```
  516. After starting the service, refer to the [JSON-RPC Testing](#json-rpc-testing) section for instructions on listing resources and tools.
  517. </details>
  518. <details>
  519. <summary><b>Asana Example</b> — workspaces/tasks/projects with a whitelist and <code>SERVER_URL_OVERRIDE</code></summary>
  520. ![image](https://github.com/user-attachments/assets/087571dd-9e06-407e-905c-92815231f618)
  521. 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`.
  522. #### 1. Verify the OpenAPI Specification
  523. Retrieve the Asana OpenAPI specification:
  524. ```bash
  525. curl https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml
  526. ```
  527. Ensure the response is a valid YAML (or JSON) document.
  528. #### 2. Configure mcp-openapi-proxy for Asana
  529. Add the following configuration to your MCP ecosystem settings:
  530. ```json
  531. {
  532. "mcpServers": {
  533. "asana": {
  534. "command": "uvx",
  535. "args": [
  536. "mcp-openapi-proxy"
  537. ],
  538. "env": {
  539. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml",
  540. "SERVER_URL_OVERRIDE": "https://app.asana.com/api/1.0",
  541. "TOOL_WHITELIST": "/workspaces,/tasks,/projects,/users",
  542. "API_KEY": "${ASANA_API_KEY}"
  543. }
  544. }
  545. }
  546. }
  547. ```
  548. *Note: Most Asana API endpoints require authentication. Set `ASANA_API_KEY` in your environment or `.env` file with a valid token.*
  549. #### 3. Testing
  550. Start the service with:
  551. ```bash
  552. 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
  553. ```
  554. You can then use the MCP ecosystem to list and invoke tools for endpoints like `/dcim/devices/` and `/ipam/ip-addresses/`.
  555. </details>
  556. <details>
  557. <summary><b>APIs.guru Example</b> — directory of thousands of public OpenAPI definitions, no auth</summary>
  558. 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.
  559. #### 1. Verify the OpenAPI Specification
  560. Retrieve the APIs.guru OpenAPI specification:
  561. ```bash
  562. curl https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml
  563. ```
  564. Ensure the response is a valid OpenAPI YAML document.
  565. #### 2. Configure mcp-openapi-proxy for APIs.guru
  566. Add the following configuration to your MCP ecosystem settings:
  567. ```json
  568. {
  569. "mcpServers": {
  570. "apisguru": {
  571. "command": "uvx",
  572. "args": ["mcp-openapi-proxy"],
  573. "env": {
  574. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml"
  575. }
  576. }
  577. }
  578. }
  579. ```
  580. #### 3. Testing
  581. Start the service with:
  582. ```bash
  583. 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
  584. ```
  585. 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.
  586. </details>
  587. <details>
  588. <summary><b>NetBox Example</b> — IPAM/DCIM API with <code>Token</code> auth</summary>
  589. 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.
  590. #### 1. Verify the OpenAPI Specification
  591. Retrieve the NetBox OpenAPI specification:
  592. ```bash
  593. curl https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml
  594. ```
  595. Ensure the response is a valid OpenAPI YAML document.
  596. #### 2. Configure mcp-openapi-proxy for NetBox
  597. Add the following configuration to your MCP ecosystem settings:
  598. ```json
  599. {
  600. "mcpServers": {
  601. "netbox": {
  602. "command": "uvx",
  603. "args": ["mcp-openapi-proxy"],
  604. "env": {
  605. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml",
  606. "API_KEY": "${NETBOX_API_KEY}"
  607. }
  608. }
  609. }
  610. }
  611. ```
  612. *Note: Most NetBox API endpoints require authentication. Set `NETBOX_API_KEY` in your environment or `.env` file with a valid token.*
  613. #### 3. Testing
  614. Start the service with:
  615. ```bash
  616. 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
  617. ```
  618. You can then use the MCP ecosystem to list and invoke tools for endpoints like `/dcim/devices/` and `/ipam/ip-addresses/`.
  619. </details>
  620. <details>
  621. <summary><b>Box API Example</b> — developer-token access to Box content</summary>
  622. 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.
  623. #### Example config: `examples/box-claude_desktop_config.json`
  624. ```json
  625. "env": {
  626. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/box.com/2.0.0/openapi.yaml",
  627. "TOOL_WHITELIST": "/folders/{folder_id}/items,/files/{file_id},/search,/recent_items",
  628. "API_KEY": "${BOX_API_KEY}"
  629. }
  630. ```
  631. - Set your Box developer token as an environment variable in `.env`:
  632. ```
  633. BOX_API_KEY=your_box_developer_token
  634. ```
  635. - Or run the proxy with a one-liner:
  636. ```bash
  637. 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
  638. ```
  639. You can now use the MCP ecosystem to list and invoke Box API tools. For integration tests, see `tests/integration/test_box_integration.py`.
  640. Note: developer api keys for free tier box users are limited to 60 minutes :(.
  641. </details>
  642. <details>
  643. <summary><b>WolframAlpha API Example</b> — computation API keyed by App ID</summary>
  644. ![image](https://github.com/user-attachments/assets/6a634d63-5734-4275-8876-6bacb8beabcc)
  645. 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.
  646. #### Example config: `examples/wolframalpha-claude_desktop_config.json`
  647. ```json
  648. {
  649. "mcpServers": {
  650. "wolframalpha": {
  651. "command": "uvx",
  652. "args": [
  653. "mcp-openapi-proxy"
  654. ],
  655. "env": {
  656. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/wolframalpha.com/v0.1/openapi.yaml",
  657. "API_KEY": "${WOLFRAM_LLM_APP_ID}"
  658. }
  659. }
  660. }
  661. }
  662. ```
  663. - Set your WolframAlpha App ID as an environment variable in `.env`:
  664. ```
  665. WOLFRAM_LLM_APP_ID=your_wolfram_app_id
  666. ```
  667. - Or run the proxy with a one-liner:
  668. ```bash
  669. 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
  670. ```
  671. You can now use the MCP ecosystem to list and invoke WolframAlpha API tools. For integration tests, see `tests/integration/test_wolframalpha_integration.py`.
  672. </details>
  673. <details>
  674. <summary><b>Letta (self-hosted + Cloud)</b> — agent platform; stdio for self-hosted, authenticated remote HTTP for Cloud</summary>
  675. Letta runs agents on a server, so attachment differs by deployment:
  676. - **Self-hosted Letta** accepts a **stdio** MCP server via `PUT /v1/tools/mcp/servers` — no network exposure.
  677. - **Letta Cloud** rejects stdio and needs a **remote streamable-HTTP** MCP URL behind authentication.
  678. 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`](examples/letta/README.md).
  679. </details>
  680. <details>
  681. <summary><b>WordPress Example</b> — publish to a real WordPress blog from any MCP agent</summary>
  682. 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](https://matthewhand.mywebcommunity.org/)** through this proxy — see the write-up [*“Turning Any API into Agent Tools”*](https://matthewhand.mywebcommunity.org/2026/06/12/turning-any-api-into-agent-tools-a-real-world-test-of-mcp-openapi-proxy/), itself posted via the proxy.
  683. Example config — `examples/wordpress-claude_desktop_config.json`:
  684. ```json
  685. {
  686. "mcpServers": {
  687. "wordpress": {
  688. "command": "uvx",
  689. "args": ["mcp-openapi-proxy"],
  690. "env": {
  691. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/main/examples/wordpress-openapi.json",
  692. "SERVER_URL_OVERRIDE": "https://your-site.example.com/wp-json",
  693. "EXTRA_HEADERS": "Authorization: Basic BASE64_OF_USERNAME_COLON_APPLICATION_PASSWORD",
  694. "IGNORE_SSL_TOOLS": "false",
  695. "TOOL_WHITELIST": "/wp/v2/posts"
  696. }
  697. }
  698. }
  699. }
  700. ```
  701. 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.
  702. **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:
  703. ```bash
  704. printf 'myuser:xxxx xxxx xxxx xxxx xxxx xxxx' | base64 -w0
  705. ```
  706. 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.
  707. </details>
  708. <details>
  709. <summary><b>Home Assistant Example</b> — control your smart home; <code>call_service</code> needs the >= 0.3.3 path-param body fix</summary>
  710. Exposes a generic slice of the [Home Assistant REST API](https://developers.home-assistant.io/docs/api/rest/)
  711. (21 operations) — read state (`get_config`, `list_states`, `get_state`, `list_services`,
  712. `get_history`/`get_history_now`, `get_logbook`, `list_calendars`, `get_calendar_events`,
  713. `get_camera_image`, `get_error_log`, `list_components`, `list_events`, `get_api_status`) and
  714. act (`call_service`, `set_state`, `delete_state`, `fire_event`, `render_template`,
  715. `check_config`, `handle_intent`). HA ships no official OpenAPI spec, so this is hand-rolled
  716. from the official docs.
  717. #### 1. Verify the OpenAPI specification
  718. ```bash
  719. curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json
  720. ```
  721. #### 2. Configure mcp-openapi-proxy for Home Assistant
  722. ```json
  723. {
  724. "mcpServers": {
  725. "homeassistant": {
  726. "command": "uvx",
  727. "args": ["mcp-openapi-proxy"],
  728. "env": {
  729. "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json",
  730. "SERVER_URL_OVERRIDE": "http://homeassistant.local:8123",
  731. "API_KEY": "${HA_TOKEN}"
  732. }
  733. }
  734. }
  735. }
  736. ```
  737. Key configuration points:
  738. - `SERVER_URL_OVERRIDE` — your instance base URL, e.g. `http://homeassistant.local:8123` or `http://<ha-host>:8123`.
  739. - `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.
  740. - `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.
  741. #### 3. Testing
  742. `get_config` should return your HA configuration (200). `call_service` for `light/turn_on`
  743. with body `{"entity_id": "light.kitchen"}` should return 200 — the path params land in the URL
  744. (`/api/services/light/turn_on`), not the body.
  745. </details>
  746. ## Troubleshooting
  747. ### JSON-RPC Testing
  748. 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](docs/MIGRATION-0.4.md):
  749. ```json
  750. {"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-ai","version":"0.1.0"}},"jsonrpc":"2.0","id":0}
  751. ```
  752. 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.
  753. Then paste these follow-up messages:
  754. ```json
  755. {"method":"notifications/initialized","jsonrpc":"2.0"}
  756. {"method":"resources/list","params":{},"jsonrpc":"2.0","id":1}
  757. {"method":"tools/list","params":{},"jsonrpc":"2.0","id":2}
  758. ```
  759. - **Missing OPENAPI_SPEC_URL:** Ensure it’s set to a valid OpenAPI JSON URL or local file path.
  760. - **Invalid Specification:** Verify the OpenAPI document is standard-compliant.
  761. - **Tool Filtering Issues:** Check `TOOL_WHITELIST` matches desired endpoints.
  762. - **Authentication Errors:** Confirm `API_KEY` and `API_AUTH_TYPE` are correct.
  763. - **Logging:** Set `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.
  764. - **Test Server:** Run directly:
  765. ```bash
  766. uvx mcp-openapi-proxy
  767. ```
  768. ## License
  769. [MIT License](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.