MessagesMCP 通道

使用 Docker Compose 部署 MCP 通道

使用 Docker Compose 在 VM 上安裝 MCP 通道堆疊。

MCP 通道目前處於研究預覽階段。申請存取權限以進行試用。

本指南將通道堆疊以強化容器的形式部署在單一主機上。相同的配置可以在多個主機上複製以提高可用性。

開始之前

您需要：

一個通道。 使用程式化存取時，如果您未提供通道 ID，設定元件會為您建立一個；若要改為附加到現有通道，請在 Console 中建立它並記錄通道 ID（tnl_...）。手動佈建一律從 Console 建立的通道開始。
主機向 Tunnels API 進行身份驗證的方式。
- 程式化存取（建議）。 在建立通道時開啟設定程式化存取（或者如果您讓設定元件建立通道，則直接在設定 > 工作負載身份下建立聯合規則），以便設定元件可以透過 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 伺服器，請使用這個最小化的伺服器：

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 的參考方法。您有責任調整它以符合您組織的安全需求。

此路徑要求主機具有 OIDC 身份提供者（例如雲端 VM 中繼資料伺服器或 SPIFFE）。如果沒有，請改用無程式化存取分頁。

設定元件使用 Workload Identity Federation 來取得通道權杖、產生 CA 和伺服器憑證，並向 Anthropic 註冊 CA。

Prepare the deployment directory
mkdir -p mcp-tunnel/{config,data} cd mcp-tunnel sudo chown 65532:65532 data
容器以非 root UID 65532 執行，並需要對 data/ 的寫入權限。

Write docker-compose.yaml

此 compose 檔案透過 SHA-256 摘要固定映像檔版本、以非 root 身份搭配唯讀檔案系統執行每個容器、移除所有 Linux capabilities，並停用權限提升。

cat > docker-compose.yaml <<'EOF'
services:
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - TUNNEL_ID
      - ANTHROPIC_FEDERATION_RULE_ID
      - ANTHROPIC_ORGANIZATION_ID
      - ANTHROPIC_WORKSPACE_ID
      - ANTHROPIC_IDENTITY_TOKEN
    volumes:
      - ./data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate run --url http://localhost:8080
    environment:
      - TUNNEL_TOKEN
    # 共用 proxy 的 netns，讓 localhost:8080 能連到它。
    network_mode: "service:mcp-proxy"
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  mcp-proxy:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    volumes:
      - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"
EOF

如果您使用範例 MCP 伺服器，請將其附加為一個服務：

cat >> docker-compose.yaml <<'EOF'

  hello-mcp:
    image: python:3.13-slim
    working_dir: /app
    volumes:
      - ./hello_server.py:/app/hello_server.py:ro
    command: sh -c "pip install --quiet mcp && python hello_server.py"
    restart: unless-stopped
EOF

Provision the tunnel
設定識別碼。保持 TUNNEL_ID 未設定可讓設定元件建立通道；設定它則可附加到來自 Console 的現有通道：
# export TUNNEL_ID=tnl_... # 設定此值以附加到現有的通道 export ANTHROPIC_FEDERATION_RULE_ID=fdrl_... export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
如果您的聯合規則的範圍是組織預設工作區以外的工作區，也請設定 ANTHROPIC_WORKSPACE_ID=wrkspc_...；否則設定元件會使用預設工作區。自動建立的通道會建立在該工作區中。
將 ANTHROPIC_IDENTITY_TOKEN 設定為來自此主機身份提供者的 OIDC JWT。請依照您的提供者的 WIF 指南註冊簽發者、設定規則的主體並鑄造權杖；規則的受眾必須與您鑄造權杖時請求的受眾相符。
執行設定元件：
docker compose run --rm setup
setup init 對 data/ 是冪等的：重新執行它會重複使用已儲存在那裡的通道 ID 和 CA，且絕不會建立第二個通道。只有當 data/ 為空或 TUNNEL_ID 已變更時，才會產生並註冊新的 CA；在這種情況下，兩個有效憑證的上限適用，因此如果兩個位置都已填滿，請先在 Console 中撤銷一個。
如果發生錯誤，請參閱設定元件身份驗證失敗。
取得您的通道網域並將其匯出以供後續步驟使用：
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain) echo "$TUNNEL_DOMAIN"
Workload Identity Federation 權杖是短期的（預設為 1 小時）且會自動過期；設定完成後沒有需要撤銷的內容。
Write the proxy config
tunnel_domain 是必要的：代理使用它在查詢 routes 中的子網域之前，從傳入的主機名稱中移除網域後綴。routes 是從子網域到上游 URL 的扁平映射，而不是列表。
cat > config/mcp-proxy.yaml <<EOF listen_addr: ":8080" log_level: info shutdown_timeout: 30s tunnel_domain: ${TUNNEL_DOMAIN} tls: cert_file: /data/tls.crt key_file: /data/tls.key routes: echo: http://hello-mcp:9000 EOF
echo: 路由指向範例 MCP 伺服器；請將其替換為（或新增）您自己的路由。請參閱代理配置參考以了解所有可用欄位。

Start the deployment

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

此 compose 檔案從主機環境讀取 TUNNEL_TOKEN 且沒有預設值，因此在每個新的 shell 中以及重新開機後都必須重複執行 export。

對於多 VM 部署，請將 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 服務命令中遞增 --token-version、設定 Workload Identity Federation 識別碼、鑄造新的 OIDC JWT，然後重新執行設定元件：

# 編輯 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 中編輯而不是在命令列上傳遞，以便新值在未來執行設定元件時持續存在。設定元件使用 Workload Identity Federation 進行身份驗證；沒有需要撤銷的 API 權杖。

若無程式化存取，請在 Console 的通道詳細資訊頁面上點擊輪替權杖，然後更新每個主機上的 TUNNEL_TOKEN 環境變數並重新啟動 cloudflared（docker compose up -d cloudflared）。

點擊輪替權杖會立即使目前的權杖失效。在那一刻與在每個主機上更新 TUNNEL_TOKEN 並重新啟動 cloudflared 之間，任何 cloudflared 重新啟動（當機、主機重新開機）的主機都無法重新連線。輪替後請立即更新每個主機。

憑證更新

您有責任監控到期時間並在伺服器憑證到期前更新它。

使用程式化存取時：

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

CLI 引數會取代 setup 服務的 command（即 init 引數）但保留其 entrypoint，因此這會執行 /setup renew-cert --output=dir:/data。

傳遞 --renew-before=720h 可使該命令在剩餘有效期超過 30 天時不執行任何操作。這使其可以安全地按固定排程執行。

若無程式化存取，請使用您現有的 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 並自動重新載入它，因此不需要重新啟動。

後續步驟

使用通道化的 MCP 伺服器

將上游 MCP 伺服器附加到 Managed Agent 或 Messages API。

安全性

強化指引、憑證輪替和入侵回應。

疑難排解

診斷連線、TLS 和路由問題。

Was this page helpful?

MessagesMCP 通道

使用 Docker Compose 部署 MCP 通道

使用 Docker Compose 在 VM 上安裝 MCP 通道堆疊。

MCP 通道目前處於研究預覽階段。申請存取權限以進行試用。

本指南將通道堆疊以強化容器的形式部署在單一主機上。相同的配置可以在多個主機上複製以提高可用性。

開始之前

您需要：

一個通道。 使用程式化存取時，如果您未提供通道 ID，設定元件會為您建立一個；若要改為附加到現有通道，請在 Console 中建立它並記錄通道 ID（tnl_...）。手動佈建一律從 Console 建立的通道開始。
主機向 Tunnels API 進行身份驗證的方式。
- 程式化存取（建議）。 在建立通道時開啟設定程式化存取（或者如果您讓設定元件建立通道，則直接在設定 > 工作負載身份下建立聯合規則），以便設定元件可以透過 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 伺服器，請使用這個最小化的伺服器：

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 的參考方法。您有責任調整它以符合您組織的安全需求。

此路徑要求主機具有 OIDC 身份提供者（例如雲端 VM 中繼資料伺服器或 SPIFFE）。如果沒有，請改用無程式化存取分頁。

設定元件使用 Workload Identity Federation 來取得通道權杖、產生 CA 和伺服器憑證，並向 Anthropic 註冊 CA。

Prepare the deployment directory
mkdir -p mcp-tunnel/{config,data} cd mcp-tunnel sudo chown 65532:65532 data
容器以非 root UID 65532 執行，並需要對 data/ 的寫入權限。

Write docker-compose.yaml

此 compose 檔案透過 SHA-256 摘要固定映像檔版本、以非 root 身份搭配唯讀檔案系統執行每個容器、移除所有 Linux capabilities，並停用權限提升。

cat > docker-compose.yaml <<'EOF'
services:
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - TUNNEL_ID
      - ANTHROPIC_FEDERATION_RULE_ID
      - ANTHROPIC_ORGANIZATION_ID
      - ANTHROPIC_WORKSPACE_ID
      - ANTHROPIC_IDENTITY_TOKEN
    volumes:
      - ./data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate run --url http://localhost:8080
    environment:
      - TUNNEL_TOKEN
    # 共用 proxy 的 netns，讓 localhost:8080 能連到它。
    network_mode: "service:mcp-proxy"
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  mcp-proxy:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    volumes:
      - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"
EOF

如果您使用範例 MCP 伺服器，請將其附加為一個服務：

cat >> docker-compose.yaml <<'EOF'

  hello-mcp:
    image: python:3.13-slim
    working_dir: /app
    volumes:
      - ./hello_server.py:/app/hello_server.py:ro
    command: sh -c "pip install --quiet mcp && python hello_server.py"
    restart: unless-stopped
EOF

Provision the tunnel
設定識別碼。保持 TUNNEL_ID 未設定可讓設定元件建立通道；設定它則可附加到來自 Console 的現有通道：
# export TUNNEL_ID=tnl_... # 設定此值以附加到現有的通道 export ANTHROPIC_FEDERATION_RULE_ID=fdrl_... export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
如果您的聯合規則的範圍是組織預設工作區以外的工作區，也請設定 ANTHROPIC_WORKSPACE_ID=wrkspc_...；否則設定元件會使用預設工作區。自動建立的通道會建立在該工作區中。
將 ANTHROPIC_IDENTITY_TOKEN 設定為來自此主機身份提供者的 OIDC JWT。請依照您的提供者的 WIF 指南註冊簽發者、設定規則的主體並鑄造權杖；規則的受眾必須與您鑄造權杖時請求的受眾相符。
執行設定元件：
docker compose run --rm setup
setup init 對 data/ 是冪等的：重新執行它會重複使用已儲存在那裡的通道 ID 和 CA，且絕不會建立第二個通道。只有當 data/ 為空或 TUNNEL_ID 已變更時，才會產生並註冊新的 CA；在這種情況下，兩個有效憑證的上限適用，因此如果兩個位置都已填滿，請先在 Console 中撤銷一個。
如果發生錯誤，請參閱設定元件身份驗證失敗。
取得您的通道網域並將其匯出以供後續步驟使用：
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain) echo "$TUNNEL_DOMAIN"
Workload Identity Federation 權杖是短期的（預設為 1 小時）且會自動過期；設定完成後沒有需要撤銷的內容。
Write the proxy config
tunnel_domain 是必要的：代理使用它在查詢 routes 中的子網域之前，從傳入的主機名稱中移除網域後綴。routes 是從子網域到上游 URL 的扁平映射，而不是列表。
cat > config/mcp-proxy.yaml <<EOF listen_addr: ":8080" log_level: info shutdown_timeout: 30s tunnel_domain: ${TUNNEL_DOMAIN} tls: cert_file: /data/tls.crt key_file: /data/tls.key routes: echo: http://hello-mcp:9000 EOF
echo: 路由指向範例 MCP 伺服器；請將其替換為（或新增）您自己的路由。請參閱代理配置參考以了解所有可用欄位。

Start the deployment

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

此 compose 檔案從主機環境讀取 TUNNEL_TOKEN 且沒有預設值，因此在每個新的 shell 中以及重新開機後都必須重複執行 export。

驗證部署

升級

請在 mcp-tunnel/ 部署目錄內執行本節中的命令。

輪替通道權杖

使用程式化存取時，在 setup 服務命令中遞增 --token-version、設定 Workload Identity Federation 識別碼、鑄造新的 OIDC JWT，然後重新執行設定元件：

# 編輯 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

憑證更新

您有責任監控到期時間並在伺服器憑證到期前更新它。

使用程式化存取時：

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

CLI 引數會取代 setup 服務的 command（即 init 引數）但保留其 entrypoint，因此這會執行 /setup renew-cert --output=dir:/data。

傳遞 --renew-before=720h 可使該命令在剩餘有效期超過 30 天時不執行任何操作。這使其可以安全地按固定排程執行。

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 並自動重新載入它，因此不需要重新啟動。

後續步驟

使用通道化的 MCP 伺服器

將上游 MCP 伺服器附加到 Managed Agent 或 Messages API。

安全性

強化指引、憑證輪替和入侵回應。

疑難排解

診斷連線、TLS 和路由問題。

Was this page helpful?

開始之前

選用：使用範例 MCP 伺服器

安裝

驗證部署

升級

輪替通道權杖

憑證更新

後續步驟

開始之前

選用：使用範例 MCP 伺服器

安裝

驗證部署

升級

輪替通道權杖

憑證更新

後續步驟

開始之前

選用：使用範例 MCP 伺服器

安裝

驗證部署

升級

輪替通道權杖

憑證更新

後續步驟

開始之前

選用：使用範例 MCP 伺服器

安裝

驗證部署

升級

輪替通道權杖

憑證更新

後續步驟