Skip to main content

MCP Setup

Connect Hooklistener to your AI coding assistant.

Fastest: let the agent connect itself

Paste one prompt into your agent and approve one link. It tests one of your webhooks first and works with any agent that can run a terminal. See Connect with one prompt. The steps below set up the server by hand.

Prerequisites​

  1. A Hooklistener account

That's it — if your MCP client supports OAuth 2.0, authentication is handled automatically. No API key needed.

OAuth 2.0 recommended

MCP clients that support OAuth 2.0 (like Claude Code) will automatically open a browser window for you to authorize access. This is more secure and easier to set up than API keys.

Claude Code​

Run in your terminal:

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

Claude Code will automatically initiate the OAuth 2.0 flow — a browser window opens where you sign in and authorize access. No API key required.

Add --scope project to share with your team (writes to .mcp.json), or --scope user for all your projects.

Run /mcp in Claude Code to verify the server appears.

Or add manually to .mcp.json

Add to .mcp.json (project) or ~/.claude/mcp.json (global):

{
  "mcpServers": {
    "hooklistener": {
      "type": "streamable-http",
      "url": "https://app.hooklistener.com/api/mcp"
    }
  }
}
Using an API key instead (legacy)
claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp \
  --header "Authorization: Bearer hklst_your_api_key_here"

Or in .mcp.json:

{
  "mcpServers": {
    "hooklistener": {
      "type": "streamable-http",
      "url": "https://app.hooklistener.com/api/mcp",
      "headers": {
        "Authorization": "Bearer hklst_your_api_key_here"
      }
    }
  }
}
warning

API key authentication for MCP is deprecated. We recommend switching to OAuth 2.0 for better security and easier credential management.

OpenAI Codex CLI​

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

If your Codex CLI version supports OAuth 2.0, authentication is handled automatically. Otherwise, use an API key:

Using an API key
export HOOKLISTENER_API_KEY=hklst_your_api_key_here
codex mcp add hooklistener --url https://app.hooklistener.com/api/mcp \
  --bearer-token-env-var HOOKLISTENER_API_KEY

Or add manually to ~/.codex/config.toml:

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

Set HOOKLISTENER_API_KEY in your shell environment.

Cursor​

Add to .cursor/mcp.json in your project root:

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

If Cursor supports OAuth 2.0 for MCP, it will handle authentication automatically. Otherwise, add an Authorization header with your API key:

{
  "mcpServers": {
    "hooklistener": {
      "type": "streamable-http",
      "url": "https://app.hooklistener.com/api/mcp",
      "headers": {
        "Authorization": "Bearer hklst_your_api_key_here"
      }
    }
  }
}

Restart Cursor or reload MCP servers from the settings panel.

Windsurf​

Add to ~/.codeium/windsurf/mcp_config.json:

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

If Windsurf supports OAuth 2.0 for MCP, it will handle authentication automatically. Otherwise, add an Authorization header with your API key:

{
  "mcpServers": {
    "hooklistener": {
      "serverUrl": "https://app.hooklistener.com/api/mcp",
      "headers": {
        "Authorization": "Bearer hklst_your_api_key_here"
      }
    }
  }
}

Any MCP client (manual)​

The server speaks JSON-RPC 2.0 over HTTP POST. Send requests to /api/mcp with:

  • Authorization: Bearer <access_token> header (OAuth 2.0 access token or hklst_ API key)
  • Content-Type: application/json
  • Accept: application/json, text/event-stream
# Initialize the session
curl -X POST https://app.hooklistener.com/api/mcp \
  -H "Authorization: Bearer <your_access_token>" \
  -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-client","version":"1.0"}}}'

Use the mcp-session-id response header for subsequent requests.

For OAuth 2.0 token management in custom clients, see the Authentication guide.

Choosing toolsets​

By default, a session lists the webhook tools plus the toolsets your organization already uses (see Available Tools). To choose toolsets yourself, send the x-hooklistener-toolsets header with a comma-separated list or all:

claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp \
  --header "x-hooklistener-toolsets: all"

In .mcp.json and other clients' JSON config, add it under headers:

"headers": {
  "x-hooklistener-toolsets": "email,monitors"
}

Choosing toolsets​

By default, a session lists the webhook tools plus the toolsets your organization already uses (see Available Tools). To choose toolsets yourself, send the x-hooklistener-toolsets header with a comma-separated list or all:

claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp \
  --header "x-hooklistener-toolsets: all"

In .mcp.json and other clients' JSON config, add it under headers:

"headers": {
  "x-hooklistener-toolsets": "email,monitors"
}

Troubleshooting​

"Authentication required" error — if using OAuth, try removing and re-adding the server to restart the auth flow. If using an API key, make sure it starts with hklst_ and is valid.

OAuth consent page not opening — make sure your browser is accessible. Some environments (e.g., remote SSH sessions) may not be able to open a browser window. In that case, use an API key instead.

Server not showing up in Claude Code — run /mcp to check status. Verify your .mcp.json is valid JSON and restart Claude Code after changes.

Your assistant can't see a tool — sessions only list the toolsets your organization uses. After creating your first inbox, monitor, real-time endpoint, saved case, or response rule, reconnect the MCP client (for example /mcp in Claude Code) to list the rest of that toolset, or send x-hooklistener-toolsets: all. See Choosing toolsets.

Your assistant can't see a tool — sessions only list the toolsets your organization uses. After creating your first inbox, monitor, real-time endpoint, saved case, or response rule, reconnect the MCP client (for example /mcp in Claude Code) to list the rest of that toolset, or send x-hooklistener-toolsets: all. See Choosing toolsets.

"Tool not found" error — the MCP server is available on every plan, but tools follow your plan's limits and features. For example, the secrets tools need a paid plan, and the Free plan allows 1 debug endpoint. See Plans & Billing.