Claude MCP Tunnels API 迁移：每个 tunnel 运维团队现在必须完成的 endpoint 切换

如果你的团队通过 Anthropic Admin API 管理 MCP tunnels，你的集成在 6 月 22 日已经（或即将）失效。Anthropic 把整个 tunnels 管理面从 Admin API 的 /v1/organizations/tunnels 迁移到了 Claude API 的 /v1/tunnels，同时引入了新的 beta header 并变更了 WIF scope。旧端点在迁移窗口期内仍然可用，但官方未公布窗口截止日期。

这是一个 routing 层面的关注点：MCP tunnels 将 Claude Managed Agents 连接到私有网络中的 MCP server，无需开放入站端口。如果你的组织以编程方式配置、轮换或归档 tunnels，调用的 API 面已经变了。

6 月 22 日的三项变更

1. Endpoint 路径。 Tunnel 的 CRUD 操作（POST、GET、LIST、DELETE）从 Admin API 的 /v1/organizations/tunnels 迁移到 Claude API 的 /v1/tunnels。Admin API 的旧端点仍然可用，但已被标记为 legacy；Anthropic 文档将新路径视为正式路径。

2. Beta header。 新端点要求携带 anthropic-beta: mcp-tunnels-2026-06-22。缺少该 header，Claude API 会返回错误。此前的 Admin API 并不要求 tunnel 操作附带 beta header。

3. WIF scope。 使用 Workload Identity Federation 配置 tunnel 凭据的规则现在需要包含 workspace:manage_tunnels scope。此前的 Admin API 使用的是组织级 scope。采用编程化凭据管理（Anthropic 推荐方式）的团队需要更新联邦规则。

旧 Admin API 路径在迁移窗口期内保持可用，但 Anthropic 没有公布截止日期——这意味着团队应当视为"截止时间未知的弃用"来对待，在生产规划中最为棘手。

为什么 AI 工程团队需要关注

MCP tunnels 是 Claude Managed Agents 与私有网络 MCP server 之间的安全连接层。它采用仅出站连接模型（通过 Cloudflare 隧道基础设施），组织无需将内部服务暴露到公网。管理 API 控制着 tunnel 的生命周期：创建 tunnel、注册 CA 证书、轮换凭据以及归档下线的 tunnel。

自动化 tunnel 配置的团队——这也是 Anthropic 通过 WIF 推荐的做法——有三个集成点需要更新：

1. API 客户端 base URL。 请求目标从 Admin API 的 /v1/organizations/tunnels 变为 api.anthropic.com/v1/tunnels。
2. 请求 header。 每次调用都必须同时携带 anthropic-version: 2023-06-01 和 anthropic-beta: mcp-tunnels-2026-06-22。
3. Identity federation 规则。 授权工作负载的 OIDC federation 规则必须在 scope 集合中包含 workspace:manage_tunnels。否则 token 交换会成功，但 tunnel 操作返回 403。

如果你的 tunnel 配置运行在 CI/CD 或基础设施即代码流水线中，scope 变更最为危险：它在授权层静默失败，而非 HTTP 传输层。流水线拿到有效 token、发出看起来合法的请求，然后收到权限错误——这可能发生在证书轮换期间，导致 tunnel 不可达。

Router/operator 视角

对于通过 TheRouter 等路由层运行 AI 工作负载的团队，MCP tunnels 在 agent 平台层运作，而非模型 API 层。标准 OpenAI 兼容路由不涉及 tunnel 管理。但这里的架构模式值得关注：

凭据轮换自动化必须追踪 API 面迁移。 如果你为任何 provider 自动化凭据生命周期——API key、WIF token、CA 证书——你需要一个机制来检测管理端点本身的迁移。这是 key 轮换自动化很少考虑的一类故障：轮换逻辑正常工作，但它请求的端点已经移走了。

Beta header 引入版本锁定风险。 mcp-tunnels-2026-06-22 header 将客户端锁定到特定 API 版本。当 Anthropic 发布新的 tunnels API 版本时，header 值会变更。与模型版本锁定不同（旧版本有明确的下线日期），beta API 版本可以在没有弃用期的情况下变更——Anthropic 文档对 tunnels 面明确声明了这一点。

Admin API 向 Claude API 的迁移模式可能重现。 Anthropic 正在将管理面整合到 Claude API 上。与其他 Admin API 端点——组织管理、workspace 配置、计费——有集成的团队，应当留意类似的迁移。

立即行动清单

1. 审计 tunnel 管理代码。 在代码库中搜索 /v1/organizations/tunnels，每个匹配项都需要迁移到 /v1/tunnels 并附带新的 beta header。

2. 更新 WIF federation 规则。 在管理 tunnel 的 federation 规则的 scope 集合中添加 workspace:manage_tunnels。在下一次证书轮换之前，先用 dry-run tunnel 创建来测试。

3. 设定迁移截止时间。 Anthropic 没有公布具体日期。自行设定一个——最好在下一次 CA 证书续期之前——并与模型弃用截止时间一并跟踪。

4. 监控 beta header 值。 Tunnels API 处于 research preview 阶段，header 值在 API 毕业或修订时会变更。构建客户端时应清晰显示 header 不匹配错误，而不是返回通用 400。

Tunnels API 参考文档见 platform.claude.com/docs/en/api/beta/tunnels。MCP tunnels 概览（含网络要求和安全模型）见 platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview。