稳定远程 URL

用 ngrok 或 Cloudflare 保持稳定 HTTPS MCP URL，同时让 Coding Tools MCP 继续绑定本机 loopback。

​

稳定远程 URL

当远程 MCP client 每天都需要使用同一个 HTTPS URL，而 Coding Tools MCP 仍然运行在你的本地机器上时，使用这个教程。

稳定域名解决的是一个问题：client 配置可以保持不变。它不会自动变成多人公用 relay，也不会自动发现每个开发者的电脑。

​

“一个 URL”有两种含义

常见设计有两类：

• 个人稳定 URL：一个开发者本地运行 Coding Tools MCP，通过 ngrok、Cloudflare Tunnel、devtunnel 或其他反向 tunnel，把 https://mcp.example.com/mcp 这样的稳定 hostname 映射到本机。
• 面向多用户的托管 relay：一个单独服务负责用户认证、设备注册、本地 agent 出站连接，并把每个请求路由到正确的 workspace。

Coding Tools MCP 提供本地 MCP runtime 和辅助 tunnel 脚本。它不包含托管 relay、dashboard、设备注册表或按用户路由的服务。

​

推荐 hostname 结构

把 MCP 流量放到子域名，不要直接放 apex domain：

docs.example.com       文档或营销站
app.example.com        如果你未来构建 dashboard，可放这里
mcp.example.com        Coding Tools MCP tunnel 或 relay 入口
local.example.com      私有 dogfood tunnel

本教程使用下面这个个人稳定 URL：

https://mcp.example.com/mcp

​

选择鉴权模式

如果 MCP client 支持 OAuth 2.1 Authorization Code + PKCE discovery，优先使用 OAuth：

export CODING_TOOLS_MCP_SERVER_URL="https://mcp.example.com"
export CODING_TOOLS_MCP_OAUTH_PASSWORD="replace-with-login-password"
export CODING_TOOLS_MCP_OAUTH_TOKEN_SECRET="$(python3 -c 'import secrets; print(secrets.token_bytes(32).hex())')"

coding-tools-mcp \
  --workspace /absolute/path/to/repo \
  --host 127.0.0.1 \
  --port 8765 \
  --tool-profile read-only \
  --oauth-mode

只有当 client 可以发送自定义 Authorization header 时，才使用 bearer auth：

export CODING_TOOLS_MCP_AUTH_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"

coding-tools-mcp \
  --workspace /absolute/path/to/repo \
  --host 127.0.0.1 \
  --port 8765 \
  --tool-profile read-only \
  --auth-token "$CODING_TOOLS_MCP_AUTH_TOKEN"

不要把 bearer token 放进 query string。Coding Tools MCP 在 /mcp 上检查的是 Authorization: Bearer <token> header。

​

ngrok reserved domain

先在 ngrok 里保留一个域名，然后让 Coding Tools MCP 绑定本机端口，再让 ngrok 指向这个端口。

终端 1：

export CODING_TOOLS_MCP_SERVER_URL="https://your-domain.ngrok-free.dev"
export CODING_TOOLS_MCP_OAUTH_PASSWORD="replace-with-login-password"
export CODING_TOOLS_MCP_OAUTH_TOKEN_SECRET="$(python3 -c 'import secrets; print(secrets.token_bytes(32).hex())')"

coding-tools-mcp \
  --workspace /absolute/path/to/repo \
  --host 127.0.0.1 \
  --port 8765 \
  --tool-profile read-only \
  --oauth-mode

终端 2：

ngrok http --domain=your-domain.ngrok-free.dev 8765

远程 MCP client 使用：

https://your-domain.ngrok-free.dev/mcp

仓库里的辅助脚本也可以用于快速运行 ngrok：

CODING_TOOLS_MCP_AUTH_MODE=oauth \
CODING_TOOLS_MCP_TOOL_PROFILE=read-only \
CODING_TOOLS_MCP_SERVER_URL="https://your-domain.ngrok-free.dev" \
scripts/tunnel.sh ngrok /absolute/path/to/repo

只有当你的 ngrok 配置已经固定 reserved domain 时，才把这个脚本当作稳定 URL 用法。否则脚本会启动普通 ngrok tunnel，URL 可能在重启后变化。

​

Cloudflare named tunnel

创建 named tunnel，并把 DNS hostname 路由到它。然后让这个 hostname 转发到本机 Coding Tools MCP 端口。

一次性设置：

cloudflared tunnel login
cloudflared tunnel create coding-tools-mcp
cloudflared tunnel route dns coding-tools-mcp mcp.example.com

创建或更新 Cloudflare tunnel 配置，让 hostname 指向本地 server：

tunnel: <tunnel-id>
credentials-file: /home/YOU/.cloudflared/<tunnel-id>.json
ingress:
  - hostname: mcp.example.com
    service: http://127.0.0.1:8765
  - service: http_status:404

终端 1：

export CODING_TOOLS_MCP_SERVER_URL="https://mcp.example.com"
export CODING_TOOLS_MCP_OAUTH_PASSWORD="replace-with-login-password"
export CODING_TOOLS_MCP_OAUTH_TOKEN_SECRET="$(python3 -c 'import secrets; print(secrets.token_bytes(32).hex())')"

coding-tools-mcp \
  --workspace /absolute/path/to/repo \
  --host 127.0.0.1 \
  --port 8765 \
  --tool-profile read-only \
  --oauth-mode

终端 2：

cloudflared tunnel run coding-tools-mcp

远程 MCP client 使用：

https://mcp.example.com/mcp

​

demo 用 quick tunnel

临时测试时，可以用仓库脚本安装 package、启动本地 server 并暴露 tunnel：

curl -fsSL https://raw.githubusercontent.com/xyTom/coding-tools-mcp/main/scripts/install.sh \
  | bash -s -- --tunnel cloudflared --auto-install-tunnel --workspace /absolute/path/to/repo

这适合 demo，但公开 URL 可能在重启后变化。如果 client 配置必须保持稳定，使用 ngrok reserved domain 或 Cloudflare named tunnel。

​

验证 URL

把 BASE_URL 替换为不带 /mcp 的 tunnel origin：

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

HTTP JSON-RPC ping：

curl "$BASE_URL/mcp" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  --data '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}'

如果使用 bearer auth，额外加上：

-H "Authorization: Bearer $CODING_TOOLS_MCP_AUTH_TOKEN"

​

安全注意事项

• 让 Coding Tools MCP 保持绑定 127.0.0.1，只暴露 tunnel URL。
• 远程会话先用 --tool-profile read-only，除非你明确需要写入工具。
• 所有非 loopback 部署都使用 OAuth 或 bearer auth。
• full 加 exec_command 等价于在配置的 workspace 边界内暴露远程代码执行能力。
• 测试结束后停止 tunnel；如果 token 或 OAuth secret 被分享过，及时轮换。