
MCP Gateway
io.github.MikkoParkkola由 GitHub 账号 MikkoParkkola 发布v3.5.1更新于 Oct 24, 2026
Universal MCP gateway with Meta-MCP discovery, routing, and REST API capabilities.
概览
一个本地网关,把多个 MCP 服务器和 REST API 收拢到少量元工具之下,按需发现并路由后端工具。
- 可以做什么
- 通过网关的元工具搜索并调用后端工具,无需加载全部后端定义
- 从客户端配置导入已有 MCP 服务器、从内置注册表添加服务器,或手写网关配置
- 通过 YAML 能力文件或导入 OpenAPI 规范,把 REST API 暴露为工具
- 提供网页仪表板,可搜索工具、查看服务器健康状态、配置和成本统计
- 实施路由策略:按客户端限制工具范围、限流、熔断、重试,并支持后端热重载
- 适用场景
- 当你拥有大量 MCP 服务器或 REST API,希望用固定且精简的工具面替代把每个定义都塞进上下文时适用;也适合需要对工具后端集中施加策略、健康检查和审计点的场景。
- 运行要求
- 以本地进程运行(Homebrew、Cargo、直接下载二进制或 Docker 镜像),通过 gateway.yaml 配置。各后端可能需要自己的 API 密钥,并在配置中引用。非 full 版 Docker 镜像不含 Node 或 uv,无法启动 npx/uvx 后端。商业用途需要商业许可。
安装
在 SourceWeft 中
- 打开 控制台中的 MCP Gateway,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
MCP Gateway
[CI] [Crates.io] [Downloads] [Rust] [License] [unsafe denied] [dependency status] [Capabilities] [MCP Protocol] [OWASP Agentic AI] [Glama] [Quality Score] [Install in VS Code] [Install in Cursor]
One gateway between your AI and every tool it needs, without flooding the context window.
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.
Permitted noncommercial and nonprofit use is free, including running the full gateway. Commercial use outside these free permissions needs a commercial license.
The problem this removes
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.
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.
Quick Start
Four commands:
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-exampleswrites a workinggateway.yamlwith 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
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.
Direct binary download
Set up, three ways
Option A: auto-import everything (recommended)
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
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:
mcp-gateway list shows what is configured. mcp-gateway remove <name> removes one.
Option C: hand-write gateway.yaml
For the full schema, see the annotated 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 is the authoritative list. Minimal example:
Run and verify
The web dashboard is at http://localhost:39400/ui once serve is running. The
operator dashboard at /dashboard needs the admin credential, and a browser
cannot send one on a navigation — so serve prints a single-use link to open it
with, on a loopback bind. A network-bound gateway prints none and is managed
through /ui with the token instead. See
Opening the dashboard.
Connect AI clients (if you skipped Option A)
setup export writes the gateway entry into client config files for you. It auto-detects the right path per client:
Existing client files are backed up before mutation. The command prints the exact rollback command beside each updated client.
Modes: --mode proxy (HTTP), --mode stdio (subprocess), --mode auto (probe the health endpoint, then fall back).
Manual JSON snippet (if you prefer to edit by hand)
Why use MCP Gateway?
- 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.
- 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. - 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. - Per-user identity to backends. Multitenant backends can receive the verified end-user identity with no gateway-stored long-lived credential. See Multitenant identity.
- 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. - 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.
- Production resilience. Circuit breakers, retries with backoff, rate limiting, and health checks keep one flaky server from taking down the whole toolchain.
- Dual protocol. MCP plus an A2A (agent-to-agent) transport adapter, so the same gateway routes tool calls and cross-provider agent messages.
What MCP Gateway is, and what it is not
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.
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.
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.
Multitenant identity
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, ADR-008, and 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.
Independent reviews
- Five MCP hot-reload tools compared: Ruach Tov Collective's BPD-based comparison of mcp-gateway against four restart-focused alternatives, with a feature matrix and architectural analysis.
- mcp-gateway deep dive: a walkthrough of the capability system, SHA-256 integrity pinning, and the v2.5 to v2.9 development arc.
Quantitative claims in this README are sourced from docs/BENCHMARKS.md and the machine-readable benchmarks/public_claims.json, with a CI check that fails on drift.
Why the token math matters
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.
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.
Code Mode: two tools instead of the meta-tool set
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.
Security
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) and Simon Willison's summary (MCP has prompt injection security problems) lay out the threat model.
mcp-gateway puts every backend tool description behind one audit surface and defends it structurally:
- 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,sidenoteexfiltration language,curl .* https?://, andbase64in 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(19 tests). - Optional SHA-256 capability hash-pinning.
mcp-gateway cap pin <file>writes asha256:line over the file's canonical hash (grep -v '^sha256:' capability.yaml | sha256sumreproduces it from any shell). Unpinned files still load. A pinned file that no longer matches fails closed on load and on every watcher event. - 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.rsanddetect_rug_pullsinsrc/capability/backend.rs. - 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.
Full walkthrough, PoC snippets, and roadmap: docs/blog/security-aware-mcp-gateway.md.
- 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.
Recent additions
- 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: 22 tests acrosssrc/capability/openapi.rsandtests/openapi_import_tests.rs.
Architecture
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).
Features
Web dashboard
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.
Security and governance
Integration and discovery
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.
Protocol and transport
- MCP versions: the
initializehandshake negotiates up to 2025-11-25. The newer 2026-07-28 revision is reached only on the statelessPOST /mcppath, via theMCP-Protocol-Versionheader; it is served by default and is switched off withserver.modern_protocol: false - Transports: stdio, Streamable HTTP, SSE, WebSocket
- Hot reload: capability YAMLs and backends are watched and reloaded live.
server.public_urlandcontrol_plane.role_mappingare re-read per request; everything else needs a restart - Reload outcomes:
gateway_reload_configand/ui/api/reloadreportrestart_required, and keep reporting it until a restart, for every field a reload cannot apply — which is every field outside that short live list,authincluded. A reload that would leave the tool endpoint reachable without a credential is refused rather than applied - Config discovery: auto-finds
gateway.yamlin cwd,~/.config/mcp-gateway/, and/etc/mcp-gateway/ - "Did you mean?": Levenshtein-based typo correction on tool names
- 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 - Dynamic descriptions: live tool and server counts in meta-tool descriptions
- Tunnel mode: expose via Tailscale or pipenet without opening ports
- Shell completions:
mcp-gateway completions bash|zsh|fish - Spec preview (opt-in): filtered
tools/list(SEP-1821),tools/resolve(SEP-1862), dynamic promotion
Supported backends
Any MCP-compliant server works. All three transport types are supported:
Remote MCP servers plug in by URL, with no extra code. See examples/gateway-full.yaml for a commented GitMCP backend entry and docs/REMOTE_BACKENDS.md for a step-by-step walkthrough.
Public MCP Gateway Comparison
This table compares public, user-facing behavior, not internal roadmap scoring. MCP Gateway entries are grounded in this repo's public docs: quickstart, deployment, OWASP controls, TrustCard/CBOM, CatalogTrustLab, adaptive ranking, identity grants, ADR-007 identity propagation, ADR-008 multi-user OAuth isolation. Competitor entries are grounded in public project docs: Docker MCP Catalog and Toolkit, MCPJungle README, mcpo README, and Supergateway README.
vs Anthropic MCP tunnels
On 2026-05-19 Anthropic shipped Claude Managed Agents with self-hosted sandboxes (public beta) and MCP tunnels (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.
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.
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.
API
Performance
SKILL.md / agentskills.io compatibility
MCP Gateway can ingest Agent Skills 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.
What gets parsed
- YAML frontmatter (
name,description,version,effort,allowed-tools,triggers,keywords) - Markdown body, with fenced
bash/python/jsoncode blocks extracted as structuredSkillCodeBlockentries - Progressive-disclosure resources:
SKILL.advanced.md,reference.md,README.md, and anyresources/*.mdfiles in the skill directory
Security model (read-only)
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.
Registry location: ~/.mcp-gateway/skills.json (override with MCP_GATEWAY_SKILLS_REGISTRY or --registry).
Reference: Anthropic SKILL.md spec and agentskills.io.
Documentation
Troubleshooting
Backend will not connect? Test the command directly (npx -y @anthropic/mcp-server-tavily), then check gateway logs with --log-level debug.
Circuit breaker open? Ask your MCP client for gateway_list_servers: it
reports circuit_breaker per backend and works on the shipped config. The HTTP
equivalent, curl -H "Authorization: Bearer $ADMIN_KEY" localhost:39400/health | jq '.backends', additionally needs auth.enabled: true and an admin
credential — authentication is off by default, and while it is off every caller
is anonymous, so the token is ignored and even a bearer-carrying request sees
just {count, all_healthy}. Adjust thresholds in failsafe.circuit_breaker
(default: opens after 5 consecutive failures, retries after 30s).
One tool went quiet, then came back on its own about five minutes later?
That is the per-capability error budget, not the circuit breaker — separate
mechanism, separate keys. A capability whose failure rate crosses
error_budget.capability.threshold is disabled on its own, leaving the rest of
its backend serving, and re-enables itself on the next call once
error_budget.capability.cooldown (default 5 minutes) has elapsed.
gateway_list_disabled_capabilities names the ones currently suspended.
A whole backend went offline and stayed offline? The backend-level error
budget auto-killed it: its failure rate crossed error_budget.threshold over
the sliding window. Unlike a capability, a killed backend does not come
back by itself — revive it with gateway_revive_server, and raise the
threshold or the window if the kill was premature. gateway_list_servers
reports a killed backend as "status": "disabled", which is how you tell an
auto-kill apart from an open breaker.
Every key of both budgets is documented inline in examples/gateway-full.yaml
under error_budget:. Rate-limited responses (429, RESOURCE_EXHAUSTED) are
excluded from both budgets: a throttled backend is a working backend, so
throttling alone can neither kill a backend nor disable a capability.
Tools not appearing? Verify the backend is running (gateway_list_servers). Tool lists are cached for 5 minutes.
Versioning and stability
This project follows Semantic Versioning over its product surface: the CLI, and the configuration file format. Changes to either are versioned accordingly — a config key that stops being accepted, or a command that changes behaviour, is a breaking change.
The Rust library API is not part of that surface. Types are pub for
modularity and testing, not as a supported embedding API, and they may change
in any release. The crate ships a binary; at the time of writing crates.io
reports zero reverse dependencies. If you embed the library, pin an exact
version (=4.0.0) rather than a caret range.
This is stated explicitly because "removing a pub field" and "breaking a
supported API" are only the same thing when the API is supported. Here it is
not, and that needs to be published rather than assumed.
Contributing
- Fork and branch (
git checkout -b feature/your-feature) - Test (
cargo test) and lint (cargo fmt && cargo clippy -- -D warnings) - Open a PR against
mainwith a clear description and a CHANGELOG entry
See CONTRIBUTING.md for full details. Look for good first issue or help wanted to get started.
Ecosystem
mcp-gateway is part of a suite of MCP tools:
License
mcp-gateway is licensed under the PolyForm Noncommercial License 1.0.0
(LICENSE-NONCOMMERCIAL). Every first-party file carries
a copyright line and an explicit
// SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0 header. There is no
second license and no allowlist.
What this means:
- Permitted noncommercial and nonprofit use is free, including running the whole gateway. See the free-use permissions.
- Commercial use outside those free permissions requires a commercial license. This covers the whole project — dispatch, transport, backend management, identity, security, governance — including the generic building blocks that earlier 3.x releases shipped under MIT headers. See COMMERCIAL.md.
- Rights granted in earlier releases are not revoked. Versions 3.0.0–3.2.1 were published with MIT package metadata, and v3.3.0 onward in the 3.x line shipped a small MIT core under per-file headers. Those copies stay MIT for their recipients; from v4.0.0 there is no MIT core. See NOTICE.md.
Full model: LICENSES.md.
Credits
Created by Mikko Parkkola. Implements Model Context Protocol versions 2025-11-25 and 2026-07-28; the newer revision is served by default and can be switched off.
来源:README.md,提交 0d4f91d
工具
0版本历史
1- v3.5.1最新Sep 16, 2026
评分
已满足适用检查项的 40%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分
请在仓库或注册中心条目中声明许可证。