MCP Tunnels

MCP tunnels connect Allternit to externally hosted MCP servers over HTTPS. Each tunnel has a unique token that the MCP server uses to authenticate inbound connections, plus optional mTLS client certificates and OAuth issuer/audience validation enforced by mcp_tunnel_auth.

Base URL

/api/v1/admin/mcp-tunnels

Endpoints

Method	Path	Description
`POST`	`/api/v1/admin/mcp-tunnels`	Create a tunnel
`GET`	`/api/v1/admin/mcp-tunnels`	List tunnels
`GET`	`/api/v1/admin/mcp-tunnels/:id`	Get a tunnel
`PUT`	`/api/v1/admin/mcp-tunnels/:id`	Update a tunnel
`DELETE`	`/api/v1/admin/mcp-tunnels/:id`	Delete a tunnel
`POST`	`/api/v1/admin/mcp-tunnels/:id/rotate`	Rotate the tunnel token
`POST`	`/api/v1/admin/mcp-tunnels/:id/reveal`	Reveal the tunnel token

Create a tunnel

curl -X POST https://api.allternit.com/api/v1/admin/mcp-tunnels \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "internal-search",
    "description": "Internal search MCP server",
    "endpoint_url": "https://mcp.example.com/sse",
    "oauth_issuer": "https://auth.example.com",
    "audience": "mcp-audience"
  }'

Request body

{
  "name": "internal-search",
  "description": "Internal search MCP server",
  "endpoint_url": "https://mcp.example.com/sse",
  "oauth_issuer": "https://auth.example.com",
  "audience": "mcp-audience"
}

Response

{
  "id": "amt_01hqx8x7x7x7x7x7x7x7x7x",
  "organization_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
  "name": "internal-search",
  "description": "Internal search MCP server",
  "endpoint_url": "https://mcp.example.com/sse",
  "client_cert_pem": null,
  "oauth_issuer": "https://auth.example.com",
  "audience": "mcp-audience",
  "created_by": "usr_01hqx8x7x7x7x7x7x7x7x7x",
  "created_at": "2026-08-13T18:00:00Z",
  "updated_at": "2026-08-13T18:00:00Z",
  "tunnel_token": "amt_550e8400e29b41d4a716446655440000"
}

Save the tunnel_token immediately. It can be revealed later, but treat it as a secret.

List tunnels

curl -X GET https://api.allternit.com/api/v1/admin/mcp-tunnels \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "items": [
    {
      "id": "amt_01hqx8x7x7x7x7x7x7x7x7x",
      "organization_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
      "name": "internal-search",
      "description": "Internal search MCP server",
      "endpoint_url": "https://mcp.example.com/sse",
      "client_cert_pem": null,
      "oauth_issuer": "https://auth.example.com",
      "audience": "mcp-audience",
      "created_by": "usr_01hqx8x7x7x7x7x7x7x7x7x",
      "created_at": "2026-08-13T18:00:00Z",
      "updated_at": "2026-08-13T18:00:00Z"
    }
  ]
}

Update a tunnel

curl -X PUT https://api.allternit.com/api/v1/admin/mcp-tunnels/amt_01hqx8x7x7x7x7x7x7x7x7x \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "internal-search-v2",
    "endpoint_url": "https://mcp.example.com/v2/sse"
  }'

Response

{
  "id": "amt_01hqx8x7x7x7x7x7x7x7x7x",
  "organization_id": "org_01hqx8x7x7x7x7x7x7x7x7x",
  "name": "internal-search-v2",
  "description": "Internal search MCP server",
  "endpoint_url": "https://mcp.example.com/v2/sse",
  "client_cert_pem": null,
  "oauth_issuer": "https://auth.example.com",
  "audience": "mcp-audience",
  "created_by": "usr_01hqx8x7x7x7x7x7x7x7x7x",
  "created_at": "2026-08-13T18:00:00Z",
  "updated_at": "2026-08-13T18:05:00Z"
}

Rotate the tunnel token

curl -X POST https://api.allternit.com/api/v1/admin/mcp-tunnels/amt_01hqx8x7x7x7x7x7x7x7x7x/rotate \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "id": "amt_01hqx8x7x7x7x7x7x7x7x7x",
  "tunnel_token": "amt_7c9e6f5d4c3b2a1908e7f6d5c4b3a291",
  "updated_at": "2026-08-13T18:10:00Z"
}

Reveal the tunnel token

curl -X POST https://api.allternit.com/api/v1/admin/mcp-tunnels/amt_01hqx8x7x7x7x7x7x7x7x7x/reveal \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "id": "amt_01hqx8x7x7x7x7x7x7x7x7x",
  "tunnel_token": "amt_7c9e6f5d4c3b2a1908e7f6d5c4b3a291"
}

Delete a tunnel

curl -X DELETE https://api.allternit.com/api/v1/admin/mcp-tunnels/amt_01hqx8x7x7x7x7x7x7x7x7x \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response

{
  "deleted": true
}

Authentication policy

Tunnels support three layers of security:

Tunnel token — a shared secret presented by the MCP server.
mTLS client certificate — client_cert_pem can be provided for mutual TLS.
OAuth issuer and audience — JWT bearer tokens from the configured issuer are validated for the given audience.

Error codes

Status	Code	Description
`400`	`invalid_name`	Name must be 1–128 characters.
`400`	`invalid_endpoint_url`	URL must start with `http://` or `https://` and be ≤ 2048 characters.
`403`	`organization_required`	Caller is not associated with an organization.
`403`	`insufficient_role`	Caller is not an organization owner or admin.
`404`	`tunnel_not_found`	Tunnel does not exist or belongs to another organization.

Tools / MCP — attaching MCP servers and server-side execution
Workspaces — scope tunnels to workspaces

Get Started

Core Concepts

Gizzi Code CLI

Tools & ACI

Security & Enterprise

Admin API

BYOC Runtime

Surfaces

CI CD

Guides

Cookbooks

Release Notes

MCP Tunnels

MCP Tunnels

Base URL

Endpoints

Create a tunnel

Request body

Response

List tunnels

Response

Update a tunnel

Response

Rotate the tunnel token

Response

Reveal the tunnel token

Response

Delete a tunnel

Response

Authentication policy

Error codes

​MCP Tunnels

​Base URL

​Endpoints

​Create a tunnel

​Request body

​Response

​List tunnels

​Response

​Update a tunnel

​Response

​Rotate the tunnel token

​Response

​Reveal the tunnel token

​Response

​Delete a tunnel

​Response

​Authentication policy

​Error codes

​Related pages

MCP Tunnels

Base URL

Endpoints

Create a tunnel

Request body

Response

List tunnels

Response

Update a tunnel

Response

Rotate the tunnel token

Response

Reveal the tunnel token

Response

Delete a tunnel

Response

Authentication policy

Error codes

Related pages