mcpField
R
run-mcp-gateway

run-mcp-gateway

github.com/ngrok云与 DevOps18143 次安装4 天前更新
代码仓库

关于 run-mcp-gateway

run-mcp-gateway 是一项技能,通过 ngrok 暴露开发中的 MCP 服务,供多个 AI 模型提供商远程测试。它涵盖按提供商配置的 Bearer 令牌认证、流量检查和持久云端点。

主要功能

  1. 01为 MCP 配置流式 HTTP 传输
  2. 02按提供商进行 Bearer 令牌认证
  3. 03通过流量策略标记调用方
  4. 04将流量转发至内部 MCP 服务
  5. 05使用持久的公共云端点

适用场景

  1. 01通过多个提供商远程测试 MCP 服务
  2. 02通过稳定端点持续访问开发服务
  3. 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 必须独立于开发进程而持续有效。

步骤

  1. 为 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 仍可供本地客户端使用。

  2. 将服务作为内部端点运行。 .internal URL 会使其成为内部端点——无需额外的绑定标志: ngrok http <port> --url https://mcp.internal --host-header=rewrite --host-header=rewrite 很重要:通过 forward-internal 到达的流量会携带 Host: mcp.internal,而 MCP SDK 默认会拒绝该请求,以防 DNS 重绑定攻击。

  3. 创建一个保管库,并为每个提供商创建一个密钥。 这些是你生成的令牌(不是提供商的 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 步为提供商配置设置。切勿在聊天中索要令牌。

  4. 使用策略创建云端点(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。

  5. 将每个提供商指向 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。

评论

支持 Markdown