Create a tunnel

⚠️

Preview — this feature is being built; the design below is the spec.

POST https://app.syntic.ai/v1/tunnels

Create a tunnel so the MCP connector and agents can reach an MCP server inside your private network. You run the small syntic-tunnel connector next to the server; it dials out to Syntic over TLS on port 443, so no inbound firewall rule or public address is needed. The response holds the connector token, shown only once.

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

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <key>`: a private inference key (`sk_live_...`). See Authentication.
`syntic-beta`	Yes, while in preview	`mcp-tunnels-2026-12-01`. Without it the call fails with `400 beta_required`. See Versioning.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Up to 255 characters. Retrying with the same key within 24 hours returns the first result instead of acting twice. See Idempotency.

Body parameters

Parameter	Type	Required	Notes
`name`	string	Yes	1 to 64 characters, unique in the workspace.
`allowed_targets`	array of strings	Yes	1 to 20 URLs (http or https) the connector may forward to.
`auth_mode`	string	No	`token` (default) or `mtls`.
`description`	string	No	Up to 200 characters.

Response

201 Created, 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"
  ],
  "auth_mode": "token",
  "status": "disconnected",
  "connections": {
    "active": 0,
    "last_seen_at": null
  },
  "region": "eu",
  "created_at": "2026-10-28T09:00:00Z",
  "updated_at": "2026-10-28T09:00:00Z",
  "connector_token": "stn_live_9QxF…redacted"
}

Field	Type	Description
`id`	string	Starts with `tnl_`. Use it as `tunnel_id` on an MCP server entry.
`allowed_targets`	array	The only URLs inside your network the connector will forward to. Anything else is refused by the connector itself.
`auth_mode`	string	How connectors prove who they are: `token` (connector token) or `mtls` (client certificate from this tunnel’s certificates).
`status`	string	`connected` when at least one connector is online, `disconnected` otherwise, `disabled` when turned off.
`connections`	object	How many connector instances are online and when one last checked in.
`connector_token`	string	Starts with `stn_`. Pass it to the connector as `SYNTIC_TUNNEL_TOKEN`. Returned only here and by rotate.

Examples

curl -sS "https://app.syntic.ai/v1/tunnels" \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "syntic-beta: mcp-tunnels-2026-12-01" \
  -H "Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "erp-onprem",
      "description": "On-prem ERP MCP server",
      "allowed_targets": [
        "http://erp-mcp.internal:8080/mcp"
      ]
    }'

import os
 
import requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/tunnels",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}",
        "syntic-beta": "mcp-tunnels-2026-12-01",
        "Idempotency-Key": "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69",
    },
    json={
        "name": "erp-onprem",
        "description": "On-prem ERP MCP server",
        "allowed_targets": [
            "http://erp-mcp.internal:8080/mcp"
        ]
    },
    timeout=60,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{resp.status_code} {data['error']['code']}: {data['error']['message']}")
print(data)

const res = await fetch('https://app.syntic.ai/v1/tunnels', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'syntic-beta': 'mcp-tunnels-2026-12-01',
    'Idempotency-Key': '8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "erp-onprem",
    "description": "On-prem ERP MCP server",
    "allowed_targets": [
      "http://erp-mcp.internal:8080/mcp"
    ]
  }),
})
const text = await res.text()
const data = text ? JSON.parse(text) : null
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`)
console.log(data ?? res.status)

package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
 
func main() {
	body := strings.NewReader(`{
  "name": "erp-onprem",
  "description": "On-prem ERP MCP server",
  "allowed_targets": [
    "http://erp-mcp.internal:8080/mcp"
  ]
}`)
	req, err := http.NewRequest("POST", "https://app.syntic.ai/v1/tunnels", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SYNTIC_API_KEY"))
	req.Header.Set("syntic-beta", "mcp-tunnels-2026-12-01")
	req.Header.Set("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode >= 300 {
		panic(fmt.Sprintf("%d: %s", resp.StatusCode, out))
	}
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "name": "erp-onprem",
              "description": "On-prem ERP MCP server",
              "allowed_targets": [
                "http://erp-mcp.internal:8080/mcp"
              ]
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://app.syntic.ai/v1/tunnels"))
            .header("Authorization", "Bearer " + System.getenv("SYNTIC_API_KEY"))
            .header("syntic-beta", "mcp-tunnels-2026-12-01")
            .header("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300) {
            throw new RuntimeException(response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;
 
using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://app.syntic.ai/v1/tunnels");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SYNTIC_API_KEY"));
request.Headers.Add("syntic-beta", "mcp-tunnels-2026-12-01");
request.Headers.Add("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69");
request.Content = new StringContent("""
    {
      "name": "erp-onprem",
      "description": "On-prem ERP MCP server",
      "allowed_targets": [
        "http://erp-mcp.internal:8080/mcp"
      ]
    }
    """, Encoding.UTF8, "application/json");
 
using var response = await http.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode) throw new Exception($"{(int)response.StatusCode}: {text}");
Console.WriteLine(text);

<?php
$body = <<<'JSON'
{
  "name": "erp-onprem",
  "description": "On-prem ERP MCP server",
  "allowed_targets": [
    "http://erp-mcp.internal:8080/mcp"
  ]
}
JSON;
 
$ch = curl_init('https://app.syntic.ai/v1/tunnels');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SYNTIC_API_KEY'),
        'syntic-beta: mcp-tunnels-2026-12-01',
        'Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
 
if ($status >= 300) {
    throw new RuntimeException("$status: $response");
}
print_r(json_decode($response, true) ?? $status);

require "json"
require "net/http"
require "uri"
 
uri = URI("https://app.syntic.ai/v1/tunnels")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('SYNTIC_API_KEY')}"
req["syntic-beta"] = "mcp-tunnels-2026-12-01"
req["Idempotency-Key"] = "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69"
req["Content-Type"] = "application/json"
req.body = <<~'JSON'
  {
    "name": "erp-onprem",
    "description": "On-prem ERP MCP server",
    "allowed_targets": [
      "http://erp-mcp.internal:8080/mcp"
    ]
  }
JSON
 
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "#{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
puts res.body.empty? ? res.code : JSON.pretty_generate(JSON.parse(res.body))

Errors

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

Status	`type`	`code`	When
400	`invalid_request_error`	`beta_required`	The `syntic-beta` header is missing.
409	`conflict_error`	`name_taken`	Another tunnel in the workspace has this name.
409	`conflict_error`	`tunnel_limit_reached`	The workspace already has 25 tunnels.
401	`authentication_error`	`invalid_api_key`	The key is missing, unknown, revoked or expired.
429	`rate_limit_error`	`rate_limited`	Too many requests; wait for `Retry-After`. See Rate-limit headers.

MCP tunnels List tunnels

Was this page helpful?