MCP server

The TunnelHQ MCP server lets an AI assistant such as Claude, Cursor, Windsurf, or Cline 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.

This page describes MCP server 0.4.0, the current release.

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

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.

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.