Skip to content
Back to search

mcp-gateway

One endpoint in front of your MCP servers and REST APIs. The agent sees a small fixed meta-tool surface and finds tools on demand. Also an MCP compatibility layer: clients and servers on different MCP revisions (2024-11-05 to 2026-07-28) work together through it. Single Rust binary.

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/MikkoParkkola/mcp-gateway 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/MikkoParkkola/mcp-gateway'

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/mikkoparkkola--mcp-gateway/badge.svg)](/listings/mikkoparkkola--mcp-gateway)

HTML

<a href="/listings/mikkoparkkola--mcp-gateway"><img src="/api/listings/mikkoparkkola--mcp-gateway/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.

**Four commands:**

brew trust --tap MikkoParkkola/tap   # Homebrew 6.0+
brew install MikkoParkkola/tap/mcp-gateway   # 1. install
mcp-gateway setup wizard --configure-client  # 2. import existing servers + wire up clients
mcp-gateway serve                            # 3. run
mcp-gateway doctor                           # 4. verify everything is healthy

That is it. Your AI clients now talk to the gateway, and the gateway routes to every backend you already had configured, at a flat `11 tools` instead of `~150` — 11 is the default HTTP configuration counted for an administrator; an ordinary client is shown four fewer. Start with `gateway_search_tools` from your AI client to find any backend tool, then invoke it with `gateway_invoke`.

> **Nothing to import yet?** `mcp-gateway init --with-examples` writes a working `gateway.yaml` with public capabilities so you can confirm the gateway is alive before adding your own servers.

**Or tell your AI assistant** (recommended):

> Read https://github.com/MikkoParkkola/mcp-gateway and install mcp-gateway to consolidate all my MCP servers behind one gateway

Your agent will install the binary, run the setup wizard, import your existing MCP servers, and wire itself up. This works in Claude Code, Cursor, Windsurf, Codex, and any AI with terminal access.

Install

| Method | Command | |--------|---------| | **Homebrew (macOS/Linux, recommended)** | `brew install MikkoParkkola/tap/mcp-gateway` | | **Cargo** | `cargo install mcp-gateway` | | **cargo-binstall** | `cargo binstall mcp-gateway` | | **Direct binary download (Windows x64)** | Download `mcp-gateway-windows-x86_64.exe` from the [latest release](https://github.com/MikkoParkkola/mcp-gateway/releases/latest) | | **Docker** | `docker run -p 127.0.0.1:39400:39400 -e MCP_GATEWAY_SERVER__ALLOW_UNAUTHENTICATED_NETWORK_BIND=true -v $(pwd)/gateway.container.yaml:/config.yaml:ro ghcr.io/mikkoparkkola/mcp-gateway:latest --config /config.yaml --host 0.0.0.0 --port 39400` | | **Docker, `npx`/`uvx` backends** | Same, with `:latest-full` — the default image carries no Node or `uv`, so a stdio backend that shells out to either cannot spawn. See [Docker Deployment](docs/DEPLOYMENT.md#docker-deployment). |

On Linux, the image runs as UID/GID 1001. Make an owner-only deployment copy instead of changing ownership on your working config: `install -m 600 gateway.yaml gateway.container.yaml && sudo chown 1001:1001 gateway.container.yaml`. Do not make a credential-bearing config world-readable. Docker Desktop handles bind-mount identity differently on macOS and Windows.

<details> <summary>Direct binary download</summary>

# macOS Apple Silicon
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-arm64 -o mcp-gateway && chmod +x mcp-gateway

# macOS Intel
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-x86_64 -o mcp-gateway && chmod +x mcp-gateway

# Linux x86_64
curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-linux-x86_64 -o mcp-gateway && chmod +x mcp-gateway
# Windows x64 (PowerShell)
Invoke-WebRequest -Uri https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-windows-x86_64.exe -OutFile mcp-gateway.exe

</details>

Set up, three ways

Option A: auto-import everything (recommended)

mcp-gateway setup wizard --configure-client

Scans Claude Desktop, Claude Code, Cursor, Zed, Continue.dev, Codex, and running MCP processes; lets you pick which servers to import into `gateway.yaml`; previews the gateway entry; writes it into each detected client config; verifies the write; and prints backup and rollback paths when an existing client config changes. Add `--yes` to skip the prompts and import everything.

Option B: add servers from the built-in registry

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 · 596 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. # MCP Gateway
  2. [![CI](https://github.com/MikkoParkkola/mcp-gateway/actions/workflows/ci.yml/badge.svg)](https://github.com/MikkoParkkola/mcp-gateway/actions/workflows/ci.yml)
  3. [![Crates.io](https://img.shields.io/crates/v/mcp-gateway.svg)](https://crates.io/crates/mcp-gateway)
  4. [![Downloads](https://img.shields.io/crates/d/mcp-gateway.svg)](https://crates.io/crates/mcp-gateway)
  5. [![Rust](https://img.shields.io/badge/rust-1.95+-blue.svg)](https://www.rust-lang.org)
  6. [![License](https://img.shields.io/badge/license-PolyForm--NC-blue.svg)](https://github.com/MikkoParkkola/mcp-gateway/blob/main/LICENSES.md)
  7. [![unsafe denied](https://img.shields.io/badge/unsafe-denied-success.svg)](https://github.com/rust-secure-code/safety-dance/)
  8. [![dependency status](https://deps.rs/repo/github/MikkoParkkola/mcp-gateway/status.svg)](https://deps.rs/repo/github/MikkoParkkola/mcp-gateway)
  9. [![Capabilities](https://img.shields.io/badge/REST%20capabilities-110%2B-purple.svg)](https://github.com/MikkoParkkola/mcp-gateway/tree/main/capabilities)
  10. [![MCP Protocol](https://img.shields.io/badge/MCP-2025--11--25-green.svg)](https://modelcontextprotocol.io)
  11. [![OWASP Agentic AI](https://img.shields.io/badge/OWASP_Agentic_AI-10%2F10_self--assessed-blue.svg)](docs/OWASP_AGENTIC_AI_COMPLIANCE.md)
  12. [![Glama](https://glama.ai/mcp/servers/MikkoParkkola/mcp-gateway/badge)](https://glama.ai/mcp/servers/MikkoParkkola/mcp-gateway)
  13. [![Quality Score](https://glama.ai/mcp/servers/MikkoParkkola/mcp-gateway/badges/score.svg)](https://glama.ai/mcp/servers/MikkoParkkola/mcp-gateway)
  14. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP-0078d4?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=mcp-gateway&config=%7B%22command%22%3A%22mcp-gateway%22%2C%22args%22%3A%5B%22serve%22%2C%22--stdio%22%5D%7D)
  15. [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP-black?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=mcp-gateway&config=%7B%22command%22%3A%22mcp-gateway%22%2C%22args%22%3A%5B%22serve%22%2C%22--stdio%22%5D%7D)
  16. **One gateway between your AI and every tool it needs, without flooding the context window.**
  17. MCP Gateway is a single Rust binary that sits between an AI client and all of its tools. Connect MCP servers and REST APIs behind it, and the agent sees a compact meta-surface of 9 to 17 tools instead of every backend definition. It discovers and calls backend tools on demand. A small live-agent benchmark found no completed-task token saving from that extra hop, so the value is catalog capacity plus policy and routing—not a blanket token claim. See [Benchmarks](docs/BENCHMARKS.md).
  18. ![demo](demo.gif)
  19. Permitted noncommercial and nonprofit use is free, including running the full gateway. Commercial use outside these free permissions needs a [commercial license](#license).
  20. ## The problem this removes
  21. Every MCP tool an AI client connects costs roughly 150 tokens of context overhead, loaded into every request whether the tool gets used or not. Connect 20 servers with 100 tools between them and you spend about 15,000 tokens before the conversation starts. Context limits then force a second cost: you have to decide up front which tools to connect and leave the rest out, so the agent makes worse decisions because it cannot reach data you chose not to load.
  22. MCP Gateway moves the full catalog out of the exposed tool list. The agent loads a small fixed set of meta-tools, searches with `gateway_search_tools`, and invokes a backend tool with `gateway_invoke`. This creates room for larger catalogs, but the extra search hop can cost more tokens and time on a completed task.
  23. ```mermaid
  24. flowchart LR
  25. AI["AI client<br/>(Claude, Cursor, ...)"]
  26. subgraph GW["MCP Gateway (single binary)"]
  27. META["Compact meta-surface<br/>9-17 tools"]
  28. DISC{"Discover on demand<br/>gateway_search_tools<br/>gateway_invoke"}
  29. end
  30. T1["MCP backend<br/>Tavily (stdio)"]
  31. T2["MCP backend<br/>Context7 (http)"]
  32. C1["REST capability<br/>GitHub"]
  33. C2["REST capability<br/>Stripe"]
  34. Cn["110+ capabilities"]
  35. AI -->|"9-17 tool defs"| META
  36. META --> DISC
  37. DISC --> T1
  38. DISC --> T2
  39. DISC --> C1
  40. DISC --> C2
  41. DISC --> Cn
  42. ```
  43. ## Quick Start
  44. **Four commands:**
  45. ```bash
  46. brew trust --tap MikkoParkkola/tap # Homebrew 6.0+
  47. brew install MikkoParkkola/tap/mcp-gateway # 1. install
  48. mcp-gateway setup wizard --configure-client # 2. import existing servers + wire up clients
  49. mcp-gateway serve # 3. run
  50. mcp-gateway doctor # 4. verify everything is healthy
  51. ```
  52. That is it. Your AI clients now talk to the gateway, and the gateway routes to every backend you already had configured, at a flat `11 tools` instead of `~150` — 11 is the default HTTP configuration counted for an administrator; an ordinary client is shown four fewer. Start with `gateway_search_tools` from your AI client to find any backend tool, then invoke it with `gateway_invoke`.
  53. > **Nothing to import yet?** `mcp-gateway init --with-examples` writes a working `gateway.yaml` with public capabilities so you can confirm the gateway is alive before adding your own servers.
  54. **Or tell your AI assistant** (recommended):
  55. > Read https://github.com/MikkoParkkola/mcp-gateway and install mcp-gateway to consolidate all my MCP servers behind one gateway
  56. Your agent will install the binary, run the setup wizard, import your existing MCP servers, and wire itself up. This works in Claude Code, Cursor, Windsurf, Codex, and any AI with terminal access.
  57. ### Install
  58. | Method | Command |
  59. |--------|---------|
  60. | **Homebrew (macOS/Linux, recommended)** | `brew install MikkoParkkola/tap/mcp-gateway` |
  61. | **Cargo** | `cargo install mcp-gateway` |
  62. | **cargo-binstall** | `cargo binstall mcp-gateway` |
  63. | **Direct binary download (Windows x64)** | Download `mcp-gateway-windows-x86_64.exe` from the [latest release](https://github.com/MikkoParkkola/mcp-gateway/releases/latest) |
  64. | **Docker** | `docker run -p 127.0.0.1:39400:39400 -e MCP_GATEWAY_SERVER__ALLOW_UNAUTHENTICATED_NETWORK_BIND=true -v $(pwd)/gateway.container.yaml:/config.yaml:ro ghcr.io/mikkoparkkola/mcp-gateway:latest --config /config.yaml --host 0.0.0.0 --port 39400` |
  65. | **Docker, `npx`/`uvx` backends** | Same, with `:latest-full` — the default image carries no Node or `uv`, so a stdio backend that shells out to either cannot spawn. See [Docker Deployment](docs/DEPLOYMENT.md#docker-deployment). |
  66. On Linux, the image runs as UID/GID 1001. Make an owner-only deployment copy
  67. instead of changing ownership on your working config: `install -m 600
  68. gateway.yaml gateway.container.yaml && sudo chown 1001:1001
  69. gateway.container.yaml`. Do not make a credential-bearing config
  70. world-readable. Docker Desktop handles bind-mount identity differently on
  71. macOS and Windows.
  72. <details>
  73. <summary>Direct binary download</summary>
  74. ```bash
  75. # macOS Apple Silicon
  76. curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-arm64 -o mcp-gateway && chmod +x mcp-gateway
  77. # macOS Intel
  78. curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-darwin-x86_64 -o mcp-gateway && chmod +x mcp-gateway
  79. # Linux x86_64
  80. curl -L https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-linux-x86_64 -o mcp-gateway && chmod +x mcp-gateway
  81. ```
  82. ```powershell
  83. # Windows x64 (PowerShell)
  84. Invoke-WebRequest -Uri https://github.com/MikkoParkkola/mcp-gateway/releases/latest/download/mcp-gateway-windows-x86_64.exe -OutFile mcp-gateway.exe
  85. ```
  86. </details>
  87. ### Set up, three ways
  88. #### Option A: auto-import everything (recommended)
  89. ```bash
  90. mcp-gateway setup wizard --configure-client
  91. ```
  92. Scans Claude Desktop, Claude Code, Cursor, Zed, Continue.dev, Codex, and running MCP processes; lets you pick which servers to import into `gateway.yaml`; previews the gateway entry; writes it into each detected client config; verifies the write; and prints backup and rollback paths when an existing client config changes. Add `--yes` to skip the prompts and import everything.
  93. #### Option B: add servers from the built-in registry
  94. 48 popular MCP servers are pre-registered with the right command, args, and env-var template. `mcp-gateway add` is compatible with `claude mcp add` and `codex mcp add`:
  95. ```bash
  96. mcp-gateway add tavily # known server, fills env vars
  97. mcp-gateway add my-server -- npx -y @some/mcp-server --flag # arbitrary stdio command
  98. mcp-gateway add --url https://mcp.sentry.dev/mcp sentry # HTTP server
  99. mcp-gateway add -e API_KEY=xxx my-server -- npx my-mcp-server
  100. ```
  101. `mcp-gateway list` shows what is configured. `mcp-gateway remove <name>` removes one.
  102. #### Option C: hand-write `gateway.yaml`
  103. For the full schema, see the annotated [examples/gateway-full.yaml](examples/gateway-full.yaml), which covers `env_files`, `server`, `auth`, `meta_mcp`, `streaming`, `failsafe`, `cache`, `capabilities`, and `backends`. The remaining top-level sections (`playbooks`, `security`, `webhooks`, `routing_profiles`, `code_mode`, `mtls`, `key_server`, `agent_auth`, `runtime`, `marketplace`, `control_plane`, `cost_governance`) have no prose reference yet; the `Config` struct in [src/config/mod.rs](src/config/mod.rs) is the authoritative list. Minimal example:
  104. ```yaml
  105. server:
  106. port: 39400
  107. meta_mcp:
  108. enabled: true
  109. backends:
  110. tavily:
  111. # `command` is parsed with host-platform rules: POSIX shlex on unix,
  112. # CommandLineToArgvW on Windows (so `C:\Windows\py.exe …` keeps its
  113. # backslashes; quote paths that contain spaces).
  114. command: "npx -y @anthropic/mcp-server-tavily"
  115. description: "Web search"
  116. env:
  117. TAVILY_API_KEY: "${TAVILY_API_KEY}"
  118. sentry:
  119. http_url: "https://mcp.sentry.dev/mcp"
  120. description: "Sentry issues"
  121. ```
  122. ### Run and verify
  123. ```bash
  124. mcp-gateway serve # start the gateway
  125. mcp-gateway doctor # diagnose config, port, env vars, backend health
  126. mcp-gateway doctor --fix # auto-fix issues where possible
  127. ```
  128. The web dashboard is at <http://localhost:39400/ui> once `serve` is running. The
  129. operator dashboard at `/dashboard` needs the admin credential, and a browser
  130. cannot send one on a navigation — so `serve` prints a single-use link to open it
  131. with, on a loopback bind. A network-bound gateway prints none and is managed
  132. through `/ui` with the token instead. See
  133. [Opening the dashboard](docs/DEPLOYMENT.md#opening-the-dashboard).
  134. ### Connect AI clients (if you skipped Option A)
  135. `setup export` writes the gateway entry into client config files for you. It auto-detects the right path per client:
  136. ```bash
  137. mcp-gateway setup export --target all --dry-run # preview without writing
  138. mcp-gateway setup export --target all # write, back up, verify
  139. mcp-gateway setup export --target claude-code # one client
  140. mcp-gateway setup export --target all --watch # regenerate on gateway.yaml changes
  141. mcp-gateway setup export --rollback <backup-file> # restore one client config
  142. ```
  143. Existing client files are backed up before mutation. The command prints the exact rollback command beside each updated client.
  144. | Client | Config path |
  145. |--------|-------------|
  146. | `claude-code` | `~/.claude.json` |
  147. | `claude-desktop` | platform-specific |
  148. | `cursor` | `.cursor/mcp.json` (workspace) |
  149. | `vs-code-copilot` | `.vscode/mcp.json` (workspace) |
  150. | `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
  151. | `cline` | `.cline/mcp_servers.json` (workspace) |
  152. | `zed` | `~/.config/zed/settings.json` |
  153. Modes: `--mode proxy` (HTTP), `--mode stdio` (subprocess), `--mode auto` (probe the health endpoint, then fall back).
  154. <details>
  155. <summary>Manual JSON snippet (if you prefer to edit by hand)</summary>
  156. ```json
  157. {
  158. "mcpServers": {
  159. "gateway": {
  160. "type": "http",
  161. "url": "http://localhost:39400/mcp"
  162. }
  163. }
  164. }
  165. ```
  166. </details>
  167. ## Why use MCP Gateway?
  168. - **Larger catalog, smaller exposed surface.** The agent loads a fixed meta-surface instead of every backend definition. In the checked-in live run, both paths completed every task, but the meta path used 1.2–16.1% more input tokens and added one turn. See [Benchmarks](docs/BENCHMARKS.md).
  169. - **Unlimited tools, discovered on demand.** No more choosing which servers fit the budget. The agent searches (`gateway_search_tools`) and invokes (`gateway_invoke`) tools as it needs them.
  170. - **Add any REST API in minutes.** Drop in a YAML file or import an OpenAPI spec with `mcp-gateway cap import`. 110+ capabilities ship built in.
  171. - **Per-user identity to backends.** Multitenant backends can receive the verified end-user identity with no gateway-stored long-lived credential. See [Multitenant identity](#end-user-identity-v31).
  172. - **Secure by construction.** A tool-poisoning validator scans every backend tool description before it reaches the agent. SHA-256 capability pinning is optional: unpinned files load, pinned files fail closed on mismatch. OWASP Agentic AI Top 10 coverage is self-assessed in-tree, not a certification. The crate sets `#![deny(unsafe_code)]`, so any unsafe block needs an explicit `#[allow]` opt-in, with optional mTLS, message signing, and agent identity.
  173. - **Swap your MCP stack without losing your session.** Hot-reload backends and config in about 8ms while the AI stays connected. No restart, no lost context.
  174. - **Production resilience.** Circuit breakers, retries with backoff, rate limiting, and health checks keep one flaky server from taking down the whole toolchain.
  175. - **Dual protocol.** MCP plus an A2A (agent-to-agent) transport adapter, so the same gateway routes tool calls and cross-provider agent messages.
  176. ### What MCP Gateway is, and what it is not
  177. MCP Gateway is a tool and capability **router**. It routes MCP tool, resource, and prompt traffic to backend MCP servers and to capability-backed REST APIs, and it can proxy MCP server-to-client requests like `sampling/createMessage`, `elicitation/create`, and `roots/list` back to the connected client over the existing session.
  178. It is not a chat-completions or embeddings proxy. When a backend asks for `sampling/createMessage`, the connected client performs the model call, not the gateway. The OpenAI-compatible prompt-cache helpers exist for one narrow reason: so `gateway_invoke` can preserve `prompt_cache_key` behavior for backends that call LLM APIs internally. That boundary is deliberate. The value here is routing hundreds of tools through a small surface, not sitting in the model path.
  179. Compared with the default approach of loading every tool definition into every request, the gateway trades a one-time discovery hop for a flat, small context cost. Compared with generic transport bridges that expose one server at a time, it aggregates many backends behind one namespaced surface with integrity checks, ranking, and per-user identity.
  180. <a id="end-user-identity-v31"></a>
  181. ## Multitenant identity
  182. A multitenant backend (email, memory, calendar) that runs its own OIDC normally sees only "the gateway," so it cannot enforce per-user access or produce a per-user audit trail. mcp-gateway propagates the verified end-user identity to the backend through one of three configured strategies. It can mint a short-lived gateway-signed assertion, forward the caller's own token, or run an RFC 8693 token exchange for OAuth-native backends. It keeps no long-lived credential for anyone. A backend marked `required` fails closed rather than serve a shared key when no verified identity is present, and per-user results stay isolated in the cache. See [ADR-007](docs/adr/ADR-007-identity-propagation.md), [ADR-008](docs/adr/ADR-008-multi-user-oauth-isolation.md), and [docs/UPGRADING-3.0.md](docs/UPGRADING-3.0.md). For the full propagation sequence, each strategy's wiring, the safety invariants, and the 2.x upgrade path, see [What is new in v3.1.0: end-user identity to backends](docs/whats-new-v3.1-identity.md).
  183. ### Independent reviews
  184. - [Five MCP hot-reload tools compared](https://ruachtov.ai/blog/five-tools-mcp-restart.html): Ruach Tov Collective's BPD-based comparison of mcp-gateway against four restart-focused alternatives, with a feature matrix and architectural analysis.
  185. - [mcp-gateway deep dive](https://ruachtov.ai/blog/mcp-gateway-deep-dive.html): a walkthrough of the capability system, SHA-256 integrity pinning, and the v2.5 to v2.9 development arc.
  186. Quantitative claims in this README are sourced from [docs/BENCHMARKS.md](docs/BENCHMARKS.md) and the machine-readable [benchmarks/public_claims.json](benchmarks/public_claims.json), with a CI check that fails on drift.
  187. ## Why the token math matters
  188. Every MCP tool you connect costs about 150 tokens of context overhead. Connect 20 servers with 100 tools and you have burned roughly 15,000 tokens before the first message, on definitions the AI probably will not use this turn. Worse, context limits force you to choose which tools to connect at all, so the agent makes weaker decisions because the right data is out of reach.
  189. | | Without gateway | With gateway |
  190. |---|----------------|--------------|
  191. | **Tools in context** | Every definition, every request | 11 meta-tools in the README benchmark (~1,100 tokens) |
  192. | **Schema footprint** | ~15,000 modeled tokens (100 tools) | ~1,100 modeled tokens before discovery; not completed-task cost |
  193. | **Measured task cost** | Direct path was lower at every tested size | Meta path used 1.2–16.1% more input tokens and one extra turn |
  194. | **Practical tool limit** | 20 to 50 tools under context pressure | Unlimited, discovered on demand |
  195. | **Connect a new REST API** | Build an MCP server (days) | Drop a YAML file or import an OpenAPI spec (minutes) |
  196. | **Changing MCP config** | Restart the AI session, lose context | Restart gateway (~8ms), session stays alive |
  197. | **When one tool breaks** | Cascading failures | Circuit breakers isolate it |
  198. The gateway exposes 9 tools minimum, 11 in the README benchmark scenario, counted for an administrator; a caller without admin standing is shown four fewer. The base discovery quartet stays fixed. Everything else is listed only where it can answer: stats, cost reporting, playbooks and profile control appear once the configuration that backs them exists, and webhook status where a webhook registry is attached, which the stdio transport never has. A deployment that turns all of them on is served 17. It costs context exactly where it is useful.
  199. ### Code Mode: two tools instead of the meta-tool set
  200. Setting `code_mode.enabled: true` makes `tools/list` return exactly two tools, `gateway_search` and `gateway_execute`, instead of the meta-tool set. Everything else is reached through those two. Tools named in `meta_mcp.surfaced_tools` are not appended in this mode, so the count stays at two however many backends are connected. Code Mode is off by default. `gateway_search` returns L0 by default (tool name, one-line purpose, score). Pass `detail=l1` or `detail=l2` for more, or `explain=true` for ranking diagnostics. `include_schema=true` is deprecated and maps to L2.
  201. ```yaml
  202. code_mode:
  203. enabled: true
  204. ```
  205. ## Security
  206. Connecting N MCP servers to an agent means accepting N attack surfaces. Tool poisoning, rug pulls, and exfiltration through hidden instructions in tool descriptions are demonstrated attacks, not hypotheticals. Invariant Labs' writeup ([MCP Security Notification: Tool Poisoning Attacks](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks)) and Simon Willison's summary ([MCP has prompt injection security problems](https://simonwillison.net/2025/Apr/9/mcp-prompt-injection/)) lay out the threat model.
  207. mcp-gateway puts every backend tool description behind one audit surface and defends it structurally:
  208. - **Tool-poisoning validator (AX-010).** Every backend tool description is scanned before it reaches the agent's context window. HIGH patterns fail closed: `<IMPORTANT>` blocks, `~/.ssh`/`~/.aws`/`id_rsa`/`.env`/`/etc/passwd`, `sidenote` exfiltration language, `curl .* https?://`, and `base64` in an exfil context. MEDIUM patterns warn: 40+ consecutive spaces, zero-width or bidi-override Unicode, and oversized descriptions. Implementation: [`src/validator/rules/tool_poisoning.rs`](src/validator/rules/tool_poisoning.rs) (19 tests).
  209. - **Optional SHA-256 capability hash-pinning.** `mcp-gateway cap pin <file>` writes a `sha256:` line over the file's canonical hash (`grep -v '^sha256:' capability.yaml | sha256sum` reproduces it from any shell). Unpinned files still load. A pinned file that no longer matches fails closed on load and on every watcher event.
  210. - **Rug-pull detection.** When a pinned capability's on-disk content changes after approval, the watcher unloads it and logs `RUG-PULL DETECTED`. The capability stays quarantined until an operator re-pins it. Implementation: [`src/capability/hash.rs`](src/capability/hash.rs) and `detect_rug_pulls` in [`src/capability/backend.rs`](src/capability/backend.rs).
  211. - **Centralized audit surface.** Capability YAMLs are plain text: diffable, greppable, and reviewable in a PR. The agent only ever sees the compact meta-surface, so there is no N-server tool-list pollution and no N-server attack surface.
  212. Full walkthrough, PoC snippets, and roadmap: [docs/blog/security-aware-mcp-gateway.md](docs/blog/security-aware-mcp-gateway.md).
  213. - **OWASP Agentic AI Top 10 (self-assessed).** Controls are mapped across all 10 ASI risks at the gateway boundary in-tree. That is not a certification. Hardening follow-ups are tracked separately for SBOMs, release signing, live remote attestation discovery, multi-gateway signing, SQL-sink defaults, and collusion detection. See [docs/OWASP_AGENTIC_AI_COMPLIANCE.md](docs/OWASP_AGENTIC_AI_COMPLIANCE.md).
  214. ### Recent additions
  215. - **OpenAPI importer.** `mcp-gateway cap import <spec-url-or-file>` turns an OpenAPI 3 spec into one validated capability YAML per operation. The full Swagger Petstore spec becomes 19 validated capability YAMLs end to end:
  216. ```bash
  217. mcp-gateway cap import https://petstore3.swagger.io/api/v3/openapi.json --output capabilities/ --prefix petstore
  218. ```
  219. 22 tests across [`src/capability/openapi.rs`](src/capability/openapi.rs) and [`tests/openapi_import_tests.rs`](tests/openapi_import_tests.rs).
  220. ## Architecture
  221. ```mermaid
  222. flowchart TB
  223. subgraph GW["MCP Gateway (:39400)"]
  224. META["Meta-MCP surface: 9-17 tools<br/>gateway_list_servers · gateway_list_tools<br/>gateway_search_tools · gateway_invoke"]
  225. FS["Failsafes: circuit breaker · retry · rate limit"]
  226. META --> FS
  227. end
  228. FS --> B1["Tavily<br/>(stdio)"]
  229. FS --> B2["Context7<br/>(http)"]
  230. FS --> B3["Pieces<br/>(sse)"]
  231. FS --> B4["REST capabilities<br/>(110+)"]
  232. ```
  233. Single-binary gateway. An AI client talks to the compact meta-surface, and the gateway dynamically discovers and routes to backend tools. Key modules: `gateway/` (core router, OAuth, streaming, UI), `provider/` (MCP/composite/capability), `capability/` (discovery, validation), `transport/` (HTTP, stdio), `security/` (firewall, mTLS, message signing, agent identity, memory scanner), `identity_propagation/`, `key_server/`, `cost_accounting/`, `scheduler/`, `skills/`, `tool_profiles/`, `config_reload/`, and `a2a/` (A2A transport adapter).
  234. ## Features
  235. ### Web dashboard
  236. Embedded web UI at `/ui`: live status, searchable tools, server health, a read-only control-plane view, and a config viewer. Operator dashboard at `/dashboard`, which needs the admin credential — on a loopback bind `serve` prints a single-use link to open it with, since a browser cannot attach an `Authorization` header to a navigation. Cost tracking at `/ui#costs`. All served from the same binary and port, with no frontend build step.
  237. ### Security and governance
  238. | Feature | Description | Docs |
  239. |---------|-------------|------|
  240. | **Authentication** | Bearer tokens, API keys, explicit admin keys, per-client rate limits, and opt-in per-client circuit breakers. With auth disabled every caller over HTTP is anonymous and holds no admin; a stdio caller is admin, because the client spawned the process | [examples/per-client-tool-scopes.yaml](examples/per-client-tool-scopes.yaml) |
  241. | **Cross-site protection** | `Origin`, `Host` and `Sec-Fetch-Site` validation refuses web pages reaching the local port. A client that sends no `Origin` is not refused for that, but the `Host` check applies to every request, so a client reaching the gateway by a name it does not answer to is refused whether or not it is a browser | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md#browser-access-to-the-gateway-port) |
  242. | **End-user identity propagation** | Three configured strategies (`identity_propagation` config): gateway-signed assertion, client-token passthrough, and RFC 8693 token exchange. Fails closed when a backend requires identity. Per-user cache isolation. Enforced on dispatch, Code Mode, and direct routes. | [docs/adr/ADR-007-identity-propagation.md](docs/adr/ADR-007-identity-propagation.md) |
  243. | **Per-user OAuth isolation** | Fail-closed default (v3.0): a backend that requires a per-user OAuth identity refuses a call that lacks one instead of serving a shared stored token. Opt into the previous shared-credential behavior with `auth.single_user: true` (personal gateway) or `oauth.shared_account: true` (a specific backend). Upgrading from 2.x backs up `gateway.yaml` and prints a one-time posture notice; no config changes automatically. | [docs/adr/ADR-008-multi-user-oauth-isolation.md](docs/adr/ADR-008-multi-user-oauth-isolation.md), [docs/UPGRADING-3.0.md](docs/UPGRADING-3.0.md) |
  244. | **Cleartext credential refusal** | A backend whose configuration is credential-bearing — an `oauth` section, identity propagation, injected secrets, any static header whatever its name, or userinfo or a query in the URL — over plain `http://` to a host off this machine is refused at config load rather than started. Loopback is exempt; `allow_cleartext_credentials: true` on that backend accepts the exposure knowingly | [docs/REMOTE_BACKENDS.md](docs/REMOTE_BACKENDS.md#authenticated-remote-backends) |
  245. | **Per-client tool scopes** | Allowlist or denylist tools per API key with glob patterns | [examples/per-client-tool-scopes.yaml](examples/per-client-tool-scopes.yaml) |
  246. | **Security firewall** | Credential redaction, prompt-injection detection, and shell/SQL/path-traversal scanning | [CHANGELOG](CHANGELOG.md#260---2026-03-13) |
  247. | **Cost governance** | Per-tool, per-key, daily budgets with alert thresholds (log/notify/block) | [CHANGELOG](CHANGELOG.md#260---2026-03-13) |
  248. | **Session sandboxing** | Per-session call limits, duration caps, backend restrictions | [CHANGELOG](CHANGELOG.md#250---2026-03-12) |
  249. | **mTLS** | Certificate-based auth for tool execution | [CHANGELOG](CHANGELOG.md#240---2026-02-25) |
  250. ### Integration and discovery
  251. The gateway ships with **110+ built-in capabilities**: weather, Wikipedia, GitHub, stock quotes, package tracking, and more. Capability YAMLs hot-reload automatically after file changes, no restart needed.
  252. | Feature | Description |
  253. |---------|-------------|
  254. | **Capability system** | REST API to MCP tool via YAML. Hot-reloaded. [110+ built-in](capabilities/). OpenAPI import supported. |
  255. | **Transform chains** | Namespace, filter, rename, and response transforms. [Example](examples/transform-example.yaml). |
  256. | **Webhooks** | GitHub/Linear/Stripe push events as MCP notifications. [Docs](docs/WEBHOOKS.md). |
  257. | **Auto-discovery** | Discover MCP servers from existing client configs and running processes. |
  258. | **Surfaced tools** | Pin high-value tools directly in `tools/list` for one-hop invocation. |
  259. | **Semantic search** | TF-IDF ranked search across all tool names and descriptions. |
  260. | **Tool profiles** | Usage analytics per tool: latency, errors, trends. Persisted to disk. |
  261. | **Config export** | Export sanitized config as YAML or JSON via `mcp-gateway config export`. |
  262. ### Protocol and transport
  263. - **MCP versions**: the `initialize` handshake negotiates up to 2025-11-25. The newer 2026-07-28 revision is reached only on the stateless `POST /mcp` path, via the `MCP-Protocol-Version` header; it is served by default and is switched off with `server.modern_protocol: false`
  264. - **Transports**: stdio, Streamable HTTP, SSE, WebSocket
  265. - **Hot reload**: capability YAMLs and backends are watched and reloaded live. `server.public_url` and `control_plane.role_mapping` are re-read per request; everything else needs a restart
  266. - **Reload outcomes**: `gateway_reload_config` and `/ui/api/reload` report `restart_required`, and keep reporting it until a restart, for every field a reload cannot apply — which is every field outside that short live list, `auth` included. A reload that would leave the tool endpoint reachable without a credential is refused rather than applied
  267. - **Config discovery**: auto-finds `gateway.yaml` in cwd, `~/.config/mcp-gateway/`, and `/etc/mcp-gateway/`
  268. - **"Did you mean?"**: Levenshtein-based typo correction on tool names
  269. - **Tool annotations**: MCP 2025-11-25 `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`; gateway meta-tools are fully annotated, while backend tools use the hybrid pass-through/fill policy in [ADR-003](docs/adr/ADR-003-mcp-tool-annotation-policy.md)
  270. - **Dynamic descriptions**: live tool and server counts in meta-tool descriptions
  271. - **Tunnel mode**: expose via Tailscale or pipenet without opening ports
  272. - **Shell completions**: `mcp-gateway completions bash|zsh|fish`
  273. - **Spec preview** (opt-in): filtered `tools/list` (SEP-1821), `tools/resolve` (SEP-1862), dynamic promotion
  274. ### Supported backends
  275. Any MCP-compliant server works. All three transport types are supported:
  276. | Transport | Examples |
  277. |-----------|---------|
  278. | **stdio** | `@anthropic/mcp-server-tavily`, `@modelcontextprotocol/server-filesystem`, `@modelcontextprotocol/server-github` |
  279. | **HTTP** | Any Streamable HTTP server |
  280. | **SSE** | Pieces, LangChain, [GitMCP](https://gitmcp.io) (free remote docs and code search for any GitHub repo) |
  281. Remote MCP servers plug in by URL, with no extra code. See [examples/gateway-full.yaml](examples/gateway-full.yaml) for a commented GitMCP backend entry and [docs/REMOTE_BACKENDS.md](docs/REMOTE_BACKENDS.md) for a step-by-step walkthrough.
  282. ## Public MCP Gateway Comparison
  283. This table compares public, user-facing behavior, not internal roadmap scoring. MCP Gateway entries are grounded in this repo's public docs: [quickstart](QUICKSTART.md), [deployment](docs/DEPLOYMENT.md), [OWASP controls](docs/OWASP_AGENTIC_AI_COMPLIANCE.md), [TrustCard/CBOM](docs/trustcard.md), [CatalogTrustLab](docs/catalog_trust_lab.md), [adaptive ranking](docs/adaptive_ranking.md), [identity grants](docs/identity_grants.md), [ADR-007 identity propagation](docs/adr/ADR-007-identity-propagation.md), [ADR-008 multi-user OAuth isolation](docs/adr/ADR-008-multi-user-oauth-isolation.md). Competitor entries are grounded in public project docs: [Docker MCP Catalog and Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/), [MCPJungle README](https://github.com/mcpjungle/MCPJungle), [mcpo README](https://github.com/open-webui/mcpo), and [Supergateway README](https://github.com/supercorp-ai/supergateway).
  284. | Axis | **MCP Gateway** | **[Docker MCP Gateway / Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/)** | **[MCPJungle](https://github.com/mcpjungle/MCPJungle)** | **[mcpo](https://github.com/open-webui/mcpo) / [Supergateway](https://github.com/supercorp-ai/supergateway)** |
  285. |---|---|---|---|---|
  286. | Primary job | MCP and REST capability router with a compact meta-surface | Docker-managed catalog, profiles, containerized MCP servers, and gateway | Self-hosted gateway that runs many MCP servers behind one endpoint | Protocol bridges: MCP to OpenAPI for mcpo; stdio to SSE/WS for Supergateway |
  287. | Install | Standalone Rust binary via cargo, Homebrew, VS Code, Cursor, and local build | Docker Desktop / Docker CLI plugin flow | Self-hosted gateway install and server registration | Python/uvx/Docker for mcpo; npm/CLI bridge for Supergateway |
  288. | Configuration | Wizard, local starter profile, service templates, client export, doctor JSON, backup and rollback | Docker profiles and catalog selection | Centralized server and client configuration | Per-bridge command/config for each exposed server or transport |
  289. | Security | OWASP Agentic AI matrix, firewall, response inspection, hash-pinned capabilities, mTLS/signing options | Verified container images with versioning, provenance, and security updates in Docker catalog | Centralized access control and observability | Transport/API exposure layer; security depends on bridge auth and deployment boundary |
  290. | Identity and grants | Local identity-grant contract and CLI; multi-user OAuth isolation is credential-agnostic by default (ADR-008), and a backend configured `required` fails closed rather than serve a shared credential; per-user identity propagation to backends via signed assertion, caller-token passthrough, or RFC 8693 token exchange; the OIDC key server is disabled by default, delegated-bearer acceptance is a separate opt-in, and control-plane role mappings are issuer-scoped | Docker/team controls depend on Docker organization setup | Authenticated clients and server access control | Not a grant engine; delegates identity policy to the surrounding deployment |
  291. | Runtime isolation | RuntimeProvider policy planning plus Docker/Podman/Kubernetes deployment paths | Container-first isolation is the core runtime model | Runs and manages MCP servers behind the gateway | Bridges existing server processes/transports rather than isolating arbitrary tools |
  292. | Trust metadata | TrustCard/CBOM generation, validation, TrustLab evidence, provenance stubs | Catalog packages carry image provenance and security update flow | Gateway inventory and observability focus | Protocol metadata bridge; trust metadata is not the primary product surface |
  293. | Discovery | Meta-MCP listing/search, ShadowRadar unmanaged-server inventory, capability registry | Docker MCP Catalog of packaged servers | Centralized discovery across configured servers | Exposes one bridged server surface at a time unless composed externally |
  294. | Policy and governance | Policy, grants, audit events, read-only control-plane tab/API, enterprise evidence boundary | Docker org/catalog/profile policy model | Centralized access control for teams | No broad governance plane; use with another policy layer when needed |
  295. | Imports and bridges | Native MCP backends plus REST capability YAML and protocol-import planning | Docker-packaged MCP server catalog | MCP server aggregation | Strong bridge story for OpenAPI, SSE, WebSocket, and stdio compatibility |
  296. | Ranking and routing | Safety-aware ranking, explanations, cost/latency/trust/health signals | Catalog/profile selection, not an MCP tool ranker | Gateway-level routing to configured servers | Transport routing, not semantic tool ranking |
  297. | Deployment | Local, team gateway, Docker Compose, systemd, launchd, a security-hardened Helm chart (non-root, seccomp, read-only rootfs), and experimental (v1alpha1) Kubernetes CRDs | Docker Desktop, Docker CLI, Docker Hub/catalog workflow | Local or shared self-hosted gateway | Local or remote bridge process beside the target MCP server |
  298. | Licensing | PolyForm Noncommercial 1.0.0 throughout; free nonprofit permission; [commercial terms](COMMERCIAL.md) for other commercial use | Docker product and repository licensing apply | See project repository license | See each bridge repository license |
  299. ### vs Anthropic MCP tunnels
  300. On 2026-05-19 Anthropic shipped [Claude Managed Agents](https://claude.com/blog/claude-managed-agents-updates) with self-hosted sandboxes (public beta) and [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) (research preview). An MCP tunnel lets a Claude agent reach a single MCP server inside a private network through one outbound connection from a lightweight gateway, with no inbound firewall rules, no public endpoint, and end-to-end encryption.
  301. mcp-gateway and Anthropic's MCP tunnel sit at different layers and compose. The tunnel is reachability plumbing for one private MCP server. mcp-gateway is the aggregation, routing, capability-namespacing, and observability layer across many MCP and REST backends. Deploy both and mcp-gateway becomes the private MCP server that the tunnel exposes: one tunnel, one outbound connection, every backend behind it.
  302. | Concern | Anthropic MCP tunnel | mcp-gateway | Boundary |
  303. |---|---|---|---|
  304. | **Backend topology** | Single MCP server per tunnel, exposed through one outbound connection ([overview](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview)) | N-backend aggregation: 110+ REST capabilities plus multiple MCP backends behind a compact 9-17 tool meta-surface (`src/gateway/`, `capabilities/*.yaml`) | Different primitive: 1-server reachability vs many-backend aggregation |
  305. | **Tool routing** | Opaque pass-through; the agent sees whatever tool list the tunneled server publishes | Capability namespacing plus dynamic `gateway_search_tools` / `gateway_invoke` discovery (`src/gateway/`); SHA-256 pinning per capability (`src/capability/hash.rs`) | Different layer: transport reachability vs tool-surface curation and integrity |
  306. | **Observability** | Per-tunnel session telemetry from Anthropic's side | Unified `trace_id` and cost accounting across every backend invocation (`src/cost_accounting/`, `src/gateway/`) | Scope distinction: per-tunnel session vs cross-backend trace correlation |
  307. They solve adjacent problems. A team that wants Claude Managed Agents to reach a private-network deployment of mcp-gateway uses the tunnel for reachability and mcp-gateway for fan-out, capability hygiene, OWASP Agentic AI controls, and unified cost and trace telemetry.
  308. ## API
  309. | Endpoint | Method | Description |
  310. |----------|--------|-------------|
  311. | `/health` | GET | Health check with backend status; authenticated admin callers also see per-backend runtime profile lifecycle state |
  312. | `/mcp` | POST | Meta-MCP mode (dynamic discovery) |
  313. | `/mcp/{backend}` | POST | Direct backend access |
  314. | `/ui` | GET | Web dashboard |
  315. | `/ui/api/control-plane` | GET | Read-only local control-plane projection for inventory, runtime health, decisions, RBAC, and license boundaries |
  316. | `/dashboard` | GET | Operator dashboard. Admin only; opened with the single-use link `serve` prints on a loopback bind |
  317. | `/metrics` | GET | Prometheus metrics (with `--features metrics`) |
  318. ## Performance
  319. | Metric | Value | Notes |
  320. |--------|-------|-------|
  321. | **Startup time** | ~8ms | Measured with `hyperfine` ([benchmarks](docs/BENCHMARKS.md)) |
  322. | **Binary size** | ~12-13 MB | Release build with LTO, stripped |
  323. | **Hot-path microbenchmarks** | Included | Criterion suite covers registry, parsing, cache-key, firewall, and semantic-search hot paths |
  324. | **End-to-end latency** | Backend-dependent | Measure with your real MCP servers and REST APIs rather than relying on a synthetic single number |
  325. ## SKILL.md / agentskills.io compatibility
  326. MCP Gateway can ingest [Agent Skills](https://agentskills.io) and Claude Code `SKILL.md` files and expose them as discoverable skills alongside capability YAML. This lets the gateway consume any SKILL.md, whether authored locally, shipped from `agentskills.io`, or pulled from a GitHub release, and surface it through the same meta-tool surface used for capabilities.
  327. ```bash
  328. # Import a local skill directory (auto-discovers SKILL.md + resources/)
  329. mcp-gateway skills import ./skills/my-skill
  330. # Import a single SKILL.md file
  331. mcp-gateway skills import ./path/to/SKILL.md
  332. # Import from an agentskills.io URL
  333. mcp-gateway skills import https://agentskills.io/skills/my-skill/SKILL.md
  334. # List imported skills
  335. mcp-gateway skills list
  336. # Search by name, description, trigger, or keyword
  337. mcp-gateway skills search "gmail"
  338. # Show the full body (including any embedded code blocks)
  339. mcp-gateway skills show gws-gmail-send
  340. # Remove a skill
  341. mcp-gateway skills remove gws-gmail-send
  342. ```
  343. **What gets parsed**
  344. - YAML frontmatter (`name`, `description`, `version`, `effort`, `allowed-tools`, `triggers`, `keywords`)
  345. - Markdown body, with fenced `bash`/`python`/`json` code blocks extracted as structured `SkillCodeBlock` entries
  346. - Progressive-disclosure resources: `SKILL.advanced.md`, `reference.md`, `README.md`, and any `resources/*.md` files in the skill directory
  347. **Security model (read-only)**
  348. Imported skills are stored as data, not executed. Embedded `bash` or `python` blocks are parsed and surfaced to users and agents via `skills show`, but MCP Gateway will never run them automatically. A future release may add opt-in execution gated on per-skill user consent. To run a skill's commands today, copy them from `skills show` and run them in your own shell.
  349. Registry location: `~/.mcp-gateway/skills.json` (override with `MCP_GATEWAY_SKILLS_REGISTRY` or `--registry`).
  350. Reference: [Anthropic SKILL.md spec](https://docs.claude.com/en/docs/claude-code/skills) and [agentskills.io](https://agentskills.io).
  351. ## Documentation
  352. | Document | Contents |
  353. |----------|----------|
  354. | [Quick Start](docs/QUICKSTART.md) | Zero to running in 2 minutes |
  355. | [Annotated config example](examples/gateway-full.yaml) | Commented `gateway.yaml` covering the most-used config sections |
  356. | [OAuth Configuration](docs/OAUTH_CONFIG.md) | OAuth 2.0 setup with Slack and Figma examples |
  357. | [Upgrading to 4.0](docs/UPGRADING-4.0.md) | Per-issuer OAuth storage, strict `env_files` parsing, protocol floor, and the single-license change |
  358. | [Upgrading to 3.0](docs/UPGRADING-3.0.md) | Per-user OAuth isolation and identity-propagation upgrade path |
  359. | [Deployment Guide](docs/DEPLOYMENT.md) | Docker, systemd, TLS/mTLS, scaling |
  360. | [Multi-User Setup](docs/MULTI_USER.md) | Key server, policy scopes, per-backend identity propagation |
  361. | [OpenAPI Import](docs/OPENAPI_IMPORT.md) | Generate capabilities from OpenAPI specs |
  362. | [Webhooks](docs/WEBHOOKS.md) | Event integration setup |
  363. | [Community Registry](docs/COMMUNITY_REGISTRY.md) | Share and install capabilities |
  364. | [Benchmarks](docs/BENCHMARKS.md) | Performance measurements |
  365. | [Changelog](CHANGELOG.md) | Release history |
  366. | [OWASP Agentic AI Compliance](docs/OWASP_AGENTIC_AI_COMPLIANCE.md) | Risk coverage matrix |
  367. | [ShadowRadar](docs/SHADOW_SCAN.md) | Passive local discovery and static network-rule export |
  368. | [vs Anthropic MCP tunnels](#vs-anthropic-mcp-tunnels) | Where mcp-gateway and Anthropic's MCP tunnel compose |
  369. ## Troubleshooting
  370. **Backend will not connect?** Test the command directly (`npx -y @anthropic/mcp-server-tavily`), then check gateway logs with `--log-level debug`.
  371. **Circuit breaker open?** Ask your MCP client for `gateway_list_servers`: it
  372. reports `circuit_breaker` per backend and works on the shipped config. The HTTP
  373. equivalent, `curl -H "Authorization: Bearer $ADMIN_KEY" localhost:39400/health |
  374. jq '.backends'`, additionally needs `auth.enabled: true` and an admin
  375. credential — authentication is off by default, and while it is off every caller
  376. is anonymous, so the token is ignored and even a bearer-carrying request sees
  377. just `{count, all_healthy}`. Adjust thresholds in `failsafe.circuit_breaker`
  378. (default: opens after 5 consecutive failures, retries after 30s).
  379. **One tool went quiet, then came back on its own about five minutes later?**
  380. That is the per-capability error budget, not the circuit breaker — separate
  381. mechanism, separate keys. A capability whose failure rate crosses
  382. `error_budget.capability.threshold` is disabled on its own, leaving the rest of
  383. its backend serving, and re-enables itself on the next call once
  384. `error_budget.capability.cooldown` (default 5 minutes) has elapsed.
  385. `gateway_list_disabled_capabilities` names the ones currently suspended.
  386. **A whole backend went offline and stayed offline?** The backend-level error
  387. budget auto-killed it: its failure rate crossed `error_budget.threshold` over
  388. the sliding window. Unlike a capability, a killed backend does **not** come
  389. back by itself — revive it with `gateway_revive_server`, and raise the
  390. threshold or the window if the kill was premature. `gateway_list_servers`
  391. reports a killed backend as `"status": "disabled"`, which is how you tell an
  392. auto-kill apart from an open breaker.
  393. Every key of both budgets is documented inline in `examples/gateway-full.yaml`
  394. under `error_budget:`. Rate-limited responses (`429`, `RESOURCE_EXHAUSTED`) are
  395. excluded from both budgets: a throttled backend is a working backend, so
  396. throttling alone can neither kill a backend nor disable a capability.
  397. **Tools not appearing?** Verify the backend is running (`gateway_list_servers`). Tool lists are cached for 5 minutes.
  398. ## Versioning and stability
  399. This project follows [Semantic Versioning](https://semver.org/) over its
  400. **product surface**: the CLI, and the configuration file format. Changes to
  401. either are versioned accordingly — a config key that stops being accepted, or a
  402. command that changes behaviour, is a breaking change.
  403. **The Rust library API is not part of that surface.** Types are `pub` for
  404. modularity and testing, not as a supported embedding API, and they may change
  405. in any release. The crate ships a binary; at the time of writing crates.io
  406. reports zero reverse dependencies. If you embed the library, pin an exact
  407. version (`=4.0.0`) rather than a caret range.
  408. This is stated explicitly because "removing a `pub` field" and "breaking a
  409. supported API" are only the same thing when the API is supported. Here it is
  410. not, and that needs to be published rather than assumed.
  411. ## Contributing
  412. 1. Fork and branch (`git checkout -b feature/your-feature`)
  413. 2. Test (`cargo test`) and lint (`cargo fmt && cargo clippy -- -D warnings`)
  414. 3. Open a PR against `main` with a clear description and a [CHANGELOG](CHANGELOG.md) entry
  415. See [CONTRIBUTING.md](CONTRIBUTING.md) for full details. Look for [`good first issue`](https://github.com/MikkoParkkola/mcp-gateway/labels/good%20first%20issue) or [`help wanted`](https://github.com/MikkoParkkola/mcp-gateway/labels/help%20wanted) to get started.
  416. ## Ecosystem
  417. mcp-gateway is part of a suite of MCP tools:
  418. | Tool | Description |
  419. |------|-------------|
  420. | **[mcp-gateway](https://github.com/MikkoParkkola/mcp-gateway)** | **Universal MCP gateway: a compact 9-17 tool surface replaces 100+ registrations** |
  421. | [trvl](https://github.com/MikkoParkkola/trvl) | AI travel agent, 36 MCP tools for flights, hotels, ground transport |
  422. | [nab](https://github.com/MikkoParkkola/nab) | Web content extraction: fetch any URL with cookies and anti-bot bypass |
  423. | [axterminator](https://github.com/MikkoParkkola/axterminator) | macOS GUI automation, 34 MCP tools via the Accessibility API |
  424. ## License
  425. mcp-gateway is licensed under the **PolyForm Noncommercial License 1.0.0**
  426. ([LICENSE-NONCOMMERCIAL](LICENSE-NONCOMMERCIAL)). Every first-party file carries
  427. a copyright line and an explicit
  428. `// SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0` header. There is no
  429. second license and no allowlist.
  430. What this means:
  431. - **Permitted noncommercial and nonprofit use is free**, including running the whole gateway. See the [free-use permissions](COMMERCIAL.md#free-use-and-optional-support).
  432. - **Commercial use outside those free permissions requires a commercial license.** This covers
  433. the whole project — dispatch, transport, backend management, identity,
  434. security, governance — including the generic building blocks that earlier 3.x
  435. releases shipped under MIT headers. See [COMMERCIAL.md](COMMERCIAL.md).
  436. - Rights granted in earlier releases are not revoked. Versions 3.0.0–3.2.1 were
  437. published with MIT package metadata, and v3.3.0 onward in the 3.x line shipped
  438. a small MIT core under per-file headers. Those copies stay MIT for their
  439. recipients; from **v4.0.0** there is no MIT core. See [NOTICE.md](NOTICE.md).
  440. Full model: [LICENSES.md](LICENSES.md).
  441. ## Credits
  442. Created by [Mikko Parkkola](https://github.com/MikkoParkkola). Implements [Model Context Protocol](https://modelcontextprotocol.io/) versions 2025-11-25 and 2026-07-28; the newer revision is served by default and can be switched off.
  443. [Changelog](CHANGELOG.md) | [Releases](https://github.com/MikkoParkkola/mcp-gateway/releases)

Ratings and comments

Sign in to rate this skill.

Sign in

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