在家用手机驱动你的工作站:coding-tools-mcp 远程 MCP 隧道(cloudflared/ngrok)与 OAuth 认证快速上手-平芜编程栈

【免费下载链接】coding-tools-mcp

Give any AI agent the ability to code

项目地址：https://gitcode.com/gh_mirrors/co/coding-tools-mcp

coding-tools-mcp是一个让任何 AI 客户端都能安全读写代码仓库的 MCP 编程运行时。配合内置的远程 MCP 隧道（cloudflared / ngrok / Microsoft Dev Tunnel）与 OAuth 认证，你只需一条命令，就能把家里的电脑变成一台随时待命的编程工作站——然后掏出手机，让 ChatGPT、Grok 或 claude.ai 替你读代码、改文件、跑测试。

本文是一份面向新手的完整上手指南：如何搭建认证过的 HTTPS 隧道、如何配置 OAuth 2.1 + PKCE、如何在手机上接入你的工作站，以及远程暴露前必做的安全检查。

一、为什么需要远程 MCP 隧道？📱

平时使用 AI 编程，服务器和客户端都在同一台电脑上，通过 stdio 或本机127.0.0.1通信，天然安全。但当你想离开工作站、用手机继续写代码时，就遇到了两个问题：

服务器默认只绑定回环地址127.0.0.1:8765，公网根本访问不到；
工具集里包含apply_patch（改文件）和exec_command（跑命令）这类高权限工具，绝不能裸奔到公网。

coding-tools-mcp 的解法很干净：

本地回环服务器 + 带认证的 HTTPS 隧道。

服务器始终只监听127.0.0.1，通过 Model Context Protocol 的 Streamable HTTP 协议在/mcp端点提供服务；
隧道工具（cloudflared、ngrok 或 devtunnel）把这条本机地址"接一根管子"出去，得到一个https://<tunnel-host>/mcp公网地址；
认证二选一：Bearer token（静态密钥头）或OAuth 2.1 + PKCE（适合 ChatGPT 这类无法填自定义请求头的云端客户端）。

相关实现可参考 docs/remote-mcp.md 与 integrations/tunnels/tunnel.sh。

二、一分钟看懂三种隧道 Provider 🔌

Provider	适用场景	特点
`cloudflared`	首选，免账号	临时隧道自动分配`trycloudflare.com`地址，脚本默认选项
`ngrok`	想要固定域名	需账号；脚本支持自动安装（依赖 Homebrew 或 npm）
`devtunnel`	Windows / 微软生态	Microsoft Dev Tunnel，`--allow-anonymous`匿名托管

三个 provider 都封装在 integrations/tunnels/ 目录下：

integrations/tunnels/tunnel-cloudflared.sh
integrations/tunnels/tunnel-ngrok.sh
integrations/tunnels/tunnel-devtunnel.sh
公共逻辑（token 生成、启动服务器、打印接入配置）集中在 integrations/tunnels/tunnel-common.sh

三、最快上手：一行命令开通 cloudflared 隧道 ⚡

1. 获取代码并安装

git clone https://gitcode.com/gh_mirrors/co/coding-tools-mcp cd coding-tools-mcp scripts/install.sh --tunnel cloudflared --auto-install-tunnel --workspace /path/to/repo

安装脚本 scripts/install.sh 会自动完成三件事：

从 PyPI 安装coding-tools-mcp命令（优先用uv，否则pip）；
在127.0.0.1:8765启动 MCP 服务器，认证模式默认bearer，自动生成一个随机 token；
启动cloudflared隧道（缺少 CLI 时--auto-install-tunnel会自动装好）。

2. 拿到接入信息

脚本启动后会直接打印出你在手机上要填的内容：

URL: https://<tunnel-host>/mcp Header: Authorization: Bearer <token>

把 URL 和 Header 填入任意支持自定义请求头的 MCP 客户端，隧道就通了。✅

3. 已有仓库时：直接用 tunnel.sh

如果coding-tools-mcp已安装，等价的一行命令是：

export CODING_TOOLS_MCP_AUTH_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" CODING_TOOLS_MCP_AUTH_MODE=bearer integrations/tunnels/tunnel.sh cloudflared /path/to/repo

常用环境变量一览：

变量	作用	默认值
`CODING_TOOLS_MCP_AUTH_MODE`	认证模式：`bearer`/`noauth`/`oauth`	`bearer`
`CODING_TOOLS_MCP_AUTH_TOKEN`	复用已有 token（缺省自动生成）	—
`CODING_TOOLS_MCP_PORT`	本地 HTTP 端口	`8765`
`CODING_TOOLS_MCP_WORKSPACE`	工作区目录	当前目录
`CODING_TOOLS_MCP_AUTO_INSTALL_TUNNEL`	缺隧道 CLI 时自动安装	交互式询问

四、OAuth 认证：让 ChatGPT、Grok 也能接上 🔐

Bearer token 需要一个能填自定义Authorization请求头的客户端。但ChatGPT 的自定义连接器只支持 OAuth 或无认证，Grok 网页版也是云端 OAuth 流程——这时就轮到 OAuth 模式出场了。

1. 开启 OAuth 隧道

CODING_TOOLS_MCP_AUTH_MODE=oauth \ integrations/tunnels/tunnel.sh cloudflared /path/to/repo

服务器内置了完整的OAuth 2.1 Authorization Code + PKCE (S256)流程，并支持RFC 7591 动态客户端注册：客户端自己发现、自己注册，不需要你手工编 client ID 或复制 client secret。核心逻辑见 coding_tools_mcp/oauth.py。

脚本会打印出一串OAuth 密码——稍后客户端弹出授权页时输入它即可：

OAuth password: <一串随机密码> Client registration: https://<tunnel-host>/oauth/register (RFC 7591)

2. 关键规则（新手必读）

授权码一次性有效，5 分钟过期；access token 默认24 小时有效，且绑定到注册客户端和确切的 MCP 资源 URL；
动态注册是进程内的：服务器重启后，客户端需要重新注册一次；
临时隧道的域名每次都会变，服务器会从请求中自动推导 issuer；如果你配了固定域名，用CODING_TOOLS_MCP_SERVER_URL把它钉死，保证 issuer / audience / 发现 URL 恒定；
可选环境变量：CODING_TOOLS_MCP_OAUTH_PASSWORD（不填则自动生成并打印）、CODING_TOOLS_MCP_OAUTH_TOKEN_TTL（token 寿命，秒）、CODING_TOOLS_MCP_OAUTH_TOKEN_SECRET（稳定的 HS256 签名密钥）。

3. 手机端接入实战 📱

ChatGPT：设置 → Connectors → Advanced settings 打开开发者模式，新建自定义连接器指向https://<tunnel-host>/mcp。若 ChatGPT 能自行发现 OAuth 端点，授权页输入脚本打印的密码即可；若表单要你手填，则填 Authorization URL（/oauth/authorize）和 Token URL（/oauth/token），客户端 ID/secret 通过预注册方式提供：

CODING_TOOLS_MCP_OAUTH_CLIENT_ID=<client-id> \ CODING_TOOLS_MCP_OAUTH_CLIENT_SECRET=<secret> \ CODING_TOOLS_MCP_OAUTH_REDIRECT_URIS=<ChatGPT 展示的 redirect URI> \ CODING_TOOLS_MCP_AUTH_MODE=oauth \ integrations/tunnels/tunnel.sh cloudflared /path/to/repo

Grok：grok.com → Settings → Connectors，添加自定义连接器指向https://<tunnel-host>/mcp，弹窗里完成 OAuth 即可。

Gemini CLI / 通用 HTTP 客户端（支持自定义头时直接用 Bearer 隧道）：

gemini mcp add --transport http coding-tools https://<tunnel-host>/mcp \ --header "Authorization: Bearer <token>"

各客户端的完整配置示例在 docs/mcp-client-config.md。

4. 顺手验证一下隧道是否通了

curl "$BASE_URL/.well-known/mcp.json" curl "$BASE_URL/.well-known/oauth-protected-resource" curl "$BASE_URL/.well-known/oauth-authorization-server"

BASE_URL换成隧道 HTTPS 域名（不带/mcp）。Bearer 模式下，不带 token 的请求应返回401，带上正确 token 应能完成initialize握手。

五、图形化管理：桌面客户端 🖥️

不想碰命令行？项目自带一个 PySide6 桌面客户端（支持简体中文），能按工作区管理配置、一键启停服务器与隧道、切换 OAuth / Bearer / NoAuth、查看运行日志，还能一键复制 ChatGPT 自定义连接器需要填写的全部字段：

python -m pip install "coding-tools-mcp[desktop]" coding-tools-mcp-desktop

Cloudflare 支持临时隧道（trycloudflare.com地址）与命名隧道（固定域名）两种模式，详见 apps/desktop-client/README.md 与 apps/desktop-client/mcp_desktop_client/app.py。

六、安全清单：远程暴露前必做 5 件事 ✅

工具集包含改文件和跑命令的能力，远程部署请务必过一遍这份清单（原文见 docs/remote-mcp.md）：

永远不要把noauth暴露到公网——它只配给本机回环进程用；
坚持 HTTPS，定期轮换 Bearer token，OAuth 密码/签名密钥不要写进仓库；
权限模式保持在safe或trusted（见 docs/permission-modes.md），dangerous只给隔离容器/虚拟机用；
隧道认证的是"传输"，不是"代码执行"——对不信任的仓库，请把服务器跑进一次性 Docker 沙箱（见 docs/docker.md），用完即毁；
不要对公网端点使用--dangerously-fake-readonly-annotations，它会把apply_patch、exec_command谎报为只读工具，让对端客户端失去警惕。

七、常见问题排查 🔧

现象	原因与处理
请求返回`401`	Bearer 模式没带 token 或 token 不对；确认`Authorization: Bearer <token>`拼写
`GET /mcp`返回`405`	正常行为：端点只提供 Streamable HTTP POST，不提供 SSE 流
客户端保存了`Mcp-Session-Id`	0.3.0 起服务端无状态：旧会话头会被忽略而非报错，重连、换客户端都不丢状态
启动时报`cloudflared is not installed`	加`--auto-install-tunnel`，或设置`CODING_TOOLS_MCP_AUTO_INSTALL_TUNNEL=1`
反向代理后面识别不到真实来源	仅在你自己可控的代理后设置`CODING_TOOLS_MCP_TRUST_PROXY_HEADERS=1`；浏览器跨域来源可用`CODING_TOOLS_MCP_ALLOWED_ORIGINS`精确放行
`DELETE /mcp`返回`405`	无状态设计下没有可终止的会话，属预期行为

八、延伸阅读 📚

远程 MCP 完整文档（端点、注册规则、HTTP 会话行为）：docs/remote-mcp.md
各客户端接入配置（Claude Desktop / Cursor / VS Code / ChatGPT / Grok …）：docs/mcp-client-config.md
快速开始与本地启动：docs/quickstart.md
安全边界与 Landlock 隔离：docs/security-boundary.md
隧道脚本源码：integrations/tunnels/

搭好这条隧道后，你的工作方式可以是这样的：出门前对手机说一句"跑一下测试，把第一个失败修了"，回家时 commit 已经在等你了。🚀