> ## Documentation Index
> Fetch the complete documentation index at: https://coding-1afcb9be.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 稳定远程 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：

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

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

```text theme={null}
https://mcp.example.com/mcp
```

## 选择鉴权模式

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

```bash theme={null}
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：

```bash theme={null}
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：

```bash theme={null}
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：

```bash theme={null}
ngrok http --domain=your-domain.ngrok-free.dev 8765
```

远程 MCP client 使用：

```text theme={null}
https://your-domain.ngrok-free.dev/mcp
```

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

```bash theme={null}
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 端口。

一次性设置：

```bash theme={null}
cloudflared tunnel login
cloudflared tunnel create coding-tools-mcp
cloudflared tunnel route dns coding-tools-mcp mcp.example.com
```

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

```yaml theme={null}
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：

```bash theme={null}
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：

```bash theme={null}
cloudflared tunnel run coding-tools-mcp
```

远程 MCP client 使用：

```text theme={null}
https://mcp.example.com/mcp
```

## demo 用 quick tunnel

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

```bash theme={null}
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：

```bash theme={null}
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：

```bash theme={null}
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，额外加上：

```bash theme={null}
-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 被分享过，及时轮换。