Claude MCP Tunnels API Migration: The Endpoint Move Every Tunnel Operator Must Complete Now

If your team manages MCP tunnels through the Anthropic Admin API, your integration broke on June 22 — or it will break once the migration window closes. Anthropic moved the entire tunnels management surface from /v1/organizations/tunnels on the Admin API to /v1/tunnels on the Claude API, introduced a new beta header, and changed the required WIF scope. The old endpoints remain available during a migration window, but no end date has been published.

This is a routing-layer concern: MCP tunnels connect Claude Managed Agents to private-network MCP servers without opening inbound ports. If your organization provisions, rotates, or archives tunnels programmatically, the API surface you call just moved.

What changed on June 22

Three things shifted simultaneously:

1. Endpoint path. Tunnel CRUD operations (POST, GET, LIST, DELETE) moved from the Admin API at /v1/organizations/tunnels to the Claude API at /v1/tunnels. The Admin API endpoints are still available but are now legacy; Anthropic's documentation calls the new surface the canonical path.

2. Beta header. The new endpoints require anthropic-beta: mcp-tunnels-2026-06-22. Without this header, the Claude API returns an error. The previous Admin API surface did not require a beta header for tunnel operations.

3. WIF scope. Workload Identity Federation rules that provision tunnel credentials must now include the workspace:manage_tunnels scope. The previous Admin API used organization-level scopes. Teams using programmatic access — the recommended credential strategy — need to update their federation rules.

The old Admin API path remains live during a migration window. Anthropic has not published an end date, which means teams should treat this as a deprecation with unknown deadline — the worst kind for production planning.

Why it matters for AI engineering teams

MCP tunnels are the secure connectivity layer between Claude Managed Agents and private-network MCP servers. They use an outbound-only connection model (via Cloudflare's tunnel infrastructure) so organizations never need to expose internal services to the public internet. The management API controls tunnel lifecycle: creating tunnels, registering CA certificates, rotating credentials, and archiving decommissioned tunnels.

Teams that automate tunnel provisioning — which is what Anthropic recommends via WIF — have three integration points that need updating:

1. API client base URL. Requests go to api.anthropic.com/v1/tunnels instead of the Admin API host at /v1/organizations/tunnels.
2. Request headers. Every call must include both anthropic-version: 2023-06-01 and anthropic-beta: mcp-tunnels-2026-06-22.
3. Identity federation rules. The OIDC federation rule that authorizes your workload must include workspace:manage_tunnels in its scope set. Without it, token exchange succeeds but tunnel operations return 403.

If your tunnel provisioning runs in CI/CD or infrastructure-as-code pipelines, the scope change is the most dangerous: it fails silently at the authorization layer, not at the HTTP transport layer. Your pipeline gets a valid token, makes a valid-looking request, and receives a permissions error — potentially during a certificate rotation that leaves your tunnel unreachable.

The router/operator angle

For teams running AI workloads through a routing layer like TheRouter, MCP tunnels operate at the agent platform level, not the model API level. Standard OpenAI-compatible routing does not touch tunnel management. But the architectural pattern matters:

Credential rotation automation must track API surface migrations. If you automate credential lifecycle for any provider — API keys, WIF tokens, CA certificates — you need a process to detect when the management endpoint itself changes. This is a class of failure that key-rotation automation rarely accounts for: the rotation logic works, but the endpoint it targets has moved.

Beta headers create version-pinning risk. The mcp-tunnels-2026-06-22 header pins your client to a specific API revision. When Anthropic ships a new tunnels API version, the header value changes. Unlike model version pinning (where the old version has a published sunset date), beta API versions can change without a deprecation period — Anthropic's docs explicitly state this for the tunnels surface.

The Admin API to Claude API migration pattern may repeat. Anthropic is consolidating management surfaces onto the Claude API. Teams that integrate with other Admin API endpoints — organization management, workspace configuration, billing — should watch for similar migrations.

What to do now

1. Audit your tunnel management code. Search for /v1/organizations/tunnels in your codebase. Every hit needs to move to /v1/tunnels with the new beta header.

2. Update WIF federation rules. Add workspace:manage_tunnels to the scope set on any federation rule that manages tunnels. Test with a dry-run tunnel creation before the next certificate rotation.

3. Set a migration deadline. Anthropic has not published one. Pick your own — ideally before your next CA certificate renewal — and track it alongside model deprecation deadlines.

4. Monitor the beta header value. The tunnels API is in research preview. The header value will change when the API graduates or revises. Build your client to surface header-mismatch errors clearly, not as generic 400s.

The Tunnels API reference is at platform.claude.com/docs/en/api/beta/tunnels. The MCP tunnels overview, including network requirements and security model, is at platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview.