v20

OpenAPI 3.1.0raw.githubusercontent.com2026-08-035471202.8 KB
Tunnels

Create (or revive) a relay tunnel for a named project server

Registers a server record named name if missing, mints a relay tunnel grant for it, and persists the tunnel bearer URL (including the plaintext ?k= secret) onto the server record's url so evals and chatboxes can target the tunnel like any remote server. The plaintext persistence is a deliberate trade-off of the current tunnel MVP — the backend otherwise stores only a hash of the secret — mitigated by rotation: every call rotates the secret, revokes the previous grant at the edge (disconnecting any live tunnel session for the server), and updates the stored URL, so re-calling this route is also the rotation/recovery path.

The caller hosts the tunnel itself: connect a WebSocket to relayWsUrl (subprotocol mcpjam-tunnel.v1, Authorization: Bearer <connectToken>) and serve the relayed requests — this is what mcpjam tunnel does. When the host disconnects, the server record stays and calls to the public URL fail fast at the edge.

post/projects/{projectId}/tunnels

Path parameters

projectIdstring required

ID of the hosted project that contains the server.

Request body

namestring required

Server name to register the tunnel under. Reusing an existing server's name points that record at the tunnel: its url is overwritten and stdio records are converted to transportType: "http".

Response

Tunnel grant minted and the server record updated.

serverIdstring required

The registered project server's ID.

namestring required
existedboolean required

True when a server record with this name already existed (its config now points at the tunnel).

previousUrlstring

The record's previous URL, present when it existed with a different one (it has been overwritten).

previousTransportTypestring

The record's previous transport, present when it existed (a stdio record has been converted to http).

slugstring required

Stable public subdomain slug; survives re-creates for the same server.

urlstring required

Public tunnel URL including the ?k= bearer secret. Also persisted on the server record's url.

connectTokenstring required

Bearer for the relay edge WebSocket handshake.

connectTokenExpiresAtnumber

Epoch-ms expiry of connectToken.

relayWsUrlstring required

Relay edge WebSocket endpoint to connect to.

secretVersionnumber

Monotonic secret version; each create bumps it.