from line 1
1---
2title: Tunnels
3url: https://platform.claude.com/docs/en/api/beta/tunnels
4---
5
61# Tunnels
72
83## Create Tunnel
94
10**post** `/v1/tunnels`
5**POST** `/v1/tunnels`
116
127The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
138
149Creates a tunnel. Creation allocates a fresh hostname and provisions the tunnel; it is not idempotent. The new tunnel rejects MCP traffic until at least one CA certificate is added.
1510
16### Header Parameters
11### Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Body Parameters
89### Body parameters
9590
9691- `display_name: optional string or null`
9792
9893 Optional human-readable name for the tunnel (1-255 characters).
9994
95 minLength: 1, maxLength: 255
96
10097### Returns
10198
102- `BetaTunnel object { id, archived_at, created_at, 3 more }`
99- `BetaTunnel object`
103100
104101 An MCP tunnel.
105102
from line 108
111108
112109 A timestamp in RFC 3339 format
113110
111 format: date-time
112
114113 - `created_at: string`
115114
116115 A timestamp in RFC 3339 format
117116
117 format: date-time
118
118119 - `display_name: string or null`
119120
120121 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 126
125126
126127 - `type: "tunnel"`
127128
128 - `"tunnel"`
129
130129### Example
131130
132```http
131```bash
133132curl https://api.anthropic.com/v1/tunnels \
134133 -H 'Content-Type: application/json' \
135134 -H 'anthropic-version: 2023-06-01' \
from line 137
138137 -d '{}'
139138```
140139
141#### Response
140#### Response (200)
142141
143142```json
144143{
from line 152
153152
154153## Get Tunnel
155154
156**get** `/v1/tunnels/{tunnel_id}`
155**GET** `/v1/tunnels/{tunnel_id}`
157156
158157The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
159158
160159Fetches a tunnel by ID.
161160
162### Path Parameters
161### Path parameters
163162
164163- `tunnel_id: string`
165164
166### Header Parameters
165### Headers
167166
168167- `"anthropic-beta": optional array of AnthropicBeta`
169168
from line 242
243242
244243### Returns
245244
246- `BetaTunnel object { id, archived_at, created_at, 3 more }`
245- `BetaTunnel object`
247246
248247 An MCP tunnel.
249248
from line 254
255254
256255 A timestamp in RFC 3339 format
257256
257 format: date-time
258
258259 - `created_at: string`
259260
260261 A timestamp in RFC 3339 format
261262
263 format: date-time
264
262265 - `display_name: string or null`
263266
264267 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 272
269272
270273 - `type: "tunnel"`
271274
272 - `"tunnel"`
273
274275### Example
275276
276```http
277```bash
277278curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID \
278279 -H 'anthropic-version: 2023-06-01' \
279280 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 281
280281 -H "X-Api-Key: $ANTHROPIC_API_KEY"
281282```
282283
283#### Response
284#### Response (200)
284285
285286```json
286287{
from line 296
295296
296297## List Tunnels
297298
298**get** `/v1/tunnels`
299**GET** `/v1/tunnels`
299300
300301The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
301302
302303Lists tunnels. Results are ordered by creation time, newest first; archived tunnels are excluded unless include_archived is set.
303304
304### Query Parameters
305### Query parameters
305306
306307- `include_archived: optional boolean`
307308
from line 312
311312
312313 Maximum number of tunnels to return per page. Defaults to 20, maximum 1000.
313314
315 format: int32
316
314317- `page: optional string`
315318
316319 Opaque pagination cursor from a previous `list_tunnels` response.
317320
318### Header Parameters
321### Headers
319322
320323- `"anthropic-beta": optional array of AnthropicBeta`
321324
from line 410
407410
408411 A timestamp in RFC 3339 format
409412
413 format: date-time
414
410415 - `created_at: string`
411416
412417 A timestamp in RFC 3339 format
413418
419 format: date-time
420
414421 - `display_name: string or null`
415422
416423 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 428
421428
422429 - `type: "tunnel"`
423430
424 - `"tunnel"`
425
426431- `next_page: string or null`
427432
428433 Pagination cursor for the next page, or null if no more results.
from line 434
429434
430435### Example
431436
432```http
437```bash
433438curl https://api.anthropic.com/v1/tunnels \
434439 -H 'anthropic-version: 2023-06-01' \
435440 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 441
436441 -H "X-Api-Key: $ANTHROPIC_API_KEY"
437442```
438443
439#### Response
444#### Response (200)
440445
441446```json
442447{
from line 461
456461
457462## Archive Tunnel
458463
459**post** `/v1/tunnels/{tunnel_id}/archive`
464**POST** `/v1/tunnels/{tunnel_id}/archive`
460465
461466The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
462467
463468Archives 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.
464469
465### Path Parameters
470### Path parameters
466471
467472- `tunnel_id: string`
468473
469### Header Parameters
474### Headers
470475
471476- `"anthropic-beta": optional array of AnthropicBeta`
472477
from line 551
546551
547552### Returns
548553
549- `BetaTunnel object { id, archived_at, created_at, 3 more }`
554- `BetaTunnel object`
550555
551556 An MCP tunnel.
552557
from line 563
558563
559564 A timestamp in RFC 3339 format
560565
566 format: date-time
567
561568 - `created_at: string`
562569
563570 A timestamp in RFC 3339 format
564571
572 format: date-time
573
565574 - `display_name: string or null`
566575
567576 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 581
572581
573582 - `type: "tunnel"`
574583
575 - `"tunnel"`
576
577584### Example
578585
579```http
586```bash
580587curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/archive \
581588 -X POST \
582589 -H 'anthropic-version: 2023-06-01' \
from line 591
584591 -H "X-Api-Key: $ANTHROPIC_API_KEY"
585592```
586593
587#### Response
594#### Response (200)
588595
589596```json
590597{
from line 606
599606
600607## Reveal Tunnel Token
601608
602**post** `/v1/tunnels/{tunnel_id}/reveal_token`
609**POST** `/v1/tunnels/{tunnel_id}/reveal_token`
603610
604611The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
605612
606613Reveals a tunnel's connector 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.
607614
608### Path Parameters
615### Path parameters
609616
610617- `tunnel_id: string`
611618
612### Header Parameters
619### Headers
613620
614621- `"anthropic-beta": optional array of AnthropicBeta`
615622
from line 696
689696
690697### Returns
691698
692- `BetaTunnelToken object { id, tunnel_token, type }`
699- `BetaTunnelToken object`
693700
694701 A tunnel's connector token.
695702
from line 710
703710
704711 - `type: "tunnel_token"`
705712
706 - `"tunnel_token"`
707
708713### Example
709714
710```http
715```bash
711716curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/reveal_token \
712717 -X POST \
713718 -H 'anthropic-version: 2023-06-01' \
from line 720
715720 -H "X-Api-Key: $ANTHROPIC_API_KEY"
716721```
717722
718#### Response
723#### Response (200)
719724
720725```json
721726{
from line 732
727732
728733## Rotate Tunnel Token
729734
730**post** `/v1/tunnels/{tunnel_id}/rotate_token`
735**POST** `/v1/tunnels/{tunnel_id}/rotate_token`
731736
732737The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
733738
734739Rotates a tunnel's connector token. Rotation invalidates the current token for new connections and returns a fresh value; established connections are not severed. A connector restarted after rotation must use the new value.
735740
736### Path Parameters
741### Path parameters
737742
738743- `tunnel_id: string`
739744
740### Header Parameters
745### Headers
741746
742747- `"anthropic-beta": optional array of AnthropicBeta`
743748
from line 820
815820
816821 - `"mid-conversation-tool-changes-2026-07-01"`
817822
818### Body Parameters
823### Body parameters
819824
820825- `reason: optional string or null`
821826
822827 Optional free-text reason for the rotation, recorded for audit.
823828
829 maxLength: 1024
830
824831### Returns
825832
826- `BetaTunnelToken object { id, tunnel_token, type }`
833- `BetaTunnelToken object`
827834
828835 A tunnel's connector token.
829836
from line 844
837844
838845 - `type: "tunnel_token"`
839846
840 - `"tunnel_token"`
841
842847### Example
843848
844```http
849```bash
845850curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/rotate_token \
846851 -H 'Content-Type: application/json' \
847852 -H 'anthropic-version: 2023-06-01' \
from line 855
850855 -d '{}'
851856```
852857
853#### Response
858#### Response (200)
854859
855860```json
856861{
from line 865
860865}
861866```
862867
863## Domain Types
868## Domain types
864869
865870### Beta Tunnel
866871
867- `BetaTunnel object { id, archived_at, created_at, 3 more }`
872- `BetaTunnel object`
868873
869874 An MCP tunnel.
870875
from line 881
876881
877882 A timestamp in RFC 3339 format
878883
884 format: date-time
885
879886 - `created_at: string`
880887
881888 A timestamp in RFC 3339 format
882889
890 format: date-time
891
883892 - `display_name: string or null`
884893
885894 Human-readable name for the tunnel (1-255 characters). Null if unset.
from line 899
890899
891900 - `type: "tunnel"`
892901
893 - `"tunnel"`
894
895902### Beta Tunnel Token
896903
897- `BetaTunnelToken object { id, tunnel_token, type }`
904- `BetaTunnelToken object`
898905
899906 A tunnel's connector token.
900907
from line 915
908915
909916 - `type: "tunnel_token"`
910917
911 - `"tunnel_token"`
918## Tunnels › Certificates
912919
913# Certificates
920### Create Tunnel Certificate
914921
915## Create Tunnel Certificate
922**POST** `/v1/tunnels/{tunnel_id}/certificates`
916923
917**post** `/v1/tunnels/{tunnel_id}/certificates`
918
919924The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
920925
921926Registers a public CA certificate on a tunnel. Anthropic verifies the gateway's server certificate against this CA when it terminates the inner TLS session. A tunnel holds at most two non-archived certificates.
922927
923### Path Parameters
928#### Path parameters
924929
925930- `tunnel_id: string`
926931
927### Header Parameters
932#### Headers
928933
929934- `"anthropic-beta": optional array of AnthropicBeta`
930935
from line 1007
10021007
10031008 - `"mid-conversation-tool-changes-2026-07-01"`
10041009
1005### Body Parameters
1010#### Body parameters
10061011
10071012- `ca_certificate_pem: string`
10081013
10091014 PEM-encoded X.509 CA certificate. Must contain exactly one certificate and no private-key material. Maximum 8KB.
10101015
1011### Returns
1016 maxLength: 8192
10121017
1013- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
1018#### Returns
10141019
1020- `BetaTunnelCertificate object`
1021
10151022 A CA certificate attached to a tunnel.
10161023
10171024 - `id: string`
from line 1029
10221029
10231030 A timestamp in RFC 3339 format
10241031
1032 format: date-time
1033
10251034 - `created_at: string`
10261035
10271036 A timestamp in RFC 3339 format
10281037
1038 format: date-time
1039
10291040 - `expires_at: string or null`
10301041
10311042 A timestamp in RFC 3339 format
10321043
1044 format: date-time
1045
10331046 - `fingerprint: string`
10341047
10351048 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 1053
10401053
10411054 - `type: "tunnel_certificate"`
10421055
1043 - `"tunnel_certificate"`
1056#### Example
10441057
1045### Example
1046
1047```http
1058```bash
10481059curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates \
10491060 -H 'Content-Type: application/json' \
10501061 -H 'anthropic-version: 2023-06-01' \
from line 1066
10551066 }'
10561067```
10571068
1058#### Response
1069##### Response (200)
10591070
10601071```json
10611072{
from line 1080
10691080}
10701081```
10711082
1072## Get Tunnel Certificate
1083### Get Tunnel Certificate
10731084
1074**get** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}`
1085**GET** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}`
10751086
10761087The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
10771088
10781089Fetches a tunnel certificate by ID.
10791090
1080### Path Parameters
1091#### Path parameters
10811092
10821093- `tunnel_id: string`
10831094
10841095- `certificate_id: string`
10851096
1086### Header Parameters
1097#### Headers
10871098
10881099- `"anthropic-beta": optional array of AnthropicBeta`
10891100
from line 1172
11611172
11621173 - `"mid-conversation-tool-changes-2026-07-01"`
11631174
1164### Returns
1175#### Returns
11651176
1166- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
1177- `BetaTunnelCertificate object`
11671178
11681179 A CA certificate attached to a tunnel.
11691180
from line 1186
11751186
11761187 A timestamp in RFC 3339 format
11771188
1189 format: date-time
1190
11781191 - `created_at: string`
11791192
11801193 A timestamp in RFC 3339 format
11811194
1195 format: date-time
1196
11821197 - `expires_at: string or null`
11831198
11841199 A timestamp in RFC 3339 format
11851200
1201 format: date-time
1202
11861203 - `fingerprint: string`
11871204
11881205 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 1210
11931210
11941211 - `type: "tunnel_certificate"`
11951212
1196 - `"tunnel_certificate"`
1213#### Example
11971214
1198### Example
1199
1200```http
1215```bash
12011216curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID \
12021217 -H 'anthropic-version: 2023-06-01' \
12031218 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 1219
12041219 -H "X-Api-Key: $ANTHROPIC_API_KEY"
12051220```
12061221
1207#### Response
1222##### Response (200)
12081223
12091224```json
12101225{
from line 1233
12181233}
12191234```
12201235
1221## List Tunnel Certificates
1236### List Tunnel Certificates
12221237
1223**get** `/v1/tunnels/{tunnel_id}/certificates`
1238**GET** `/v1/tunnels/{tunnel_id}/certificates`
12241239
12251240The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
12261241
12271242Lists the certificates registered on a tunnel. Archived certificates are excluded unless include_archived is set.
12281243
1229### Path Parameters
1244#### Path parameters
12301245
12311246- `tunnel_id: string`
12321247
1233### Query Parameters
1248#### Query parameters
12341249
12351250- `include_archived: optional boolean`
12361251
from line 1255
12401255
12411256 Maximum number of certificates to return per page. Defaults to 20, maximum 1000.
12421257
1258 format: int32
1259
12431260- `page: optional string`
12441261
12451262 Opaque pagination cursor from a previous `list_tunnel_certificates` response.
12461263
1247### Header Parameters
1264#### Headers
12481265
12491266- `"anthropic-beta": optional array of AnthropicBeta`
12501267
from line 1339
13221339
13231340 - `"mid-conversation-tool-changes-2026-07-01"`
13241341
1325### Returns
1342#### Returns
13261343
13271344- `data: array of BetaTunnelCertificate`
13281345
from line 1353
13361353
13371354 A timestamp in RFC 3339 format
13381355
1356 format: date-time
1357
13391358 - `created_at: string`
13401359
13411360 A timestamp in RFC 3339 format
13421361
1362 format: date-time
1363
13431364 - `expires_at: string or null`
13441365
13451366 A timestamp in RFC 3339 format
13461367
1368 format: date-time
1369
13471370 - `fingerprint: string`
13481371
13491372 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 1377
13541377
13551378 - `type: "tunnel_certificate"`
13561379
1357 - `"tunnel_certificate"`
1358
13591380- `next_page: string or null`
13601381
13611382 Pagination cursor for the next page, or null if no more results.
13621383
1363### Example
1384#### Example
13641385
1365```http
1386```bash
13661387curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates \
13671388 -H 'anthropic-version: 2023-06-01' \
13681389 -H 'anthropic-beta: mcp-tunnels-2026-06-22' \
from line 1390
13691390 -H "X-Api-Key: $ANTHROPIC_API_KEY"
13701391```
13711392
1372#### Response
1393##### Response (200)
13731394
13741395```json
13751396{
from line 1409
13881409}
13891410```
13901411
1391## Archive Tunnel Certificate
1412### Archive Tunnel Certificate
13921413
1393**post** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive`
1414**POST** `/v1/tunnels/{tunnel_id}/certificates/{certificate_id}/archive`
13941415
13951416The Tunnels API is in research preview. It requires the `anthropic-beta: mcp-tunnels-2026-06-22` header and may change without a deprecation period. It supersedes the Admin API endpoints at `/v1/organizations/tunnels`, which remain available during a migration window.
13961417
13971418Archives a tunnel certificate, removing it from the set Anthropic trusts for the 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.
13981419
1399### Path Parameters
1420#### Path parameters
14001421
14011422- `tunnel_id: string`
14021423
14031424- `certificate_id: string`
14041425
1405### Header Parameters
1426#### Headers
14061427
14071428- `"anthropic-beta": optional array of AnthropicBeta`
14081429
from line 1501
14801501
14811502 - `"mid-conversation-tool-changes-2026-07-01"`
14821503
1483### Returns
1504#### Returns
14841505
1485- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
1506- `BetaTunnelCertificate object`
14861507
14871508 A CA certificate attached to a tunnel.
14881509
from line 1515
14941515
14951516 A timestamp in RFC 3339 format
14961517
1518 format: date-time
1519
14971520 - `created_at: string`
14981521
14991522 A timestamp in RFC 3339 format
15001523
1524 format: date-time
1525
15011526 - `expires_at: string or null`
15021527
15031528 A timestamp in RFC 3339 format
15041529
1530 format: date-time
1531
15051532 - `fingerprint: string`
15061533
15071534 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
from line 1539
15121539
15131540 - `type: "tunnel_certificate"`
15141541
1515 - `"tunnel_certificate"`
1542#### Example
15161543
1517### Example
1518
1519```http
1544```bash
15201545curl https://api.anthropic.com/v1/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID/archive \
15211546 -X POST \
15221547 -H 'anthropic-version: 2023-06-01' \
from line 1549
15241549 -H "X-Api-Key: $ANTHROPIC_API_KEY"
15251550```
15261551
1527#### Response
1552##### Response (200)
15281553
15291554```json
15301555{
from line 1562
15371562 "type": "tunnel_certificate"
15381563}
15391564```
1540
1541## Domain Types
1542
1543### Beta Tunnel Certificate
1544
1545- `BetaTunnelCertificate object { id, archived_at, created_at, 4 more }`
1546
1547 A CA certificate attached to a tunnel.
1548
1549 - `id: string`
1550
1551 Unique identifier for the certificate, prefixed with `tcrt_`.
1552
1553 - `archived_at: string or null`
1554
1555 A timestamp in RFC 3339 format
1556
1557 - `created_at: string`
1558
1559 A timestamp in RFC 3339 format
1560
1561 - `expires_at: string or null`
1562
1563 A timestamp in RFC 3339 format
1564
1565 - `fingerprint: string`
1566
1567 Lowercase hex SHA-256 fingerprint of the certificate's DER encoding.
1568
1569 - `tunnel_id: string`
1570
1571 ID of the tunnel the certificate is registered against.
1572
1573 - `type: "tunnel_certificate"`
1574
1575 - `"tunnel_certificate"`
15761565
No line in this hunk matches that.