MCP Server

Connect CatchHook to your AI coding assistant. Debug webhooks, inspect requests, and manage endpoints from Claude Code, Cursor, Windsurf, Codex CLI, or any MCP-compatible editor.

The MCP server exposes 20 tools that wrap CatchHook's full API. Your AI assistant can list endpoints, search requests by provider and event type, wait for new webhooks to arrive, replay events, diagnose signature failures, and more -- all without leaving your editor.

Quick Start

1. Create an API Token

Go to Account Settings → API Tokens and create a token with read and write scopes.

2. Add to Your Editor

Claude Code:

claude mcp add catchhook --transport http --url https://catchhook.app/mcp --header "Authorization: Bearer YOUR_TOKEN"

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "catchhook": {
      "url": "https://catchhook.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Windsurf — add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "catchhook": {
      "serverUrl": "https://catchhook.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Codex CLI:

export CATCHHOOK_TOKEN="YOUR_TOKEN"
codex mcp add catchhook --url https://catchhook.app/mcp --bearer-token-env-var CATCHHOOK_TOKEN

3. Start Using It

Ask your AI assistant things like:

"List my CatchHook endpoints"
"Show me the latest Stripe webhook on endpoint ep_abc123"
"Wait for the next GitHub push event"
"Diagnose request req_xyz789"

Available Tools

Endpoint Management

Tool	Description	Scope
`list_endpoints`	List all webhook endpoints with URLs, tunnel status, and provider info	read
`get_endpoint`	Get endpoint details including provider setup checks	read
`create_endpoint`	Create a new webhook or email endpoint	write
`delete_endpoint`	Delete an endpoint and all its captured requests	write

Request Inspection

Tool	Description	Scope
`list_requests`	List captured requests with filtering by provider, event type, signature status	read
`get_request`	Full request details: headers, body, query params, and provider-enriched data	read
`delete_request`	Delete a single captured request	write
`delete_all_requests`	Bulk delete all requests on an endpoint	write

Agentic Workflow

Tool	Description	Scope
`wait_for_request`	Poll until a new webhook arrives (15s default, 30s max). Supports optional provider and event type filters.	read
`send_test_request`	Send a test webhook to verify an endpoint is receiving traffic	write

Replay & Forwarding

Tool	Description	Scope
`replay_request`	Replay a captured request to a target URL. Includes provider-aware safety warnings for idempotency, signatures, and replay risk.	write
`list_actions`	List actions configured on an endpoint	read
`create_action`	Create a new endpoint action with steps	write
`delete_action`	Remove an endpoint action	write
`get_action_runs`	View execution traces for an action	read

Analysis & Diagnostics

Tool	Description	Scope
`diagnose_request`	Comprehensive debugging: provider detection, signature verification, setup checks, replay risk, and recommended next actions	read
`compare_requests`	Provider-aware diff between two requests highlighting high-signal changes (e.g., "Stripe livemode changed", "GitHub sender changed")	read
`get_endpoint_metrics`	Endpoint statistics: request counts, error rates, status breakdown, and trends	read

Alerts

Tool	Description	Scope
`list_alerts`	List alerts configured on an endpoint	read
`create_alert`	Create a new alert (missing webhook, error response, keyword match, volume spike)	write

Example Workflows

Debug a failing Stripe webhook

You: "Show me the latest Stripe requests on endpoint ep_abc123"
AI:  Lists recent Stripe webhooks with signature status

You: "Diagnose request req_xyz789"
AI:  Shows signature verification is failing, no signing secret configured,
     recommends adding the signing secret in endpoint settings

You: "What's the setup status for endpoint ep_abc123?"
AI:  Shows 2/3 Stripe setup checks passing, missing signing secret

Wait for a webhook during development

You: "Create a new endpoint called 'stripe-dev'"
AI:  Creates the endpoint, gives you the webhook URL

You: "Wait for the next Stripe checkout event on that endpoint"
AI:  Blocks until a matching webhook arrives, then shows the full
     provider-enriched payload with event type, customer ID, amount, etc.

You: "Compare this with the previous checkout event"
AI:  Shows provider-aware diff highlighting what changed

Debug locally through a tunnel

Use the CatchHook CLI tunnel for localhost delivery; Endpoint Action Forward steps handle remote destinations.

You: "Show me how to tunnel ep_abc123 to localhost:4000"
AI:  Gives you the CatchHook CLI command to run on your machine:
     npx @catchhook/tunnel start --endpoint ep_abc123 --port 4000

You: "Send a test request to ep_abc123"
AI:  Sends a test webhook, which the active tunnel delivers to localhost

You: "Show me the endpoint metrics for the last hour"
AI:  Shows request counts, error rates, and tunnel delivery health

Authentication

The MCP server uses bearer token authentication. The same API tokens that work with the REST API work here. Tokens must have:

read scope for all tools
write scope for tools that create, modify, or delete resources

Create and manage API tokens in Account Settings → API Tokens.

Troubleshooting

"Unauthorized" error — Check that your API token is valid and the Authorization: Bearer header is set correctly in your MCP config.

"Token missing required scope: write" — The tool you're calling requires write access. Edit your API token in Account Settings to add the write scope.

wait_for_request times out — Default timeout is 15 seconds (max 30). Make sure the webhook is going to the correct endpoint URL, and check if provider or event_type filters are too restrictive. You can also call list_requests after a short wait as an alternative.

Editor can't connect — Verify the URL is https://catchhook.app/mcp and your editor supports Streamable HTTP MCP transport.

Protocol

The MCP server implements JSON-RPC 2.0 over HTTP POST at POST /mcp. It supports the initialize, tools/list, tools/call, and ping methods. Error codes follow the JSON-RPC 2.0 specification.