MCP server

The TunnelHQ MCP server lets an AI assistant such as Claude, ChatGPT, Cursor, or VS Code work with TunnelHQ directly. Ask it to test a config, add a monitor, or check on an incident, and it does the work through the same API you would use.

There are two ways to connect:

	Sign in	API key
Where it runs	Hosted by TunnelHQ at https://mcp.tunnelhq.com/mcp	On your machine, started by npx
How it signs in	You sign in to TunnelHQ and approve the connection. No key is copied.	A TUNNELHQ_API_KEY in your client’s config
Clients	Claude, Claude Code, ChatGPT, Cursor, VS Code, Windsurf, and any client with Streamable HTTP and OAuth	Any client that starts a local MCP server, such as Cline
What it can do	Read, or read and write. It never deletes.	Every tool, narrowed by the environment variables

Both need a workspace on a plan with API access, which is Starter and above.

Connect by signing in

Developers → AI assistants in the dashboard shows the server address, these steps, a few prompts to try, and the assistants connected to the workspace.

Claude

1. In Claude, open Customize, then Connectors.
2. Choose Add, then Add custom connector.
3. Name it TunnelHQ and paste https://mcp.tunnelhq.com/mcp. Choose Continue, then Add.
4. Choose Connect and sign in to TunnelHQ in the tab that opens.

On a Claude Team plan, only an Owner can add a connector. Members then choose Connect.

Claude Code

1. Add the server:

   Add TunnelHQ to Claude Code

   claude mcp add --transport http tunnelhq https://mcp.tunnelhq.com/mcp

2. In Claude Code, type /mcp, choose tunnelhq, and choose Authenticate. A browser tab opens for the sign-in.

Cursor

Add to Cursor on the AI assistants page adds the server. Cursor then shows Needs login next to TunnelHQ: choose it and sign in.

Without the button, add this to ~/.cursor/mcp.json:

~/.cursor/mcp.json

{
  "mcpServers": {
    "tunnelhq": {
      "url": "https://mcp.tunnelhq.com/mcp"
    }
  }
}

VS Code

Add to VS Code on the AI assistants page adds the server. VS Code asks whether you trust it: choose Trust, then sign in.

Without the button, run MCP: Add Server, choose HTTP, and paste https://mcp.tunnelhq.com/mcp.

ChatGPT

1. Open Settings, Connectors, Advanced, and turn on Developer mode.
2. Choose Create. Name it TunnelHQ, paste https://mcp.tunnelhq.com/mcp, and set Authentication to OAuth.
3. Choose Create and sign in.

Developer mode needs a ChatGPT plan that includes it. Check ChatGPT’s current requirements.

Windsurf

1. Open the MCP config file from the Cascade panel.

2. Add this and save:

   Windsurf MCP config

   {
     "mcpServers": {
       "tunnelhq": {
         "serverUrl": "https://mcp.tunnelhq.com/mcp"
       }
     }
   }

3. Sign in when Windsurf asks.

Other

Use https://mcp.tunnelhq.com/mcp with Streamable HTTP and OAuth. If your client only takes a key, run the server with an API key instead.

Approving the connection

The sign-in opens a TunnelHQ page, Connect app to TunnelHQ, that names the app and asks three things:

• Workspace: starts on the one you were last in. A workspace on a plan without API access is marked (no API access), and no assistant can connect to it.
• Project: All projects, or one project.
• Access: Read and write, or Read only. If your role in the workspace is Viewer, the connection can only read.

Choose Allow to connect, or Cancel.

If TunnelHQ doesn’t recognise the app, the page shows it by its web address with a warning, and Allow stays off until you tick I started this and I trust address. Only tick it if you started the connection yourself.

What a connected assistant can do

• Read only sees monitors, Uptime checks and heartbeats, results, incidents, subscriptions, usage, and the workspace’s projects.
• Read and write can also test a config or link, create and edit monitors, Uptime checks, heartbeats and subscriptions, run a check now, retest an incident’s monitor, acknowledge an incident, and sync a subscription.
• Neither can delete anything, or touch API keys, billing, or team members. Do those in the dashboard.

Testing counts as a change, because each test uses the workspace’s on-demand test allowance. Your role in the workspace still applies on top, as it does for an API key. On a read-only connection, a tool that changes something answers “This connection is read only. Reconnect with “Read and write” to change anything.”

A signed-in assistant sees 29 of the server’s tools. The five it doesn’t see are delete_monitor, bulk_delete_monitors, delete_subscription, list_api_keys, and revoke_api_key.

When the connection reaches only one project, tools use it without being told, and searching across the workspace’s other projects is refused. Otherwise the assistant names a project in its calls, and list_projects shows the choices.

Managing connections

The Connected list on Developers → AI assistants shows each connection with:

• the app;
• its access;
• its project, or All projects;
• who connected it (Owners and Admins see everyone’s connections, others see their own);
• when it was last used.

Revoke asks first, then ends that app’s access to the workspace at once. Anything it already created stays, and you can connect it again later. A connection that goes unused for 90 days ends by itself.

Prompts in the dashboard

On every plan except Free, the empty Tunnels and Uptime pages show a Set it up with an AI assistant card. Step 1 connects an assistant, and step 2 copies a prompt written for that page. The Tunnels prompt has the assistant read your VPN files, private keys included, to add them, so use it with an assistant you trust with those files. During onboarding, the “How would you like to add it?” step offers the same prompt under Have the configs in a project? Show the prompt.

Run the server with an API key

This section describes MCP server 0.4.0, the current release. It runs on your machine and has every tool, including the ones that delete.

Before you start

The MCP server authenticates with a TunnelHQ API key, available on Starter and above. Create one under Developers → API Keys.

Setup with your key filled in

The in-app Install page shows these steps with your API key already filled in, with a tab for each client. It’s the fastest way to connect.

Set up your client

If you use the CLI, thq mcp --client <claude|cursor|windsurf|cline> --apply does this for you: it runs claude mcp add for Claude Code, or writes the JSON config for the other clients.

Claude Code

1. Add the server:

   Add the MCP server to Claude Code

   claude mcp add tunnelhq --scope user \
     --env TUNNELHQ_API_KEY="thk_..." \
     -- npx -y https://tunnelhq.com/releases/mcp/latest/tunnelhq-mcp.tgz

2. Check that it registered:

   Check that it registered

   claude mcp list

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json at the root of a repository to use it in that project only:

~/.cursor/mcp.json

{
  "mcpServers": {
    "tunnelhq": {
      "command": "npx",
      "args": ["-y", "https://tunnelhq.com/releases/mcp/latest/tunnelhq-mcp.tgz"],
      "env": {
        "TUNNELHQ_API_KEY": "thk_..."
      }
    }
  }
}

Windsurf

Add the server to ~/.codeium/windsurf/mcp_config.json:

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "tunnelhq": {
      "command": "npx",
      "args": ["-y", "https://tunnelhq.com/releases/mcp/latest/tunnelhq-mcp.tgz"],
      "env": {
        "TUNNELHQ_API_KEY": "thk_..."
      }
    }
  }
}

Cline

In VS Code, click the Cline icon, then the gear icon, then MCP Servers, and paste this configuration. Cline saves it to your profile, and you don’t need to restart.

Cline MCP configuration

{
  "mcpServers": {
    "tunnelhq": {
      "command": "npx",
      "args": ["-y", "https://tunnelhq.com/releases/mcp/latest/tunnelhq-mcp.tgz"],
      "env": {
        "TUNNELHQ_API_KEY": "thk_..."
      }
    }
  }
}

Environment variables

Variable	Description
TUNNELHQ_API_KEY	Required. Your API key.
TUNNELHQ_HOST	API host. Defaults to https://beta.tunnelhq.com.
TUNNELHQ_PROJECT_ID	The project tools use when a call doesn’t name one.
TUNNELHQ_PROJECT_LOCK	1 to refuse every project except TUNNELHQ_PROJECT_ID. Requires TUNNELHQ_PROJECT_ID.
TUNNELHQ_READ_ONLY	1 to hide every tool that makes changes, leaving the 18 read-only tools.
TUNNELHQ_ENABLE_ADMIN	1 to add revoke_api_key.
TUNNELHQ_NO_CERT_RESOLVE	1 to skip certificate lookups. For OpenConnect and IKEv2 configs given as an IP address, the server normally connects to that address from your machine to read the hostname from its TLS certificate.

Safer setups

• To let an assistant look but not touch, set TUNNELHQ_READ_ONLY=1.
• To keep an assistant inside one project, set TUNNELHQ_PROJECT_ID and TUNNELHQ_PROJECT_LOCK=1.
• Leave TUNNELHQ_ENABLE_ADMIN unset unless the assistant needs to revoke keys.

Updates

npx keeps the copy it first downloaded and doesn’t check the release URL again, so an installed MCP server doesn’t update itself. To get a newer version, run thq mcp --client claude --update (or cursor, windsurf, or cline) and restart your editor. It clears only TunnelHQ’s cached copy. Without the CLI, rm -rf ~/.npm/_npx does the same, but clears the cache of every npx package.

Tools

The server has 33 tools, or 34 with admin tools enabled: 18 that only read, 15 that make changes, and 1 admin tool.

Group	Tools
Testing	test_vpn, test_batch
Monitors	list_monitors, get_monitor, create_monitor, update_monitor, delete_monitor, check_monitor, batch_check_monitors, bulk_update_monitors, bulk_delete_monitors, search_monitors
Uptime checks	list_checks, create_check, update_check
Results	get_monitor_history, list_recent_results, list_recent_failures
Incidents	list_incidents, get_incident, acknowledge_incident, retest_incident
Subscriptions	list_subscriptions, get_subscription, create_subscription, update_subscription, sync_subscription, delete_subscription
Account	whoami, list_organizations, list_projects, get_usage, list_api_keys, revoke_api_key (admin only)

With these, your assistant can:

• Test any VPN config, share link, or subscription URL and report whether it connects, including batches of tests run in parallel.
• Create, update, delete, and list monitors, and search monitors across every project the key can reach.
• Update or delete many monitors at once. bulk_update_monitors and bulk_delete_monitors default to a dry run, so the first call only previews what would change.
• List, create, and change Uptime checks: websites, keywords, ping, TCP ports, DNS servers, and heartbeats. Creating a heartbeat returns the address your job calls.
• Run on-demand checks and read results and history.
• List incidents, read one with its timeline, acknowledge it, and retest its monitor.
• Manage subscription URLs and trigger syncs.
• Check plan usage and quotas before running rate-limited operations.

Tools that take a project accept its name (case-insensitive; an unambiguous partial match works), its prj_ slug, or its number.