MCP setup · Claude Code

Hooklistener MCP server for Claude Code

Q: How do I add a remote MCP server to Claude Code?

Use claude mcp add --transport http . For Hooklistener that is claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp, followed by /mcp to sign in.

Q: Where does Claude Code store MCP servers?

Local and user scopes go in ~/.claude.json. Project scope goes in .mcp.json at the repository root, which is meant to be committed.

Q: Can Claude Code wait for a webhook to arrive?

Yes. wait_for_request waits for the matching webhook: it returns a task Claude follows until the webhook lands, or holds the call open for up to 60 seconds with blocking: true. Claude can trigger an event and check the result in one flow.

Run claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp, then type /mcp inside Claude Code, pick hooklistener and sign in with your browser. Claude Code can then create a webhook URL, wait for the next webhook, verify its signature and replay it to your local server, all from the conversation. Nothing is installed locally: the server is hosted and speaks Streamable HTTP.

Setup checked against Claude Code docs, September 2026

Terminal

claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp

# then, inside Claude Code:
/mcp   # select "hooklistener" → Authenticate

Add command: claude mcp add --transport http
Config file: ~/.claude.json (local, user) or .mcp.json (project)
Transport: "type": "http" (alias streamable-http)
Sign-in: OAuth in the browser via /mcp or claude mcp login
Read-only: Pin oauth.scopes to read_only

Setup

Connect Claude Code step by step

Add the server

The default scope is local: only you, only this project, stored in ~/.claude.json. Add --scope user to enable it in every project, or --scope project to write a .mcp.json you can commit.

Terminal

# just you, this project (default)
claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp

# just you, every project
claude mcp add --transport http --scope user hooklistener https://app.hooklistener.com/api/mcp

# whole team, checked into the repo as .mcp.json
claude mcp add --transport http --scope project hooklistener https://app.hooklistener.com/api/mcp

02
Sign in with OAuth
Inside Claude Code run /mcp, select hooklistener and choose to authenticate. Your browser opens Hooklistener's consent page; pick the organization if you belong to more than one and click Authorize. From a plain shell, claude mcp login hooklistener does the same. Over SSH add --no-browser, open the printed URL on your laptop and paste the callback URL back.
03
Check that it connected
claude mcp list should show hooklistener as ✔ Connected. ! Needs authentication means the browser step has not finished yet; ⏸ Pending approval means a project-scoped server is waiting for you to trust it.
Terminal
```
claude mcp list
claude mcp get hooklistener
```
04
Share it with your team
The project-scoped file only holds the URL. Each developer signs in with their own Hooklistener account, so no token ever lands in git.
.mcp.json
```
{
  "mcpServers": {
    "hooklistener": {
      "type": "http",
      "url": "https://app.hooklistener.com/api/mcp"
    }
  }
}
```

Read-only access

Claude Code lets you pin the OAuth scope it requests. Set oauth.scopes to read_only and the grant can search, wait, diff, validate and diagnose, but cannot create, edit, delete, replay, forward or send. If you already signed in with full access, run claude mcp logout hooklistener first so a new read-only token is issued.

.mcp.json

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

Try it

What to ask Claude Code

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

Create a Hooklistener endpoint called stripe-dev, point my Stripe CLI at it, trigger checkout.session.completed and wait for the webhook.

Claude gets a webhook URL, runs the trigger in your terminal, then waits for the event and reads the payload back.

create_endpoint
wait_for_request

Verify the Stripe signature on that request, then replay it to my local server with the amount changed to 0 and re-signed.

The replay goes through hooklistener listen on your machine (target cli), with a JSON merge patch on the body and a fresh Stripe signature from a stored secret.

verify_request_signature
replay_request

Make a test inbox, sign up on localhost:3000 with that address and check the verification email has a working link.

Claude drives the signup, waits for the email and reads the links and headers without leaving the terminal.

create_inbox
wait_for_email
get_email

Save the last three captured webhooks as replay cases expecting a 200, and run them against localhost after every change to the handler.

Real captured traffic becomes a regression suite Claude can rerun while it edits your webhook handler.

save_request_case
run_endpoint_cases
wait_for_case_run

Troubleshooting

When Claude Code doesn't connect

MCP server "hooklistener" has a "url" but no "type": Claude Code needs a transport in .mcp.json. Add "type": "http". The spec name "streamable-http" is accepted as an alias, so configs copied from elsewhere keep working.
The server shows ⏸ Pending approval: Project-scoped servers from .mcp.json wait for you to trust them in an interactive session. Accept the prompt. If you declined earlier, run claude mcp reset-project-choices and start Claude Code again.
Edits to .mcp.json or ~/.claude.json have no effect: Restart the Claude Code session after changing MCP config. Check the file is valid JSON: no trailing commas and no comments.
Large payloads get cut off: Claude Code warns when a tool result passes 10,000 tokens and stops at 25,000 by default. Raise the limit with MAX_MCP_OUTPUT_TOKENS, or ask for a specific request instead of a long list.
Terminal
export MAX_MCP_OUTPUT_TOKENS=50000 claude

FAQ

Claude Code and Hooklistener: common questions

How do I add a remote MCP server to Claude Code?

Use claude mcp add --transport http <name> <url>. For Hooklistener that is claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp, followed by /mcp to sign in.

Where does Claude Code store MCP servers?

Local and user scopes go in ~/.claude.json. Project scope goes in .mcp.json at the repository root, which is meant to be committed.

Do I need an API key for Claude Code?

No. Claude Code supports OAuth for remote servers, so you sign in once in the browser and tokens are stored for you. Nobody on the team has to paste a key into a config file.

Can Claude Code wait for a webhook to arrive?

Yes. wait_for_request waits for the matching webhook: it returns a task Claude follows until the webhook lands, or holds the call open for up to 60 seconds with blocking: true. Claude can trigger an event and check the result in one flow.

Does it work on the free plan?

Yes. MCP is on every plan. Free includes 1 debug endpoint with 1 day of history, 1 email inbox, 1 uptime monitor and 3 saved replay cases. Signature verification and re-signing need stored secrets, which are on paid plans.

Keep going

More on the MCP server

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

Other clients

Set up Hooklistener in another tool

Give Claude Code 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 free See all MCP tools