# 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**.

:::tip[Setup with your key filled in]
The in-app [Install page](https://app.tunnelhq.com/api/install) 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](/docs/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.

<Tabs syncKey="mcp-client">
  <TabItem label="Claude Code">
    <Steps>

    1. Add the server:

       ```bash title="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:

       ```bash title="Check that it registered"
       claude mcp list
       ```

    </Steps>
  </TabItem>
  <TabItem label="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:

    ```json title="~/.cursor/mcp.json"
    {
      "mcpServers": {
        "tunnelhq": {
          "command": "npx",
          "args": ["-y", "https://tunnelhq.com/releases/mcp/latest/tunnelhq-mcp.tgz"],
          "env": {
            "TUNNELHQ_API_KEY": "thk_..."
          }
        }
      }
    }
    ```
  </TabItem>
  <TabItem label="Windsurf">
    Add the server to `~/.codeium/windsurf/mcp_config.json`:

    ```json title="~/.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_..."
          }
        }
      }
    }
    ```
  </TabItem>
  <TabItem label="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.

    ```json title="Cline MCP configuration"
    {
      "mcpServers": {
        "tunnelhq": {
          "command": "npx",
          "args": ["-y", "https://tunnelhq.com/releases/mcp/latest/tunnelhq-mcp.tgz"],
          "env": {
            "TUNNELHQ_API_KEY": "thk_..."
          }
        }
      }
    }
    ```
  </TabItem>
</Tabs>

## 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](/docs/uptime/): 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](/docs/cli/), `rm -rf ~/.npm/_npx` does the same, but clears the cache of every npx package.