使用 Docker Compose 部署 MCP 隧道

本指南将隧道组件栈作为加固容器部署在单台主机上。相同的配置可以复制到多台主机以实现高可用性。

开始之前

您需要：

• 在 Console 中创建的隧道。 按照创建隧道的步骤操作，并记录隧道 ID（tnl_...）。
• 主机向 Tunnels API 进行身份验证的方式。
  • 编程式访问（推荐）。 在创建隧道时开启 Set up programmatic access（设置编程式访问），以便 setup 组件可以通过 "Workload Identity Federation"（工作负载身份联合）进行身份验证。记录联合规则 ID（fdrl_...）和您的组织 ID。
  • 手动方式。 跳过编程式访问。您需要从 Console 获取隧道令牌，自行生成 CA 和服务器证书，并在 Console 中注册 CA。
• 安装了 Docker 和 Docker Compose 的主机。手动流程还需要 openssl（1.1.1 或更高版本）。
• 从主机到 api.anthropic.com（443 TCP）和隧道边缘（7844 TCP 和 UDP）的出站网络连接。请参阅完整的网络要求。
• 一个或多个 MCP 服务器正在运行，并且可以通过您将在 routes 下配置的地址从主机访问。如果您还没有 MCP 服务器，请使用示例服务器。

可选：使用示例 MCP 服务器

如果您没有可用于测试的 MCP 服务器，请使用以下最小示例：

mkdir -p mcp-tunnel
cat > mcp-tunnel/hello_server.py <<'EOF'
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


@mcp.tool()
def hello(name: str = "world") -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"


if __name__ == "__main__":
    mcp.run(transport="streamable-http")
EOF

以下安装步骤会 cd 进入 mcp-tunnel/ 目录，并说明在何处添加相应的服务和路由。

安装

本指南提供了一种使用 Docker Compose 的参考方法。您需要自行调整以满足您组织的安全要求。

compose 文件从主机环境读取 TUNNEL_TOKEN 且没有默认值，因此必须在每个新的 shell 中以及重启后重新执行 export。

对于多虚拟机部署，将 mcp-tunnel/ 目录复制到每台主机，设置 TUNNEL_TOKEN，然后运行 docker compose up -d。在编程式流程中，TUNNEL_TOKEN 是 $(sudo cat data/tunnel-token)；在手动流程中，它是您从 Console 复制的值。相同的隧道令牌和证书适用于所有副本。

验证部署

通过从 Anthropic 一侧调用上游 MCP 服务器进行端到端验证：请参阅使用隧道化的 MCP 服务器。使用示例 MCP 服务器时，路由后的 URL 为 https://echo.<your-tunnel-domain>/mcp。如果验证失败，请参阅故障排除。

升级

在 mcp-tunnel/ 部署目录内运行本节中的命令。

轮换隧道令牌

使用编程式访问时，在 setup 服务的 command 中递增 --token-version，设置 Workload Identity Federation 标识符，生成新的 OIDC JWT，然后重新运行 setup 组件：

# 编辑 docker-compose.yaml：递增 setup 服务的 --token-version 参数中的
# 整数值（例如，将 --token-version=1 改为 --token-version=2）。
# 当该值未发生变化时，setup 二进制文件会拒绝执行轮换。
# 

export TUNNEL_ID=tnl_...
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_...   # 如果您的规则是工作区范围的
# 按照适用于您环境的 WIF 提供商指南重新生成 ANTHROPIC_IDENTITY_TOKEN
# （自安装以来它应已过期）。
export ANTHROPIC_IDENTITY_TOKEN=...

docker compose run --rm setup

export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -d cloudflared

--token-version 参数是在 docker-compose.yaml 中编辑而不是在命令行上传递的，这样新值会在 setup 组件的后续运行中持久保留。setup 组件使用 Workload Identity Federation 进行身份验证；没有需要撤销的 API 令牌。

不使用编程式访问时，在 Console 的隧道详情页面上点击 Rotate token（轮换令牌），然后在每台主机上更新 TUNNEL_TOKEN 环境变量并重启 cloudflared（docker compose up -d cloudflared）。

证书续期

您需要自行监控证书到期时间，并在服务器证书到期前进行续期。

使用编程式访问时：

docker compose run --rm setup renew-cert --output=dir:/data

这些 CLI 参数会替换 setup 服务的 command（即 init 参数），但保留其 entrypoint，因此实际运行的是 /setup renew-cert --output=dir:/data。

不使用编程式访问时，使用您现有的 CA 签发新的服务器证书（在 Console 中注册的 CA 不会更改），并替换 data/tls.crt。如果您是在新的 shell 中运行此命令，请先设置 TUNNEL_DOMAIN。

export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
  -subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
  -out data/tls.crt -days 90 \
  -extfile data/tls.ext

在任一流程中，代理都会轮询 tls.cert_file 并自动重新加载，因此无需重启。

后续步骤