СообщенияТуннели MCP

Развертывание туннелей MCP с помощью Docker Compose

Установите стек туннелей MCP на виртуальной машине с помощью Docker Compose.

Туннели MCP находятся в стадии исследовательской предварительной версии. Запросите доступ, чтобы попробовать их.

Это руководство развертывает стек туннеля в виде защищенных контейнеров на одном хосте. Одну и ту же конфигурацию можно реплицировать на несколько хостов для обеспечения доступности.

Прежде чем начать

Вам потребуется:

Туннель. При программном доступе компонент настройки создает его за вас, если вы не указываете идентификатор туннеля; чтобы вместо этого подключиться к существующему туннелю, создайте его в Console и запишите идентификатор туннеля (tnl_...). Ручная подготовка всегда начинается с туннеля, созданного в Console.
Способ аутентификации хоста в Tunnels API.
- Программный доступ (рекомендуется). Включите Set up programmatic access при создании туннеля (или создайте правило федерации напрямую в разделе Settings > Workload identity, если вы позволяете компоненту настройки создать туннель), чтобы компонент настройки мог аутентифицироваться через Workload Identity Federation. Запишите идентификатор правила федерации (fdrl_...) и идентификатор вашей организации.
- Вручную. Пропустите программный доступ. Вы получите токен туннеля из Console, самостоятельно сгенерируете CA и серверный сертификат и зарегистрируете CA в Console.
Хост с установленными 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 (например, сервер метаданных облачной виртуальной машины или SPIFFE). Если его нет, используйте вкладку Без программного доступа.

Компонент настройки использует Workload Identity Federation для получения токена туннеля, генерации CA и серверного сертификата и регистрации CA в Anthropic.

Подготовьте каталог развертывания
mkdir -p mcp-tunnel/{config,data} cd mcp-tunnel sudo chown 65532:65532 data
Контейнеры работают от имени непривилегированного UID 65532 и нуждаются в доступе на запись к data/.

Напишите docker-compose.yaml

Файл compose фиксирует образы по дайджесту SHA-256, запускает каждый контейнер от имени непривилегированного пользователя с файловой системой только для чтения, отключает все возможности Linux и запрещает повышение привилегий.

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
    # Используем сетевое пространство имён (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

Подготовьте туннель
Задайте идентификаторы. Оставьте 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/: повторный запуск повторно использует идентификатор туннеля и CA, уже хранящиеся там, и никогда не создает второй туннель. Новый CA генерируется и регистрируется только тогда, когда data/ пуст или TUNNEL_ID изменился; в этом случае действует ограничение в два активных сертификата, поэтому сначала отзовите один в Console, если оба слота заняты.
См. Сбои аутентификации компонента настройки, если возникает ошибка.
Получите домен вашего туннеля и экспортируйте его для последующих шагов:
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain) echo "$TUNNEL_DOMAIN"
Токены Workload Identity Federation являются краткосрочными (по умолчанию 1 час) и истекают автоматически; после завершения настройки отзывать нечего.
Напишите конфигурацию прокси
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; замените его своими маршрутами (или добавьте их). См. справочник по конфигурации прокси для всех доступных полей.

Запустите развертывание

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

Файл compose считывает TUNNEL_TOKEN из окружения хоста без значения по умолчанию, поэтому экспорт необходимо повторять в каждой новой оболочке и после перезагрузки.

Для развертывания на нескольких виртуальных машинах скопируйте каталог mcp-tunnel/ на каждый хост, задайте TUNNEL_TOKEN и выполните docker compose up -d. В программном процессе TUNNEL_TOKEN — это $(sudo cat data/tunnel-token); в ручном процессе — это значение, которое вы скопировали из Console. Один и тот же токен туннеля и сертификаты работают на всех репликах.

Проверка развертывания

Проверьте работу от начала до конца, вызвав вышестоящий сервер MCP со стороны Anthropic: см. Использование туннелированных серверов MCP. С примером сервера MCP маршрутизируемый URL — https://echo.<your-tunnel-domain>/mcp. Если проверка не удалась, см. Устранение неполадок.

Обновления

Выполняйте команды из этого раздела изнутри каталога развертывания mcp-tunnel/.

Ротация токена туннеля

При программном доступе увеличьте --token-version в команде сервиса setup, задайте идентификаторы Workload Identity Federation, выпустите новый OIDC JWT и повторно запустите компонент настройки:

# Отредактируйте docker-compose.yaml: увеличьте целое число в аргументе
# --token-version сервиса setup (например, с --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_...   # если ваше правило ограничено рабочим пространством
# Повторно выпустите ANTHROPIC_IDENTITY_TOKEN согласно руководству по провайдеру WIF
# для вашей среды (срок его действия истёк с момента установки).
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 для отзыва нет.

Без программного доступа нажмите Rotate token на странице сведений о туннеле в Console, затем обновите переменную окружения TUNNEL_TOKEN на каждом хосте и перезапустите cloudflared (docker compose up -d cloudflared).

Нажатие Rotate token немедленно делает текущий токен недействительным. Между этим моментом и обновлением TUNNEL_TOKEN на каждом хосте с перезапуском cloudflared любой хост, чей cloudflared перезапускается (сбой, перезагрузка хоста), не сможет переподключиться. Оперативно обновите каждый хост после ротации.

Обновление сертификата

Вы несете ответственность за мониторинг срока действия и обновление серверного сертификата до его истечения.

С программным доступом:

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

Аргументы CLI заменяют command сервиса setup (аргументы init), но сохраняют его entrypoint, поэтому выполняется /setup renew-cert --output=dir:/data.

Передайте --renew-before=720h, чтобы команда ничего не делала, когда остается более 30 дней срока действия. Это делает безопасным ее запуск по фиксированному расписанию.

Без программного доступа подпишите новый серверный сертификат вашим существующим CA (CA, зарегистрированный в Console, не меняется) и замените data/tls.crt. Сначала задайте 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?

СообщенияТуннели MCP

Развертывание туннелей MCP с помощью Docker Compose

Установите стек туннелей MCP на виртуальной машине с помощью Docker Compose.

Прежде чем начать

Вам потребуется:

Туннель. При программном доступе компонент настройки создает его за вас, если вы не указываете идентификатор туннеля; чтобы вместо этого подключиться к существующему туннелю, создайте его в Console и запишите идентификатор туннеля (tnl_...). Ручная подготовка всегда начинается с туннеля, созданного в Console.
Способ аутентификации хоста в Tunnels API.
- Программный доступ (рекомендуется). Включите Set up programmatic access при создании туннеля (или создайте правило федерации напрямую в разделе Settings > Workload identity, если вы позволяете компоненту настройки создать туннель), чтобы компонент настройки мог аутентифицироваться через Workload Identity Federation. Запишите идентификатор правила федерации (fdrl_...) и идентификатор вашей организации.
- Вручную. Пропустите программный доступ. Вы получите токен туннеля из Console, самостоятельно сгенерируете CA и серверный сертификат и зарегистрируете CA в Console.
Хост с установленными 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/ и указывают, где добавить соответствующий сервис и маршрут.

Установка

Подготовьте каталог развертывания
mkdir -p mcp-tunnel/{config,data} cd mcp-tunnel sudo chown 65532:65532 data
Контейнеры работают от имени непривилегированного UID 65532 и нуждаются в доступе на запись к data/.

Напишите docker-compose.yaml

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
    # Используем сетевое пространство имён (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

Подготовьте туннель
Задайте идентификаторы. Оставьте 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/: повторный запуск повторно использует идентификатор туннеля и CA, уже хранящиеся там, и никогда не создает второй туннель. Новый CA генерируется и регистрируется только тогда, когда data/ пуст или TUNNEL_ID изменился; в этом случае действует ограничение в два активных сертификата, поэтому сначала отзовите один в Console, если оба слота заняты.
См. Сбои аутентификации компонента настройки, если возникает ошибка.
Получите домен вашего туннеля и экспортируйте его для последующих шагов:
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain) echo "$TUNNEL_DOMAIN"
Токены Workload Identity Federation являются краткосрочными (по умолчанию 1 час) и истекают автоматически; после завершения настройки отзывать нечего.
Напишите конфигурацию прокси
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; замените его своими маршрутами (или добавьте их). См. справочник по конфигурации прокси для всех доступных полей.

Запустите развертывание

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

Проверка развертывания

Обновления

Выполняйте команды из этого раздела изнутри каталога развертывания mcp-tunnel/.

Ротация токена туннеля

# Отредактируйте docker-compose.yaml: увеличьте целое число в аргументе
# --token-version сервиса setup (например, с --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_...   # если ваше правило ограничено рабочим пространством
# Повторно выпустите ANTHROPIC_IDENTITY_TOKEN согласно руководству по провайдеру WIF
# для вашей среды (срок его действия истёк с момента установки).
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

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

Следующие шаги

Использование туннелированных серверов MCP

Подключите вышестоящий сервер MCP к Managed Agent или Messages API.

Безопасность

Рекомендации по усилению защиты, ротация учетных данных и реагирование на взлом.

Устранение неполадок

Диагностика проблем с подключением, TLS и маршрутизацией.

Was this page helpful?

Прежде чем начать

Необязательно: используйте пример сервера MCP

Установка

Проверка развертывания

Обновления

Ротация токена туннеля

Обновление сертификата

Следующие шаги

Прежде чем начать

Необязательно: используйте пример сервера MCP

Установка

Проверка развертывания

Обновления

Ротация токена туннеля

Обновление сертификата

Следующие шаги

Прежде чем начать

Необязательно: используйте пример сервера MCP

Установка

Проверка развертывания

Обновления

Ротация токена туннеля

Обновление сертификата

Следующие шаги

Прежде чем начать

Необязательно: используйте пример сервера MCP

Установка

Проверка развертывания

Обновления

Ротация токена туннеля

Обновление сертификата

Следующие шаги