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

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

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "everything"
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels"

payload = { "name": "everything" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'everything'})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'everything'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels"

	payload := strings.NewReader("{\n  \"name\": \"everything\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"everything\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"everything\"\n}"

response = http.request(request)
puts response.read_body

{
  "serverId": "srv_abc123",
  "name": "everything",
  "existed": false,
  "slug": "calm-otter",
  "url": "https://calm-otter.tunnels.mcpjam.com/api/mcp/adapter-http/srv_abc123?k=…",
  "connectToken": "ct_…",
  "connectTokenExpiresAt": 1767225600000,
  "relayWsUrl": "wss://tunnels.mcpjam.com/agent",
  "secretVersion": 3
}

Authorizations

Authorization

string

header

required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Path Parameters

projectId

string

required

ID of the hosted project that contains the server.

Body

application/json

name

string

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".

Required string length: 1 - 128

Response

Tunnel grant minted and the server record updated.

Everything the caller needs to host the tunnel connection. Treat the whole object as a credential: url embeds the plaintext ?k= bearer secret and connectToken authenticates the relay WebSocket.

serverId

string

required

The registered project server's ID.

name

string

required

existed

boolean

required

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

slug

string

required

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

url

string

required

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

connectToken

string

required

Bearer for the relay edge WebSocket handshake.

relayWsUrl

string

required

Relay edge WebSocket endpoint to connect to.

previousUrl

string

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

previousTransportType

string

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

connectTokenExpiresAt

number

Epoch-ms expiry of connectToken.

secretVersion

number

Monotonic secret version; each create bumps it.

Revoke a tunnel's live grantRevokes the grant at the control plane and edge: the public URL stops working immediately and any live tunnel session is disconnected. The server record — including its now-dead `url` — is intentionally left untouched, so the next create revives the tunnel with the same slug.

⌘I

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

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "everything"
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels"

payload = { "name": "everything" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'everything'})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'everything'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels"

	payload := strings.NewReader("{\n  \"name\": \"everything\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"everything\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/tunnels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"everything\"\n}"

response = http.request(request)
puts response.read_body

{
  "serverId": "srv_abc123",
  "name": "everything",
  "existed": false,
  "slug": "calm-otter",
  "url": "https://calm-otter.tunnels.mcpjam.com/api/mcp/adapter-http/srv_abc123?k=…",
  "connectToken": "ct_…",
  "connectTokenExpiresAt": 1767225600000,
  "relayWsUrl": "wss://tunnels.mcpjam.com/agent",
  "secretVersion": 3
}

API Guides

Endpoints

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

Authorizations

Path Parameters

Body

Response