后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载mcp-use/tunnel是 mcp-use 全栈 MCP 框架中的独立隧道客户端它通过托管的 mcp-use WebSocket 中继把运行在本机的 HTTP、WebSocket 或 MCP 服务器暴露为公网可访问的 HTTPS 地址。本文以 libraries/typescript/packages/tunnel/README.md 为核心结合 源码 与 测试 深入讲解它的 CLI 用法、参数语义、认证与状态持久化、断线重连机制以及底层转发协议。读完本文你将掌握用一条npx命令把本地 MCP 服务器临时暴露给 ChatGPT、Claude 等远程客户端进行联调的方法并理解其内部工作机制。一、包定位独立客户端与 mcp-use CLI 共用同一实现mcp-use/tunnel是一个独立的 npm 包当前仓库内版本为 0.2.1其作用正如包描述所言作为 mcp-use 的 WebSocket 隧道客户端将本地 HTTP、WebSocket 或 MCP 服务器暴露到公网。npx mcp-use/tunnel 3000这条命令会把本机3000端口上运行的服务映射到一个公共 HTTPS 地址之后远程的 MCP 客户端如 ChatGPT、Claude即可通过该公网地址访问你本地的 MCP 端点。值得强调的是它的设计定位同样的客户端代码同时驱动着mcp-use dev --tunnel与mcp-use start --tunnel两个框架命令。因此安装mcp-use本身并不需要再单独安装本包而当你只想手动暴露任意一个本地端口时才直接用npx mcp-use/tunnel 端口。这一点在包的 package.json 中也有印证它的bin字段注册了mcp-tunnel命令入口指向 dist/bin.js而 bin.ts 只有寥寥几行——直接调用 cli.ts 中的runTunnelCli真正的隧道生命周期管理则集中在 src/index.ts 的createTunnelManager中供独立 CLI 与框架内嵌路径共享。注意包要求 Node.js 22.22.2见 package.json 的engines字段因为实现依赖 Node 22 的原生WebSocket与fetch能力无需安装任何原生二进制或额外的包运行器子进程——这一点在 index.ts 的模块头注释中写得很清楚“The client connects directly to the relay over WebSocket. No native binary or package-runner subprocess is required.”二、命令行用法与选项详解2.1 命令语法README 给出的完整语法为mcp-tunnel LOCAL_PORT [--relay RELAY_URL] [--subdomain SUBDOMAIN]对应源码 cli.ts 中的usage()输出三个参数的含义如下参数说明LOCAL_PORT本机要暴露的 HTTP/WebSocket/MCP 服务器端口必填。必须是 1~65535 之间的整数否则抛出Invalid local port错误--relay RELAY_URL覆盖 WebSocket 中继的 API 地址。需要有效的 HTTP(S) URL缺少值会报--relay requires a URL--subdomain SUBDOMAIN请求一个稳定的隧道标识符子域。缺少值会报--subdomain requires a value参数解析逻辑位于 parseArgs-h/--help打印用法后退出以-开头的未知选项会抛出Unknown option重复传入端口或多余的位置参数会报Unexpected argument。这些行为在 bin.test.ts 中都有对应的断言例如parseArgs([0])抛出 “Invalid local port”parseArgs([3000, --unknown, value])抛出 “Unknown option”。2.2 环境变量MCP_USE_WS_RELAY除了命令行--relay之外还可以通过环境变量指定中继地址MCP_USE_WS_RELAYhttps://relay.example.com npx mcp-use/tunnel 3000在源码中三者优先级为显式传入的relayUrl选项 MCP_USE_WS_RELAY环境变量 默认生产中继https://api.tunnel.mcp-use.run见 index.ts 的tunnelApiBase。该函数还会校验协议必须是http:或https:否则抛错。这一设计便于在开发/测试环境下指向自建的中继部署例如 e2e 测试中就通过relayUrl指向本地 relay-fixture.ts 构造的测试中继。2.3 运行与优雅退出runTunnelClicli.ts在启动隧道后会打印一行Tunnel ready: https://adjective-color.tunnel.mcp-use.run然后挂起进程监听SIGINT与SIGTERM。收到任一信号时它会调用manager.stop()主动释放隧道保留并关闭 WebSocket 连接实现优雅退出停止完成后进程才真正结束。这意味着隧道仅在命令运行期间有效进程退出即失效——如果需要稳定的公共 URL应当部署服务器而不是依赖本地隧道。三、Host 头处理localhost 校验与 x-forwarded-hostREADME 中特别强调了一个对本地服务器友好的细节转发到本地服务器的请求携带Host: localhost与mcp-use start --tunnel的行为一致以满足本地主机校验原始的公共隧道主机名会保留在x-forwarded-host请求头中供依赖主机名的应用使用。这一行为由两个层面共同保证CLI 默认值runTunnelCli在创建 manager 时固定传入localHostHeader: localhostcli.ts因此独立 CLI 与框架命令行为完全一致。对应的单元测试也断言了这一点bin.test.ts。源码兜底逻辑在 index.ts 的handleRequestStart中如果localHostHeader有值则用它覆盖请求头的host否则回退到转发来的x-forwarded-host。同时sanitizeHeaders会剥离host、content-length以及各类 hop-by-hop 头如connection、transfer-encoding、upgrade等见 HOP_BY_HOP_HEADERS由隧道层重新生成可信的头部。端到端测试 e2e.test.ts 完整验证了这个语义默认情况下本地服务收到的host等于公共 URL 的主机名、x-forwarded-host也相同而当使用localHostHeader: localhost创建 manager 后本地服务收到的host变为localhost但x-forwarded-host依然保留公共主机名。这对那些绑定域名校验的本地框架例如对 Host 白名单敏感的 MCP 服务器非常友好——既通过了本地校验又不会丢失原始公网主机信息。四、保留、认证与状态持久化4.1 隧道保留Reservation流程每次启动隧道前客户端会先向中继申请一个“保留”申请POST {relayBase}/api/tunnels/request请求体为{}不指定子域或{subdomain: ...}指定子域10 秒超时reserveTunnel响应中继返回tunnel_id隧道标识即子域名、token认证令牌、connect_urlWebSocket 连接地址、public_url公共访问地址。任何字段缺失都会被视为无效保留并报错连接客户端随后建立到connect_url的 WebSocket连接打开后立即发送{type: authenticate, token: ...}控制消息完成认证中继回发{type: ready}后隧道才算就绪index.ts。也就是说保留是经过认证的——WebSocket 连接本身不携带凭证握手后必须显式完成 token 认证未经认证的连接无法转发流量。4.2 状态文件 .mcp-use/state/tunnel.json保留信息会被持久化到.mcp-use/state/tunnel.json位于当前工作目录下字段包括{ subdomain: quiet-amber, token: …, connect_url: wss://api.tunnel.mcp-use.run/connect/quiet-amber, public_url: https://quiet-amber.tunnel.mcp-use.run }源码中定义了对应的TunnelStateFile接口index.tssubdomain为上次成功分配的隧道标识token为保留认证值connect_url用于断线后重新挂接public_url为稳定的公共地址。持久化时目录会自动递归创建mkdirrecursive: true且文件以0o600权限写入persistState避免 token 泄露给其他系统用户写入失败仅打印警告不影响隧道运行。这份状态文件的价值在于重启后复用同一标识start()会先读取本地状态若保存的subdomain与请求一致或未指定子域优先尝试用已保存的保留直接挂接只有挂接失败或保留已失效时才会申请新的隧道index.ts。4.3 优雅关闭时释放保留stop()会向中继发送DELETE /api/tunnels/{subdomain}携带Authorization: Bearer token2 秒超时主动释放保留然后以关闭码 1000Client shutdown关闭 WebSocketstop。即使中继不可达导致释放失败中继侧的超时过期机制也会兜底清理——释放逻辑的注释明确写道 “Expiry provides the final cleanup path when the relay is unreachable”。e2e 测试中的releases the authenticated reservation during graceful shutdown用例正是断言停止后中继的删除计数为 1e2e.test.ts。五、断线自动重连与连接保活5.1 重连策略隧道建立后如果中继连接意外断开manager 不会直接放弃而是自动重连重挂reattach优先复用原保留的connect_url重新建立连接最多尝试 5 次REATTACH_ATTEMPTS退避时间从 1 秒起指数增长、上限 30 秒重新保留重挂失败后读取本地状态文件释放旧保留再申请新保留若保存的子域已不可用会打印提示并请求一个新标识终止条件当中继以关闭码 1008 关闭或关闭原因为 “Tunnel expired” / “Tunnel deleted” 时视为保留已终止必须申请全新保留否则一律按可重挂处理attach。整个调度逻辑封装在scheduleRespawnindex.ts中并用respawnInFlight防止并发重连start()期间若已有活跃连接则直接返回现有 URL。单元测试reattaches the same reservation after a deployment disconnect验证了这一点模拟中继断开后客户端自动建立了第二条指向同一connect_url的连接且未发起任何新的保留请求tunnel.test.ts。5.2 Keepalive 保活为防止空闲连接被中继回收客户端在收到中继ready消息且携带keepalive: true协商标志时会以 25 秒为周期发送{type: ping}控制消息并要求中继回pong若发出 ping 后未等到 pong即awaitingPong仍为真则判定连接失活并以 1011 关闭触发重连index.ts。测试同时覆盖了中继不支持 keepalive 协商时不发送 ping 的降级行为tunnel.test.ts。调试技巧设置环境变量MCP_USE_TUNNEL_DEBUG1可开启隧道层的调试日志前缀[mcp-use]用于观察重连、保留替换等内部事件index.ts。六、底层转发协议控制消息与二进制帧虽然使用方只需一条命令但理解底层协议有助于排查联调问题。客户端与中继之间的 WebSocket 同时承载两类数据1. JSON 控制消息文本帧包括authenticate认证、ready就绪、ping/pong保活、request-start请求开始含方法、路径、头、request-end/cancel请求结束/取消、response-start响应开始含状态码与头、response-end、response-error以及 WebSocket 相关的websocket-open/websocket-ready/websocket-close/websocket-error。单条控制消息上限 64 KiBMAX_CONTROL_MESSAGE_BYTES。2. 二进制帧请求/响应体与 WebSocket 数据帧格式为1 字节类型 36 字节 requestId 载荷。类型值在源码中以常量定义REQUEST_BODY_FRAME1、RESPONSE_BODY_FRAME2、公共 WebSocket 文本/二进制帧为 3/4、本地 WebSocket 文本/二进制帧为 5/6index.ts。requestId必须是 UUID v4 格式有专门的正则校验单帧载荷上限 256 KiBMAX_BODY_FRAME_BYTES超大响应体会自动分片发送。其他重要的工程约束包括并发本地请求上限 100MAX_LOCAL_REQUESTS超过则直接以 1008 关闭连接发送缓冲超过 1 MiBMAX_BUFFERED_SOCKET_BYTES时应用背压等待防止内存暴涨waitForSocketCapacity本地 WebSocket 在未 open 期间的入站消息先入队open 后按序冲刷缓冲区超限则以 1009 关闭并通知中继非法帧、非法 requestId、不支持的请求路径不以/开头或未知控制消息类型都会触发对应的关闭码1003/1008——单元测试rejects malformed frames, invalid identifiers, and unsupported messages对此有完整覆盖tunnel.test.ts。值得注意的是隧道是双向透明转发不仅支持普通 HTTP 请求还支持 WebSocket 升级。e2e 测试验证了公共 WebSocket 的文本与二进制消息都能双向回显e2e.test.ts同时还验证了 MCP JSON-RPC 请求、流式响应chunked以及 8 路并发请求的转发正确性e2e.test.ts。七、在 mcp-use 框架中使用隧道虽然本包可独立使用但最常见的场景还是与 mcp-use CLI 集成。官方指南 docs/tunneling/index.mdx 给出了完整流程开发阶段mcp-use dev --tunnel测试构建产物mcp-use build mcp-use start --port 3000 --tunnel启动成功后输出会同时给出本地与公共 MCP 端点例如[mcp-use] starting tunnel for port 3000… mcp-use server running at http://localhost:3000/mcp mcp-use public MCP URL: https://proper-black.tunnel.mcp-use.run/mcp关键点给客户端ChatGPT、Claude 等的 URL 必须以/mcp结尾只复制隧道源地址是不够的。之后可以用mcp-use clientCLI 快速验证隧道连通性npx mcp-use client connect tunnel-test https://proper-black.tunnel.mcp-use.run/mcp npx mcp-use client tunnel-test tools listconnect会完成 MCP 握手并把该隧道保存为tunnel-testtools list则列出你本地服务器暴露的工具。停止联调时在终端按CtrlC即可框架命令会同时停止本地服务器与隧道。另外由于中继同时转发 HTTP 与 WebSocket 升级在开发 MCP App 时通过公共隧道加载的视图依然能保持 Vite HMR 热更新——修改本地视图无需重启隧道即可在远端客户端看到变化。八、生命周期与配额限制隧道定位于部署前的本地联调而非长期公网服务因此存在明确的时限与配额见 docs/tunneling/index.mdx 的 “Lifetime and limits” 一节隧道仅在命令运行期间有效进程退出即失效框架命令运行期间掉线的隧道注册会自动重建从未连接成功的保留 5 分钟后过期已连接的隧道 24 小时后过期超过 1 小时无活动的隧道会被清理每个源 IP 每小时最多创建 10 条隧道同时最多保持 5 条活跃隧道。需要稳定公共 URL 时应直接部署服务器而不是依赖本地隧道。九、小结mcp-use/tunnel用一条命令解决了“本地 MCP 服务器如何被远程客户端访问”的问题通过托管的 WebSocket 中继完成认证保留、状态持久化、断线重连与双向流量转发且不依赖任何原生二进制。它既是独立的 CLI 工具npx mcp-use/tunnel 3000也是mcp-use dev --tunnel/mcp-use start --tunnel的内置能力——两者共享 createTunnelManager 这套实现。对本地开发而言它是把 ChatGPT、Claude 等远程 MCP 客户端接入本机服务器的最短路径需要验证细节时单元测试 与 端到端测试 都是很好的行为参考。赞分享后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载相关推荐Relay快速开始教程5步在本地部署你的AI团队协作平台Relay快速开始教程5步在本地部署你的AI团队协作平台 Relay 是一个开源的 多智能体协作平台 通过统一界面实现协作开发、代码审查和任务管理把多个人工智能AI Agent多智能体后端前端Mac Mouse Fix 上手指南3 步给普通鼠标加平滑滚动与侧键映射Mac Mouse Fix 上手指南3 步给普通鼠标加平滑滚动与侧键映射 Mac Mouse Fix 是一款 macOS 鼠标增强应用给第三方鼠标补上平滑滚桌面应用系统编程先楫 HPM5301EVKLITE 的 RT-Thread BSP 上手指南环境搭建、构建烧录与源码解析先楫 HPM5301EVKLITE 的 RT Thread BSP 上手指南环境搭建、构建烧录与源码解析 本指南以 RT Thread 仓库中的 HPM530操作系统嵌入式物联网嵌入式OSRTOS上一篇 QA Team Review Report下一篇LlamaIndex RedisChatStore 深度解析用 Redis 持久化跨进程 Chat Memoryllama-index-storage-chat-store-redis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考