MCP Setup

Connect Hooklistener to your AI coding assistant.

Prerequisites

1. A Hooklistener account
2. An API key starting with hklst_ (create one at Organization Settings > API Keys)

Claude Code

Run in your terminal:

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

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",
      "headers": {
        "Authorization": "Bearer hklst_your_api_key_here"
      }
    }
  }
}

OpenAI Codex CLI

export HOOKLISTENER_API_KEY=hklst_your_api_key_here
codex mcp add hooklistener --transport streamable-http \
  --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",
      "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",
      "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 hklst_... header
• 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 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-client","version":"1.0"}}}'

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

Troubleshooting

"Authentication required" error — your API key is missing or invalid. Generate one from Organization Settings > API Keys. Make sure it starts with hklst_.

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.

"Tool not found" error — make sure your plan includes API access. The free plan includes API access, but some features (like uptime monitors) require a paid plan.