Hooklistener

MCP setup · Cursor

Hooklistener MCP server for Cursor

Add Hooklistener to .cursor/mcp.json (this project) or ~/.cursor/mcp.json (every project) as an entry under mcpServers with just a url. No type field is needed for a remote server, and Cursor supports OAuth, so you sign in with your browser instead of pasting a key. Cursor's agent can then create webhook URLs, wait for events and replay them while it edits your handler.

Setup checked against Cursor docs, September 2026

.cursor/mcp.json
{
  "mcpServers": {
    "hooklistener": {
      "url": "https://app.hooklistener.com/api/mcp"
    }
  }
}
Config file
.cursor/mcp.json or ~/.cursor/mcp.json
Top-level key
mcpServers
Transport
url only; type is for stdio servers
Sign-in
OAuth; headers with ${env:NAME} for keys
Logs
Output panel → MCP Logs

Setup

Connect Cursor step by step

  1. 01

    Create the config file

    Use .cursor/mcp.json in the repository to share the setup with your team, or ~/.cursor/mcp.json to have Hooklistener in every project. Both use the same shape.

    .cursor/mcp.json
    {
  "mcpServers": {
    "hooklistener": {
      "url": "https://app.hooklistener.com/api/mcp"
    }
  }
}
  2. 02

    Sign in

    Cursor supports OAuth for servers that require it, and Hooklistener does. Open the Customize page in Cursor's sidebar, where MCP servers are listed, make sure hooklistener is enabled and complete the sign-in in your browser. On Hooklistener's consent page choose the organization and click Authorize.

  3. 03

    Check that it connected

    The server and its tools appear on the Customize page. If it doesn't, open the Output panel (Cmd+Shift+U), pick MCP Logs from the dropdown and look for the hooklistener lines.

  4. 04

    Ask the agent

    Tell the agent what you want tested in plain language. It picks the Hooklistener tools on its own; you approve the calls it makes.

Read-only access

Cursor only exposes OAuth scopes in its static auth block, which needs a pre-registered CLIENT_ID. Hooklistener registers Cursor on the fly instead, so Cursor gets the default full-access grant. The consent page lists exactly what that grant allows. If you want an agent that can only inspect traffic, connect it through a client that can request read_only (Codex, Claude Code or Gemini CLI).

Try it

What to ask Cursor

Plain-language requests work; Cursor picks from Hooklistener's 67 tools. These are the ones each prompt usually calls.

Create an endpoint for Shopify orders/create, give me the URL to paste in the Shopify admin, and wait for the first order.

The agent shows the URL, waits until Shopify delivers and summarizes the payload next to your handler.

  • create_endpoint
  • wait_for_request

Make the endpoint answer 500 so I can see how the sender retries, then remove the rule.

A mock response rule forces the failure; the agent then reads the retry timing and headers.

  • create_response_rule
  • investigate_request_retries
  • delete_response_rule

Verify the GitHub signature on the last push event and replay it to my local handler re-signed with the same secret.

Signature check and re-signed replay through hooklistener listen, so your local handler sees a valid request.

  • verify_request_signature
  • replay_request

Create a WebSocket endpoint, point my client in src/realtime.ts at it, and tell me what it sends on connect.

Hooklistener hosts the socket; the agent reads your client's frames and can push messages back.

  • create_realtime_endpoint
  • wait_for_realtime_message
  • send_realtime_message

Troubleshooting

When Cursor doesn't connect

Copied a config with "type": "streamable-http" or "streamableHttp"
Cursor's docs use type only for stdio servers. For a remote server, url is enough, so drop the type line if the server doesn't load.
The server never shows up
Check the top-level key is mcpServers (VS Code uses servers) and that the file is strict JSON: no trailing comma after the last entry and no comments. Then look at Output → MCP Logs.
You need a key instead of OAuth (shared machine, locked-down browser)
Put a Hooklistener API key in an environment variable and reference it from headers. Cursor's syntax is ${env:NAME}, not $NAME. API keys always have full access.
~/.cursor/mcp.json
{
  "mcpServers": {
    "hooklistener": {
      "url": "https://app.hooklistener.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HOOKLISTENER_API_KEY}"
      }
    }
  }
}

FAQ

Cursor and Hooklistener: common questions

What does a Cursor mcp.json look like for a remote Streamable HTTP server?

An entry under mcpServers with a url, for example {"mcpServers":{"hooklistener":{"url":"https://app.hooklistener.com/api/mcp"}}}. Add a headers object only if the server needs a static key.

Does Cursor support OAuth for MCP servers?

Yes. Cursor's docs say it supports OAuth for servers that require it. Hooklistener uses OAuth with dynamic client registration, so no client ID or secret goes in the config.

How do I pass an API key in Cursor's MCP headers?

Add "headers": {"Authorization": "Bearer ${env:HOOKLISTENER_API_KEY}"} to the server entry and export the variable before starting Cursor. Create keys under Organization Settings → API Keys in Hooklistener.

Where do I see MCP errors in Cursor?

Open the Output panel with Cmd+Shift+U (Ctrl+Shift+U on Windows and Linux) and choose MCP Logs from the dropdown.

Keep going

More on the MCP server

Server URL: https://app.hooklistener.com/api/mcp

Other clients

Set up Hooklistener in another tool

Give Cursor a webhook URL it can watch

The free plan includes the MCP server, 1 debug endpoint, 1 email inbox and 1 uptime monitor. No credit card.

Start freeSee all MCP tools