MCP Server Guide

What the MCP Server Does

The tunnl mcp command starts a Model Context Protocol server over stdio. MCP is a standard that lets AI coding agents (Claude Desktop, Cursor, Copilot Agent Mode) call external tools in a structured way.

When you add tunnl as an MCP server, your AI agent can:

• List your active tunnel connections
• Query request history with filters (method, path, status code, time range)
• Read the full headers and body of any captured request
• Replay a request against your running handler
• Compare the original response against a replayed response
• Export any request as a curl command

The agent can see what your webhook handler is actually receiving and what it is returning, without you switching between windows.

Setup: Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the tunnl MCP server:

{
  "mcpServers": {
    "tunnl": {
      "command": "tunnl",
      "args": ["mcp"],
      "env": {
        "TUNNL_SERVER": "https://webhooks.example.com",
        "TUNNL_TOKEN": "tk_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. You will see the tunnl tools available in the tool list.

Setup: Cursor

Create or edit .cursor/mcp.json in your project root, or add to the global Cursor MCP config:

{
  "mcpServers": {
    "tunnl": {
      "command": "tunnl",
      "args": ["mcp"],
      "env": {
        "TUNNL_SERVER": "https://webhooks.example.com",
        "TUNNL_TOKEN": "tk_your_api_key_here"
      }
    }
  }
}

If you have already logged in with tunnl login, you can omit the env block — the MCP server will read credentials from ~/.tunnl/config.json.

Tool Reference

All 8 tools exposed by tunnl mcp:

list_tunnels

List all active tunnel connections on the server.

Returns an array of tunnels with subdomain, local port, connected-at timestamp, and request count.

get_tunnel

Get details for a specific tunnel by subdomain or ID.

list_requests

Query request history with optional filters. Returns paginated results newest-first.

get_request_detail

Get the full headers and body for a specific request.

Returns the full request (method, path, headers, body) and response (status, headers, body, timing).

replay_request

Re-send a captured request to the connected CLI. The CLI forwards it to your local handler.

The request is replayed with its original headers, including signature headers (Stripe, GitHub, Slack). The replayed response is stored and can be retrieved with get_replay_diff.

get_replay_diff

Compare the original response against a replayed response.

export_curl

Export a captured request as a ready-to-run curl command.

Returns a shell-escaped curl command with all original headers and body. Useful for manual debugging and sharing.

get_tunnel_stats

Get aggregate statistics for a tunnel session.

Returns request count, error rate, average response time, and a breakdown by HTTP method and status code.

Example Workflow

Once tunnl is configured as an MCP server, you can ask your agent:

# See what your webhook handler is receiving
"Show me the last 5 requests to my abc123 tunnel"

# Debug a failing handler
"Replay the last POST to /webhook and show me what changed in the response"

# Export for manual testing
"Give me a curl command for the Stripe checkout.session.completed event
 that came in at 14:32"

# Understand a provider's payload shape
"What headers does GitHub send with push events? Look at the last 10 requests."