How to Give Your AI Coding Assistant Access to Your Webhooks via MCP

You're deep in a debugging session. Your AI coding assistant is helping you trace a payment flow bug. It asks what the last Stripe webhook payload looked like. So you leave your editor, open the Hooklistener dashboard, find the endpoint, locate the request, copy the JSON body, and paste it back into your conversation.

The whole thing takes 30 seconds, but it breaks your focus completely. And you do it dozens of times a day.

There's a better way. The Model Context Protocol (MCP) lets your coding assistant talk directly to Hooklistener's MCP server. No tab-switching. No copy-pasting. Just ask "show me the last webhook on my Stripe endpoint" and get the answer inline. This guide shows you how to set it up in under two minutes.

Think of MCP as a USB-C port for AI assistants. Before USB-C, every device had its own charger. Before MCP, every AI tool needed custom integrations to access external data.

MCP standardizes how AI assistants discover and use external tools. Here's the mental model:

• MCP Server = a service that exposes "tools" (functions the AI can call). Hooklistener runs one at app.hooklistener.com/api/mcp.
• MCP Client = your AI assistant (Claude Code, Cursor, etc.). It connects to the server, discovers the tools, and calls them when relevant.
• Tools = specific actions like "list endpoints", "get a captured request", or "create an uptime monitor". The AI decides when to call them based on your conversation.

The AI doesn't just fetch raw data—it understands the tool schemas, picks the right one, formats the arguments, and presents the result in context. You ask a question in plain English; it handles the plumbing.

You need exactly one thing: a Hooklistener account. That's it.

The MCP server uses OAuth 2.0 for authentication. When you add the server, your client opens a browser, you sign in to Hooklistener, and you're connected. Under the hood it's the full modern OAuth stack—server discovery, dynamic client registration, and PKCE—but you never see any of that. No tokens to copy, no secrets to store in config files.

If your MCP client doesn't support OAuth, there's a legacy fallback: an API key generated from Organization Settings > API Keys (keys start with hklst_). API-key auth is deprecated—tool responses include a deprecation notice nudging you to reconnect with OAuth—but it still works.

Claude Code has first-class MCP support. One command, and you're connected.

# OAuth 2.0 (recommended) — signs in via browser automatically
claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp

Run /mcp, pick "hooklistener", and choose authenticate. Your browser opens, you sign in, and the connection is live. This registers the server for the current project. Use --scope user to make it available across all your projects, or --scope project to write it to .mcp.json so your whole team gets it—each teammate signs in with their own account, so there's nothing secret in the file.

Verify it's working by typing /mcp in Claude Code. You should see "hooklistener" listed with 67 tools.

Legacy: API key

If you can't use the browser flow, pass an API key as a bearer header instead. This is deprecated—tool responses will include a notice asking you to reconnect with OAuth—but it works:

claude mcp add --transport http hooklistener \
  https://app.hooklistener.com/api/mcp \
  --header "Authorization: Bearer hklst_your_api_key_here"

Manual alternative

If you prefer editing config files directly, add this to .mcp.json (project-level) or ~/.claude.json (user scope). No headers needed—Claude Code handles the OAuth sign-in when you first connect:

{
  "mcpServers": {
    "hooklistener": {
      "type": "http",
      "url": "https://app.hooklistener.com/api/mcp"
    }
  }
}

Cursor supports OAuth for streamable HTTP servers, so the config is just a URL. Add this to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "hooklistener": {
      "url": "https://app.hooklistener.com/api/mcp"
    }
  }
}

Restart Cursor or reload MCP servers from the settings panel, then complete the browser sign-in when prompted. The tools will appear in Cursor's agent mode. If you need the legacy API-key route instead, add a "headers" object with "Authorization": "Bearer hklst_your_api_key_here".

Codex supports OAuth for streamable HTTP servers. Add the server, then sign in with your browser:

codex mcp add hooklistener \
  --url https://app.hooklistener.com/api/mcp \
  --oauth-resource https://app.hooklistener.com/api/mcp

codex mcp login hooklistener --scopes full_access

Use --scopes read_only if the agent should only inspect traffic: it can search, wait, diff, and diagnose, but not create, delete, or replay anything. Or add the server manually to ~/.codex/config.toml and run the same login command:

[mcp_servers.hooklistener]
url = "https://app.hooklistener.com/api/mcp"
oauth_resource = "https://app.hooklistener.com/api/mcp"

If you can't use OAuth, keep an API key in an environment variable and reference it with bearer_token_env_var = "HOOKLISTENER_API_KEY" instead of oauth_resource.

Once connected, your AI assistant has access to 67 tools in 7 toolsets. A new workspace lists 26 of them (the webhook tools plus each product's create tool); the rest appear after you start using that product and reconnect. The server launched with 8 tools and has grown with every release (see the changelog). You don't call these tools directly—the assistant picks the right one based on what you ask.

We won't describe all 67 here. Instead, here are the tools worth knowing about, then a map of the full surface.

The standouts

The full map

The full reference with every parameter schema lives in the MCP tools documentation.

Here's where it clicks. These aren't hypothetical—they're the workflows that made us build this in the first place.

You don't need to understand the protocol to use it, but knowing the basics helps when things go wrong.

Hooklistener's MCP server uses the Streamable HTTP transport. Your AI assistant communicates with it via JSON-RPC 2.0 over plain HTTP POST requests to a single endpoint: /api/mcp.

The flow looks like this:

1. Your assistant sends an initialize request with its client info
2. The server responds with its capabilities (what tools it supports)
3. The assistant calls tools/list to discover available tools and their parameter schemas
4. When you ask a question, the assistant picks the right tool and calls tools/call with the arguments
5. The server validates your credentials, runs the query, and returns the result

Every request after initialize includes an mcp-session-id header to maintain session context. Authentication works one of two ways. With OAuth (the default), you sign in once via browser and your client attaches a short-lived access token to every request—discovery, dynamic client registration, and PKCE all happen automatically. With a legacy API key, the key rides along as an Authorization: Bearer header on every call instead.

If you want to see what your AI assistant is doing behind the scenes, you can hit the MCP server directly with curl. This is also useful for debugging connection issues. These examples use an API key because curl can't do a browser OAuth dance—it's the one place the legacy auth still earns its keep.

Initialize a session

curl -X POST https://app.hooklistener.com/api/mcp \
  -H "Authorization: Bearer hklst_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "my-test",
        "version": "1.0"
      }
    }
  }'

Grab the mcp-session-id from the response headers, then list tools:

List available tools

curl -X POST https://app.hooklistener.com/api/mcp \
  -H "Authorization: Bearer hklst_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: SESSION_ID_FROM_ABOVE" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

You'll see all 67 tools with their names, descriptions, and parameter schemas. This is exactly what your AI assistant sees when it connects.

Every tool call is authenticated and scoped to your organization. There's no way to access another organization's data through the MCP server—every database query is filtered by your organization ID.

OAuth is the safer default, and it's why we made it the primary flow. Access tokens are short-lived (one hour, with a 30-day refresh token), so a leaked token expires on its own. And because the client handles the token exchange, there are no secrets sitting in your config files—a committed .mcp.json contains nothing but a URL.

If you're still on a legacy API key: it's hashed with SHA-256 before storage—we never store it in plaintext. When you make a request, we match on a prefix, then verify the full hash. But API-key auth for MCP is deprecated, and every tool response includes a deprecation notice asking you to reconnect with OAuth.

For team environments still using keys, avoid putting them directly in .mcp.json if it's committed to version control. Use environment variables or keep the key in a local config file that's gitignored. Codex CLI's bearer-token-env-var pattern is a good example. Or, again: OAuth makes the whole problem disappear.

The real value isn't any single tool call. It's the compound effect of your AI assistant having live context about your webhooks while it helps you write code.

When you're writing a Stripe webhook handler and the assistant can see the actual payload that just came in, it writes better code. When you're debugging a failed integration and the assistant can inspect the headers and body—or just call diagnose_request—it finds the bug faster. When it can trigger a flow and wait on wait_for_request until the webhook lands, it verifies its own work.

The setup takes two minutes: claude mcp add, sign in, done. If you want the high-level overview of everything the server exposes, the MCP server page has it. The time you save compounds every day.