MCP Tunnels
Get Tunnel
get /v1/organizations/tunnels/{tunnel_id}
Retrieve a single tunnel in the caller's organization by ID.
Path Parameters
-
tunnel_id: stringID of the Tunnel.
Header Parameters
-
"anthropic-beta": array of "mcp-tunnels-2026-05-19"Required for all Tunnel endpoints.
"mcp-tunnels-2026-05-19"
Returns
-
id: stringID of the Tunnel.
-
archived_at: stringRFC 3339 datetime string indicating when the Tunnel was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the Tunnel was created.
-
display_name: stringHuman-readable name for the Tunnel (1–255 characters), or
nullif unset. -
domain: stringAnthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
-
type: "tunnel"Object type. Always
tunnelfor Tunnels."tunnel"
-
workspace_id: stringID of the Workspace this Tunnel belongs to, or
nullfor the default Workspace. Immutable after creation.
Example
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_WIF_BEARER_TOKEN"
Response
{
"id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "Production",
"domain": "a1b2c3d4.tunnel.anthropic.com",
"type": "tunnel",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
List Tunnels
get /v1/organizations/tunnels
List the organization's tunnels.
Results span the caller's organization, ordered by creation time
(newest first). Use workspace_id to filter to a single workspace;
archived tunnels are excluded unless include_archived is set.
Query Parameters
-
include_archived: optional booleanInclude archived tunnels in the results. Archived tunnels are excluded by default.
-
limit: optional numberMaximum number of tunnels to return in a single page.
-
page: optional stringOpaque pagination cursor from a previous response's
next_page. Omit to fetch the first page. -
workspace_id: optional stringReturn only tunnels in this Workspace. Accepts a
wrkspc_-prefixed Workspace ID; omit to list tunnels across all Workspaces.
Header Parameters
-
"anthropic-beta": array of "mcp-tunnels-2026-05-19"Required for all Tunnel endpoints.
"mcp-tunnels-2026-05-19"
Returns
-
data: array of object { id, archived_at, created_at, 4 more }-
id: stringID of the Tunnel.
-
archived_at: stringRFC 3339 datetime string indicating when the Tunnel was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the Tunnel was created.
-
display_name: stringHuman-readable name for the Tunnel (1–255 characters), or
nullif unset. -
domain: stringAnthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
-
type: "tunnel"Object type. Always
tunnelfor Tunnels."tunnel"
-
workspace_id: stringID of the Workspace this Tunnel belongs to, or
nullfor the default Workspace. Immutable after creation.
-
-
next_page: stringOpaque cursor for the next page, or
nullif there are no more results.
Example
curl https://api.anthropic.com/v1/organizations/tunnels \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_WIF_BEARER_TOKEN"
Response
{
"data": [
{
"id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "Production",
"domain": "a1b2c3d4.tunnel.anthropic.com",
"type": "tunnel",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
Reveal Tunnel Token
post /v1/organizations/tunnels/{tunnel_id}/reveal_token
Return the tunnel's current connection token.
The value is fetched live on each call; Anthropic does not store it.
Repeated calls return the same value until the token is rotated.
Exposed as POST so the token does not appear in intermediary
access logs.
Path Parameters
-
tunnel_id: stringID of the Tunnel.
Header Parameters
-
"anthropic-beta": array of "mcp-tunnels-2026-05-19"Required for all Tunnel endpoints.
"mcp-tunnels-2026-05-19"
Returns
-
id: stringStable identifier for the current token value. Changes when the token is rotated.
-
tunnel_token: stringThe tunnel's connection token.
-
type: "tunnel_token"Object type. Always
tunnel_tokenfor Tunnel Tokens."tunnel_token"
Example
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/reveal_token \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_WIF_BEARER_TOKEN"
Response
{
"id": "ttkn_bb97000eaec162831399ca9b6684a4fdf5be49ace5683057b017aab5c87e19e0",
"tunnel_token": "eyJhIjoiRVhBTVBMRSIsInQiOiJFWEFNUExFIiwicyI6IkVYQU1QTEUifQ==",
"type": "tunnel_token"
}
Rotate Tunnel Token
post /v1/organizations/tunnels/{tunnel_id}/rotate_token
Invalidate the tunnel's current token for new connections and return a fresh value.
Established connections are not severed by rotation; a connector
restarted after rotation must use the new value. An optional
reason is captured for operational context.
Path Parameters
-
tunnel_id: stringID of the Tunnel.
Header Parameters
-
"anthropic-beta": array of "mcp-tunnels-2026-05-19"Required for all Tunnel endpoints.
"mcp-tunnels-2026-05-19"
Body Parameters
-
reason: optional stringOptional free-text reason for the rotation, recorded for audit.
Returns
-
id: stringStable identifier for the current token value. Changes when the token is rotated.
-
tunnel_token: stringThe tunnel's connection token.
-
type: "tunnel_token"Object type. Always
tunnel_tokenfor Tunnel Tokens."tunnel_token"
Example
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/rotate_token \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_WIF_BEARER_TOKEN"
Response
{
"id": "ttkn_bb97000eaec162831399ca9b6684a4fdf5be49ace5683057b017aab5c87e19e0",
"tunnel_token": "eyJhIjoiRVhBTVBMRSIsInQiOiJFWEFNUExFIiwicyI6IkVYQU1QTEUifQ==",
"type": "tunnel_token"
}
Archive Tunnel
post /v1/organizations/tunnels/{tunnel_id}/archive
Archive a tunnel. Archival is irreversible.
Every non-archived certificate on the tunnel is archived in the same operation, the hostname is retired and never re-allocated, and the tunnel token is invalidated. Retrying against an already-archived tunnel returns the existing record unchanged.
Path Parameters
-
tunnel_id: stringID of the Tunnel.
Header Parameters
-
"anthropic-beta": array of "mcp-tunnels-2026-05-19"Required for all Tunnel endpoints.
"mcp-tunnels-2026-05-19"
Returns
-
id: stringID of the Tunnel.
-
archived_at: stringRFC 3339 datetime string indicating when the Tunnel was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the Tunnel was created.
-
display_name: stringHuman-readable name for the Tunnel (1–255 characters), or
nullif unset. -
domain: stringAnthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
-
type: "tunnel"Object type. Always
tunnelfor Tunnels."tunnel"
-
workspace_id: stringID of the Workspace this Tunnel belongs to, or
nullfor the default Workspace. Immutable after creation.
Example
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_WIF_BEARER_TOKEN"
Response
{
"id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "Production",
"domain": "a1b2c3d4.tunnel.anthropic.com",
"type": "tunnel",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
Domain Types
MCP Tunnel Retrieve Response
-
MCPTunnelRetrieveResponse object { id, archived_at, created_at, 4 more }-
id: stringID of the Tunnel.
-
archived_at: stringRFC 3339 datetime string indicating when the Tunnel was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the Tunnel was created.
-
display_name: stringHuman-readable name for the Tunnel (1–255 characters), or
nullif unset. -
domain: stringAnthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
-
type: "tunnel"Object type. Always
tunnelfor Tunnels."tunnel"
-
workspace_id: stringID of the Workspace this Tunnel belongs to, or
nullfor the default Workspace. Immutable after creation.
-
MCP Tunnel List Response
-
MCPTunnelListResponse object { data, next_page }-
data: array of object { id, archived_at, created_at, 4 more }-
id: stringID of the Tunnel.
-
archived_at: stringRFC 3339 datetime string indicating when the Tunnel was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the Tunnel was created.
-
display_name: stringHuman-readable name for the Tunnel (1–255 characters), or
nullif unset. -
domain: stringAnthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
-
type: "tunnel"Object type. Always
tunnelfor Tunnels."tunnel"
-
workspace_id: stringID of the Workspace this Tunnel belongs to, or
nullfor the default Workspace. Immutable after creation.
-
-
next_page: stringOpaque cursor for the next page, or
nullif there are no more results.
-
MCP Tunnel Reveal Token Response
-
MCPTunnelRevealTokenResponse object { id, tunnel_token, type }-
id: stringStable identifier for the current token value. Changes when the token is rotated.
-
tunnel_token: stringThe tunnel's connection token.
-
type: "tunnel_token"Object type. Always
tunnel_tokenfor Tunnel Tokens."tunnel_token"
-
MCP Tunnel Rotate Token Response
-
MCPTunnelRotateTokenResponse object { id, tunnel_token, type }-
id: stringStable identifier for the current token value. Changes when the token is rotated.
-
tunnel_token: stringThe tunnel's connection token.
-
type: "tunnel_token"Object type. Always
tunnel_tokenfor Tunnel Tokens."tunnel_token"
-
MCP Tunnel Archive Response
-
MCPTunnelArchiveResponse object { id, archived_at, created_at, 4 more }-
id: stringID of the Tunnel.
-
archived_at: stringRFC 3339 datetime string indicating when the Tunnel was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the Tunnel was created.
-
display_name: stringHuman-readable name for the Tunnel (1–255 characters), or
nullif unset. -
domain: stringAnthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
-
type: "tunnel"Object type. Always
tunnelfor Tunnels."tunnel"
-
workspace_id: stringID of the Workspace this Tunnel belongs to, or
nullfor the default Workspace. Immutable after creation.
-
Tunnel Certificates
Create Tunnel Certificate
post /v1/organizations/tunnels/{tunnel_id}/certificates
Register a public CA certificate for the tunnel.
Anthropic verifies the gateway's server certificate against this CA when it terminates the inner TLS session. The PEM body must contain exactly one X.509 certificate and no private-key material. A tunnel holds at most two non-archived certificates.
Path Parameters
-
tunnel_id: stringID of the Tunnel.
Header Parameters
-
"anthropic-beta": array of "mcp-tunnels-2026-05-19"Required for all Tunnel endpoints.
"mcp-tunnels-2026-05-19"
Body Parameters
-
ca_certificate_pem: stringPEM-encoded X.509 CA certificate. Must contain exactly one certificate and no private-key material.
Returns
-
id: stringID of the Tunnel Certificate.
-
archived_at: stringRFC 3339 datetime string indicating when the certificate was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the certificate was registered.
-
expires_at: stringRFC 3339 datetime string indicating when the certificate expires, or
nullif it does not expire. -
fingerprint: stringThe certificate's SHA-256 fingerprint, as a lowercase hex string.
-
tunnel_id: stringID of the Tunnel this certificate is registered against.
-
type: "tunnel_certificate"Object type. Always
tunnel_certificatefor Tunnel Certificates."tunnel_certificate"
Example
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_WIF_BEARER_TOKEN" \
-d '{
"ca_certificate_pem": "-----BEGIN CERTIFICATE-----\\nMIIBexampleEXAMPLEexampleEXAMPLEexampleEXAMPLEexampleEXAMPLEexa\\n...illustrative placeholder, not a real certificate...\\n-----END CERTIFICATE-----\\n"
}'
Response
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"type": "tunnel_certificate"
}
Get Tunnel Certificate
get /v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}
Retrieve a single certificate registered on a tunnel by ID.
Path Parameters
-
tunnel_id: stringID of the Tunnel.
-
certificate_id: stringID of the Tunnel Certificate.
Header Parameters
-
"anthropic-beta": array of "mcp-tunnels-2026-05-19"Required for all Tunnel endpoints.
"mcp-tunnels-2026-05-19"
Returns
-
id: stringID of the Tunnel Certificate.
-
archived_at: stringRFC 3339 datetime string indicating when the certificate was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the certificate was registered.
-
expires_at: stringRFC 3339 datetime string indicating when the certificate expires, or
nullif it does not expire. -
fingerprint: stringThe certificate's SHA-256 fingerprint, as a lowercase hex string.
-
tunnel_id: stringID of the Tunnel this certificate is registered against.
-
type: "tunnel_certificate"Object type. Always
tunnel_certificatefor Tunnel Certificates."tunnel_certificate"
Example
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_WIF_BEARER_TOKEN"
Response
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"type": "tunnel_certificate"
}
List Tunnel Certificates
get /v1/organizations/tunnels/{tunnel_id}/certificates
List the certificates registered on a tunnel.
Archived certificates are excluded unless include_archived is set.
Path Parameters
-
tunnel_id: stringID of the Tunnel.
Query Parameters
-
include_archived: optional booleanInclude archived certificates in the results. Archived certificates are excluded by default.
-
limit: optional numberMaximum number of certificates to return.
-
page: optional stringA tunnel has at most two active certificates, so this list is not paginated.
Header Parameters
-
"anthropic-beta": array of "mcp-tunnels-2026-05-19"Required for all Tunnel endpoints.
"mcp-tunnels-2026-05-19"
Returns
-
data: array of object { id, archived_at, created_at, 4 more }-
id: stringID of the Tunnel Certificate.
-
archived_at: stringRFC 3339 datetime string indicating when the certificate was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the certificate was registered.
-
expires_at: stringRFC 3339 datetime string indicating when the certificate expires, or
nullif it does not expire. -
fingerprint: stringThe certificate's SHA-256 fingerprint, as a lowercase hex string.
-
tunnel_id: stringID of the Tunnel this certificate is registered against.
-
type: "tunnel_certificate"Object type. Always
tunnel_certificatefor Tunnel Certificates."tunnel_certificate"
-
-
next_page: stringOpaque cursor for the next page, or
nullif there are no more results.
Example
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_WIF_BEARER_TOKEN"
Response
{
"data": [
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"type": "tunnel_certificate"
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
Archive Tunnel Certificate
post /v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}/archive
Archive a certificate, removing it from the set Anthropic trusts for this tunnel.
The certificate record is retained. Archiving the last non-archived certificate is permitted; the tunnel rejects MCP traffic until a new certificate is added.
Path Parameters
-
tunnel_id: stringID of the Tunnel.
-
certificate_id: stringID of the Tunnel Certificate.
Header Parameters
-
"anthropic-beta": array of "mcp-tunnels-2026-05-19"Required for all Tunnel endpoints.
"mcp-tunnels-2026-05-19"
Returns
-
id: stringID of the Tunnel Certificate.
-
archived_at: stringRFC 3339 datetime string indicating when the certificate was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the certificate was registered.
-
expires_at: stringRFC 3339 datetime string indicating when the certificate expires, or
nullif it does not expire. -
fingerprint: stringThe certificate's SHA-256 fingerprint, as a lowercase hex string.
-
tunnel_id: stringID of the Tunnel this certificate is registered against.
-
type: "tunnel_certificate"Object type. Always
tunnel_certificatefor Tunnel Certificates."tunnel_certificate"
Example
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_WIF_BEARER_TOKEN"
Response
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"type": "tunnel_certificate"
}
Domain Types
Tunnel Certificate Create Response
-
TunnelCertificateCreateResponse object { id, archived_at, created_at, 4 more }-
id: stringID of the Tunnel Certificate.
-
archived_at: stringRFC 3339 datetime string indicating when the certificate was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the certificate was registered.
-
expires_at: stringRFC 3339 datetime string indicating when the certificate expires, or
nullif it does not expire. -
fingerprint: stringThe certificate's SHA-256 fingerprint, as a lowercase hex string.
-
tunnel_id: stringID of the Tunnel this certificate is registered against.
-
type: "tunnel_certificate"Object type. Always
tunnel_certificatefor Tunnel Certificates."tunnel_certificate"
-
Tunnel Certificate Retrieve Response
-
TunnelCertificateRetrieveResponse object { id, archived_at, created_at, 4 more }-
id: stringID of the Tunnel Certificate.
-
archived_at: stringRFC 3339 datetime string indicating when the certificate was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the certificate was registered.
-
expires_at: stringRFC 3339 datetime string indicating when the certificate expires, or
nullif it does not expire. -
fingerprint: stringThe certificate's SHA-256 fingerprint, as a lowercase hex string.
-
tunnel_id: stringID of the Tunnel this certificate is registered against.
-
type: "tunnel_certificate"Object type. Always
tunnel_certificatefor Tunnel Certificates."tunnel_certificate"
-
Tunnel Certificate List Response
-
TunnelCertificateListResponse object { data, next_page }-
data: array of object { id, archived_at, created_at, 4 more }-
id: stringID of the Tunnel Certificate.
-
archived_at: stringRFC 3339 datetime string indicating when the certificate was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the certificate was registered.
-
expires_at: stringRFC 3339 datetime string indicating when the certificate expires, or
nullif it does not expire. -
fingerprint: stringThe certificate's SHA-256 fingerprint, as a lowercase hex string.
-
tunnel_id: stringID of the Tunnel this certificate is registered against.
-
type: "tunnel_certificate"Object type. Always
tunnel_certificatefor Tunnel Certificates."tunnel_certificate"
-
-
next_page: stringOpaque cursor for the next page, or
nullif there are no more results.
-
Tunnel Certificate Archive Response
-
TunnelCertificateArchiveResponse object { id, archived_at, created_at, 4 more }-
id: stringID of the Tunnel Certificate.
-
archived_at: stringRFC 3339 datetime string indicating when the certificate was archived, or
nullif it is not archived. -
created_at: stringRFC 3339 datetime string indicating when the certificate was registered.
-
expires_at: stringRFC 3339 datetime string indicating when the certificate expires, or
nullif it does not expire. -
fingerprint: stringThe certificate's SHA-256 fingerprint, as a lowercase hex string.
-
tunnel_id: stringID of the Tunnel this certificate is registered against.
-
type: "tunnel_certificate"Object type. Always
tunnel_certificatefor Tunnel Certificates."tunnel_certificate"
-