Skip to content

Docs / Reference

MCP server for coding agents

WebhookHQ's MCP server lets a coding agent find, inspect, replay and wait for your webhooks while you debug: "find the last failed Stripe event and replay it to localhost after my fix". It works with any client that speaks the Model Context Protocol over HTTP, on every plan.

MCP or the CLI? Agents that run commands in your terminal (Claude Code, Codex, Cursor's agent) can also use the whq CLI the way they use gh: no server to add, and whq login keeps the token out of their configuration (whq help agents shows how). Use MCP for clients that can't run commands, such as Claude Desktop, or when you'd rather give the agent tools than a shell.

Connect

The server is at https://mcp.webhookhq.dev/v1/mcp. It signs in with an access token: create one on the Access tokens tab (a personal token sees what you can see; a service token, made by owners and admins, sees the whole organization).

Put the token in an environment variable, WHQ_TOKEN, so it never sits in a file you might commit; the setups below read it from there.

Claude Code: add .mcp.json to your project (safe to commit: it holds no token):

{
  "mcpServers": {
    "webhookhq": {
      "type": "http",
      "url": "https://mcp.webhookhq.dev/v1/mcp",
      "headers": { "Authorization": "Bearer ${WHQ_TOKEN}" }
    }
  }
}

Start Claude Code with WHQ_TOKEN set, and /mcp shows webhookhq as connected. For every project instead, claude mcp add --transport http --scope user webhookhq https://mcp.webhookhq.dev/v1/mcp --header "Authorization: Bearer $WHQ_TOKEN" saves the token in your own Claude Code settings.

Cursor: add it to the project's .cursor/mcp.json (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "webhookhq": {
      "url": "https://mcp.webhookhq.dev/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:WHQ_TOKEN}" }
    }
  }
}

Other clients: use the URL with the Streamable HTTP transport and send Authorization: Bearer whq_... on every request. The server follows MCP 2026-07-28 (stateless requests) and also answers clients on 2025 versions.

Never commit the token itself. Revoking it on the Access tokens tab disconnects the client at once.

Tools

  • find_webhooks: finds captured webhooks on the endpoints you can open, newest first. Filters by endpoint, event type, sender, delivery state and time, or searches the text; a search starting with $ is a JSONPath condition on JSON bodies ($.data.object.amount > 1000). Returns short summaries (id, time, type, sender, delivery state, size), never bodies, a page at a time.
  • inspect_webhook: one webhook in full: headers, body (cut after 32 KB), the signature check when the endpoint has a signing secret, and every delivery with each attempt's status and response (first 16 KB). Takes the full id or the short id the dashboard and whq listen show.
  • replay_webhook: sends a webhook again, unchanged, to one of the endpoint's destinations, a public URL, or your machine through your open whq listen tunnel. Needs editor access to the endpoint's workspace. Private addresses are refused, as in the dashboard.
  • wait_for_webhook: waits up to 25 seconds for the next webhook on an endpoint (optionally of one type) and returns its summary: "I'm sending a test now, tell me when it lands." If nothing came, the agent calls it again to keep waiting, without missing one. When many agents are waiting at once it may answer "busy" straight away; the agent calls again a few seconds later.

The read tools are marked read-only, so your client can run them without asking. replay_webhook is marked as one that changes something outside the client, so clients that ask before such tools ask you.

Replays ask first

replay_webhook never sends on the first call. It shows what it would send (method, path, where to, body size) and waits for you to confirm:

  • Clients that support forms (MCP 2026-07-28 with elicitation) show you a Send it checkbox; only your answer sends it.
  • Other clients get the preview and a one-time confirmation that your agent passes back after you agree. It's valid for 10 minutes and sends once.

Every replay shows up in the webhook's deliveries, as a replay from the dashboard does.

Limits

No daily cap, on any plan: each access token can make up to 300 requests a minute. Webhooks hidden over your plan's monthly events stay hidden here too, and you can read webhooks for as long as your plan keeps them.

Safety

Webhook headers and bodies come from whoever sent them. Results mark them as third-party data, and the tools tell agents never to follow instructions found inside them. Only replay_webhook changes anything, and only after you confirm. Every tool call is recorded with the token that made it.