# 在控制台中管理隧道

在 Claude 控制台中创建隧道、注册 CA 证书、获取隧道令牌，以及将隧道 MCP 服务器附加到智能体。

---

<Note>
  MCP 隧道是一项研究预览功能。[申请访问权限](https://claude.com/form/claude-managed-agents) 即可试用。
</Note>

本页介绍 MCP 隧道部署的控制台操作：创建隧道、注册 CA 证书、获取隧道令牌，以及将隧道服务器附加到智能体。[使用 Helm 部署 MCP 隧道](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm) 和 [使用 Docker Compose 部署 MCP 隧道](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose) 则涵盖在网络内部运行技术栈的内容。

## 前提条件

- **一个或多个 MCP 服务器**在您的私有网络中运行。隧道将流量路由到这些服务器，但不负责托管它们。
- **具有管理 MCP 隧道权限的角色**，用于创建和归档隧道、轮换令牌以及管理证书。没有此权限的组织开发者对 **MCP 隧道**页面和隧道详情只有只读访问权限。
- **一种让您的技术栈向 Tunnels API 进行身份验证的方式。**选择以下方式之一：
  - **编程访问（推荐）。**在创建隧道时设置 [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation)，这样您的技术栈可以从身份提供商获取短期 API 令牌、获取隧道令牌，并自动生成和注册 CA 证书。需要管理联邦规则的权限、已注册的 OIDC 颁发者，以及具有 `org:manage_tunnels` 范围的联邦规则。
  - **手动方式。**跳过编程访问。创建隧道后，[从控制台获取隧道令牌](#get-the-connection-details)，自行生成并 [注册 CA 证书](#add-a-ca-certificate)，然后将令牌和服务器证书作为密钥提供给您的部署。

## 创建隧道

<Steps>
  <Step title="打开 MCP 隧道页面">
    在控制台侧边栏中，前往 **Manage > MCP tunnels**。
  </Step>
  <Step title="命名隧道">
    点击 **New tunnel**，在 **Create tunnel** 对话框中输入名称。名称为必填项，用于在列表、详情页和智能体 MCP 服务器选择器中标识隧道。系统会自动分配一个类似 `abcd1234.tunnel.anthropic.com` 的域名。
  </Step>
  <Step title="可选：设置编程访问">
    **Set up programmatic access** 开关默认关闭。要开启它，您需要满足以下条件：

    1. **管理联邦规则的权限。**仅管理隧道本身不会授予此权限；如果您的角色可以创建隧道但不能创建联邦规则，控制台会隐藏该开关并显示提示。其余创建流程不变；您的部署将使用手动方式（在隧道创建后从控制台获取隧道令牌并注册 CA）。
    2. **已注册的 OIDC 颁发者**，用于您的技术栈将呈现令牌的身份提供商（如 Kubernetes 集群、AWS IAM、Google Cloud 或 GitHub Actions）。如果您的组织尚未注册，请在 **Settings > Workload identity > Issuers** 下注册一个。
    3. **具有 `org:manage_tunnels` 范围的联邦规则。**开启开关后会显示一个 **Federation rule** 选择器；每条规则都会显示其绑定的服务账户。选择一条已配置了隧道管理范围的现有规则，或点击 **Create federation rule** 内联创建一条；新规则表单允许您选择颁发者和服务账户。联邦规则将颁发者的令牌绑定到服务账户；服务账户是 Tunnels API 看到的主体。
    4. **将规则的服务账户添加到此工作区。**隧道是按工作区划分的，Tunnels API 根据服务账户的工作区成员资格进行授权。如果您在组织默认工作区以外的工作区中创建隧道，请在 **Settings > Workspaces** 下将该服务账户添加为该工作区的成员，并在部署时传递工作区 ID（Helm 为 `api.wif.workspaceId`，Compose 为 `ANTHROPIC_WORKSPACE_ID`）。有关规则、服务账户和工作区之间的关系，请参阅 [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation)。

    完全支持跳过此步骤；两个部署指南都有 **Without programmatic access** 选项卡。
  </Step>
  <Step title="创建隧道">
    点击 **Create tunnel**。控制台会配置隧道并打开详情页。
  </Step>
  <Step title="记录部署标识符">
    两种部署方式都需要：

    - **隧道 ID**（`tnl_...`），显示在隧道详情页上。
    - **隧道域名**（`abcd1234.tunnel.anthropic.com`），显示在隧道详情页上。用作代理的 `tunnel_domain` 和服务器证书的 SAN。

    **不使用编程访问时**，您还需要您的技术栈用于连接和身份验证的值：

    - **隧道令牌**，通过详情页上 **Token** 旁边的眼睛图标显示。这用于验证到隧道的出站连接；请将其视为密钥。参见 [获取连接详情](#get-the-connection-details)。
    - **CA 证书**，由您生成并 [在隧道上注册](#add-a-ca-certificate)。

    **使用编程访问时**，您的技术栈通过 Tunnels API 获取隧道令牌，并在本地生成 CA 和服务器证书（私钥永远不会离开您的环境），只需向 Anthropic 注册 CA 的公钥证书。您仍然负责保护私钥和在服务器证书过期前续期。记录您的技术栈通过 Workload Identity Federation 进行身份验证所需的标识符：

    - **联邦规则 ID**（`fdrl_...`），即您选择的规则的 ID。控制台不会将规则存储在隧道上；稍后可在 **Settings > Workload identity > Rules** 下找到。
    - **组织 ID**（UUID），显示在 **Settings > Organization** 下。
  </Step>
</Steps>

您的组织最多可以有 10 个活跃隧道。创建隧道不会建立任何连接；连接是在您的技术栈使用隧道令牌拨入并注册 CA 证书后建立的。

## 获取连接详情

打开隧道。详情页会显示一个包含域名和令牌的 **Connection** 部分，以及一个 **Certificates** 部分。

| 行 | 操作 |
|---|---|
| **Domain** | 复制分配的 `abcd1234.tunnel.anthropic.com` 值。您的代理路由是此域名的子域名。 |
| **Token** | 点击眼睛图标（**Show token**）获取隧道令牌，然后使用复制图标将其复制到部署的密钥存储中。点击 **Rotate token** 使当前令牌失效并签发新令牌。 |

<Note>
  每次显示和轮换都会被记录。轮换不会断开已建立的 cloudflared 连接，因此您可以轮换、使用新值重新部署，然后让旧连接自然排空。
</Note>

## 添加 CA 证书

Anthropic 通过您在隧道上注册的 CA 证书来验证到代理的内部 TLS 连接。没有活跃证书的隧道无法接受连接，并且在注册证书之前不会出现在智能体 MCP 服务器选择器中。

<Steps>
  <Step title="找到 Certificates 部分">
    在隧道详情页上，滚动到 **Certificates** 部分并点击 **Add certificate**。
  </Step>
  <Step title="提供证书">
    点击 **Choose file** 并选择 `.pem`、`.crt` 或 `.cer` 文件，将文件拖到文本区域，或直接粘贴 PEM 块。对话框会拒绝私钥内容和非 `-----BEGIN CERTIFICATE-----` 块的内容。文件大小必须为 8 kB 或更小。
  </Step>
  <Step title="添加证书">
    点击 **Add certificate**。指纹和有效期会出现在证书列表中，部分标题上的槽位计数会递增。
  </Step>
</Steps>

一个隧道最多可容纳两个活跃证书，以便您可以在不停机的情况下进行轮换：将新证书与旧证书一起注册，使用新密钥对重新部署代理，确认流量正常流动，然后在旧行的行上点击 **Revoke**。已撤销的证书仍会在列表中显示，并带有 **Revoked** 徽章。

## 部署技术栈

隧道已在控制台中创建，但在技术栈在您的网络中运行并使用隧道令牌拨入之前，不会有流量流动。请按照以下部署指南之一操作：

<CardGroup cols={2}>
  <Card title="使用 Docker Compose 部署" icon="cube" href="/docs/en/agents-and-tools/mcp-tunnels/deploy-compose">
    在单台主机上运行技术栈。支持编程访问和手动方式。
  </Card>
  <Card title="使用 Helm 部署" icon="stack" href="/docs/en/agents-and-tools/mcp-tunnels/deploy-helm">
    在 Kubernetes 集群上运行技术栈。支持编程访问和手动方式。
  </Card>
</CardGroup>

## 在智能体中使用隧道

一旦您的技术栈运行并配置了一个或多个 MCP 服务器，即可将隧道 MCP 服务器附加到 Managed Agent 会话。要改为从 Messages API 调用相同的服务器，请参阅 [使用隧道 MCP 服务器](/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers)。

<Note>
  选择器只显示至少有一个活跃证书的隧道。在 **MCP tunnels** 列表中仍显示 **Needs certificate** 的隧道不会出现在下拉菜单中；请先注册 CA 证书。选择器也是按工作区划分的：它列出与会话在同一工作区中的隧道，而不是其他工作区。
</Note>

<Steps>
  <Step title="打开 New session 对话框">
    前往 **Managed Agents > Sessions** 并点击 **New session**。
  </Step>
  <Step title="定义内联智能体">
    在智能体选择器中，选择 **Create new agent**，以便直接编辑 MCP 服务器列表。
  </Step>
  <Step title="添加 MCP 服务器">
    点击 **+ MCP Server** 并打开下拉菜单。在当前工作区中创建的隧道会出现在列表顶部，位于公共连接器目录之上。选择连接到您要访问的服务器的隧道。
  </Step>
  <Step title="提供路由信息">
    卡片显示两个可选字段：**Subdomain**（作为隧道域名的前缀）和 **Path**（附加在域名之后）。输入您的代理路由所使用的值。**Resolves to** 行显示将写入 `agent.mcp_servers` 的确切 URL。
  </Step>
</Steps>

<Note>
  隧道传输流量；它不对上游进行身份验证。在 MCP 服务器上配置 OAuth 或 bearer auth 的方式与任何其他 MCP 服务器相同。
</Note>

## 归档隧道

归档会立即停止隧道接受连接，且操作是永久性的。

在 **MCP tunnels** 列表中，打开隧道的行菜单并选择 **Archive**。归档的隧道在按 **Archived** 或 **All** 筛选列表时仍可见。

## 后续步骤

<CardGroup cols={2}>
  <Card title="使用 Helm 部署" icon="stack" href="/docs/en/agents-and-tools/mcp-tunnels/deploy-helm">
    使用 Anthropic Helm chart 在 Kubernetes 集群上安装。
  </Card>
  <Card title="安全" icon="lock" href="/docs/en/agents-and-tools/mcp-tunnels/security">
    加固指南、凭据轮换和泄露响应。
  </Card>
</CardGroup>