关于 run-mcp-gateway
run-mcp-gateway 是一项技能,通过 ngrok 暴露开发中的 MCP 服务,供多个 AI 模型提供商远程测试。它涵盖按提供商配置的 Bearer 令牌认证、流量检查和持久云端点。
主要功能
- 01为 MCP 配置流式 HTTP 传输
- 02按提供商进行 Bearer 令牌认证
- 03通过流量策略标记调用方
- 04将流量转发至内部 MCP 服务
- 05使用持久的公共云端点
适用场景
- 01通过多个提供商远程测试 MCP 服务
- 02通过稳定端点持续访问开发服务
- 03在流量日志中区分提供商调用
MCP 相关
指导通过 ngrok 端点和按提供商配置的认证,以流式 HTTP 向远程 MCP 客户端暴露用户的 MCP 服务。
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ ngrok/ skills --skill run-mcp-gateway安装后在 Claude Code 中输入/run-mcp-gateway确认已加载。
附带文件references/http-transport.tsreferences/traffic-policy.yaml
详细介绍
运行 MCP 网关
将开发中的 MCP(Model Context Protocol)服务公开出来,以便远程测试多个 AI 模型提供商,并支持针对每个提供商进行身份验证和流量检查。
开始之前
需要身份验证(ngrok-setup)。此任务使用云端点和内部端点,以及一项包含各提供商身份验证和 forward-internal 的流量策略——两者都来自 ngrok-engine。references/ 中提供了可运行的参考实现:http-transport.ts 和 traffic-policy.yaml。
架构
MCP client (Claude/OpenAI) --Bearer token--> Cloud Endpoint (public, runs the policy)
--forward-internal--> Agent Endpoint (bound internal, e.g. https://mcp.internal)
--HTTP--> your MCP server (streamable HTTP transport)
此处需要云端点(而非 Agent):各提供商会按自己的时间安排进行连接,因此公共 URL 必须独立于开发进程而持续有效。
步骤
-
为 MCP 服务添加 HTTP 传输。 MCP 开发服务通常使用 stdio;提供商需要可流式传输的 HTTP。将
references/http-transport.ts放入项目,并在现有的 stdio 路径旁调用它:await runHttp(buildServer, port); // POST /mcp, bound to 127.0.0.1这需要
express和@modelcontextprotocol/sdk。它默认绑定到回环地址,因此进程只能通过本地 ngrok Agent 访问——传入{ host }可更改此设置。stdio 仍可供本地客户端使用。 -
将服务作为内部端点运行。
.internalURL 会使其成为内部端点——无需额外的绑定标志:ngrok http <port> --url https://mcp.internal --host-header=rewrite--host-header=rewrite很重要:通过forward-internal到达的流量会携带Host: mcp.internal,而 MCP SDK 默认会拒绝该请求,以防 DNS 重绑定攻击。 -
创建一个保管库,并为每个提供商创建一个密钥。 这些是你生成的令牌(不是提供商的 API 密钥),因此可以区分不同的提供商:
ngrok api vaults create --name "mcp-callers" ngrok api secrets create --name "claude-key" --value "$(openssl rand -hex 32)" --vault-id "$VAULT_ID"当
ngrok-surfaces(“账户资源”)选择 ngrok MCP 服务时,请改用gw_create_vault和gw_create_secret,且不要索要 API 密钥。gw_create_secret会让用户前往仪表板表单输入值。让用户在自己的计算机上使用openssl rand -hex 32生成每个令牌,将其粘贴到该表单中,并留好令牌,以便在第 5 步为提供商配置设置。切勿在聊天中索要令牌。 -
使用策略创建云端点(
references/traffic-policy.yaml)。其结构对安全至关重要,因此请原样使用,不要重新推导:每个提供商对应一条规则,用于匹配该提供商的 bearer 令牌、标记调用方并执行forward-internal(这是终止操作);之后添加一条无条件的兜底规则,返回 401。任何未携带有效令牌的请求都不会匹配任何提供商规则,并会落入 401 规则。不要重新调整其结构,让拒绝规则改为检查
x-mcp-caller标记。该标头由策略添加,但它也是一个请求标头,因此客户端可以自行发送并完全绕过检查。根据适用场景,通过相应界面附加策略(参见
ngrok-surfaces):可持久使用的设置可选 Terraform 或 operator;快速设置可在 ngrok MCP 服务上使用gw_create_cloud_endpoint,或通过 CLI 使用ngrok api。 -
将每个提供商指向
https://<your-cloud-endpoint>/mcp,并将其 bearer 令牌设为自定义标头。之后要添加提供商,只需添加密钥并复制相应的策略规则。
注意事项
- 每个请求创建一个新的服务实例。 MCP 的无状态 HTTP 模式要求每个请求都使用全新的服务对象,以免多个并发提供商共享会话状态。
references/http-transport.ts遵循此模式。 - 调用方归属信息仅供参考。
x-mcp-caller会告知服务哪个提供商发起了调用,但持有任意有效令牌的客户端也可以自行发送该标头。可将其用于日志记录,但不要用于授权。 /mcp路径。 提供商期望 MCP 端点位于某个路径下(通常为/mcp);请确保传输配置与提供给用户的 URL 一致。- host-header rewrite(步骤 2)——转发的 MCP 请求返回 400 时,最常见的原因就是这一项。
给 Agent 的说明
- 这与
expose-localhost不同:它需要按提供方配置身份验证,并使用持久的云端端点,而不是普通隧道。 - 这是为用户自己的 MCP 服务准备的。要将 ngrok 的 MCP 服务连接到用户的 Agent,请参阅
ngrok-setup。 - 不要自行设计传输方式——使用随附的
http-transport.ts,并调整用户的buildServer。