Update a tunnel

⚠️
Preview — this feature is being built; the design below is the spec.
PATCH https://app.syntic.ai/v1/tunnels/{tunnel_id}

Change a tunnel’s targets, description or state. New allowed_targets are pushed to connected connectors within 30 seconds. Setting status: disabled closes every connection; requests that use the tunnel then fail with 502 tunnel_unavailable until it is enabled again.

For how this fits into a full workflow, see MCP tunnels.

Headers

HeaderRequiredValue
AuthorizationYesBearer <key>: a private inference key (sk_live_...). See Authentication.
syntic-betaYes, while in previewmcp-tunnels-2026-12-01. Without it the call fails with 400 beta_required. See Versioning.
Content-TypeYesapplication/json

Path parameters

ParameterTypeDescription
tunnel_idstringThe tunnel id, starting with tnl_.

Body parameters

ParameterTypeRequiredNotes
allowed_targetsarray of stringsNoReplaces the list.
descriptionstringNo
statusstringNoenabled or disabled.

Response

200 OK, Content-Type: application/json

{
  "id": "tnl_01JCE4G6J8L0N2Q4S6U8",
  "type": "tunnel",
  "name": "erp-onprem",
  "description": "On-prem ERP MCP server",
  "workspace_id": "wrkspc_01JC0A2C4E6G8J0L2N4Q",
  "allowed_targets": [
    "http://erp-mcp.internal:8080/mcp",
    "http://hr-mcp.internal:8081/mcp"
  ],
  "auth_mode": "token",
  "status": "connected",
  "connections": {
    "active": 2,
    "last_seen_at": "2026-11-05T10:00:31Z"
  },
  "region": "eu",
  "created_at": "2026-10-28T09:00:00Z",
  "updated_at": "2026-10-28T09:00:00Z"
}
FieldTypeDescription
idstringStarts with tnl_. Use it as tunnel_id on an MCP server entry.
allowed_targetsarrayThe only URLs inside your network the connector will forward to. Anything else is refused by the connector itself.
auth_modestringHow connectors prove who they are: token (connector token) or mtls (client certificate from this tunnel’s certificates).
statusstringconnected when at least one connector is online, disconnected otherwise, disabled when turned off.
connectionsobjectHow many connector instances are online and when one last checked in.

Examples

curl -sS -X PATCH "https://app.syntic.ai/v1/tunnels/tnl_01JCE4G6J8L0N2Q4S6U8" \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "syntic-beta: mcp-tunnels-2026-12-01" \
  -H "Content-Type: application/json" \
  -d '{
      "allowed_targets": [
        "http://erp-mcp.internal:8080/mcp",
        "http://hr-mcp.internal:8081/mcp"
      ]
    }'

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

StatustypecodeWhen
400invalid_request_errorbeta_requiredThe syntic-beta header is missing.
404not_found_errortunnel_not_foundNo tunnel with this id in the key’s workspace.
401authentication_errorinvalid_api_keyThe key is missing, unknown, revoked or expired.
429rate_limit_errorrate_limitedToo many requests; wait for Retry-After. See Rate-limit headers.
Was this page helpful?