MCP server

Hooks hosts a Model Context Protocol server so an AI assistant can inspect a workspace without copying REST calls by hand. The endpoint is a stateless Streamable HTTP server at:

https://api.hooks.events/mcp

Authentication uses the same Bearer API key as the REST API. The key’s scopes decide which tools are visible and what each tool can read or change.

Connect a client

Create an API key in Settings → API keys with at least endpoints:read and deliveries:read. Keep it in an environment variable or the client’s secret store; never paste it into a shared config file.

Claude Code

claude mcp add --transport http hooks https://api.hooks.events/mcp \
  --header "Authorization: Bearer $HOOKS_API_KEY"

Cursor

Add the server to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hooks": {
      "url": "https://api.hooks.events/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HOOKS_API_KEY}"
      }
    }
  }
}

Generic MCP client

Any client that supports Streamable HTTP can use the same URL and header:

{
  "mcpServers": {
    "hooks": {
      "type": "http",
      "url": "https://api.hooks.events/mcp",
      "headers": {
        "Authorization": "Bearer hks_..."
      }
    }
  }
}

The server has no OAuth flow and keeps no session state, so no Mcp-Session-Id is issued. POST carries every JSON-RPC message; GET and DELETE return 405.

Read tools

Read tools are always available and require the same scopes as the equivalent REST route.

Tool	Scope	Purpose
list_events	endpoints:read	List events, filtered by endpoint, routing status, text or field.
search_events	endpoints:read	Free-text and body.<path>=<value> / headers.<name>=<value>.
get_event	endpoints:read	Read one event; optionally include the raw payload.
list_deliveries	deliveries:read	List deliveries by status, endpoint, destination or replay job.
get_delivery	deliveries:read	Read one delivery and every recorded attempt.
list_issues	deliveries:read	List aggregated destination failures.
get_issue	deliveries:read	Read one aggregated issue.
list_endpoints	endpoints:read	List non-archived (or filtered) endpoints.
get_endpoint	endpoints:read	Read one endpoint, its source config and hooks.
get_metrics	metrics:read	Totals, status breakdown, latency percentiles and buckets.

Every query is scoped to the API key’s workspace. Cross-workspace ids return a tool error instead of data.

Search examples

Ask the assistant to run, or call directly:

{ "name": "search_events", "arguments": { "filter": "body.order.id=1042" } }

{ "name": "search_events", "arguments": { "q": "checkout failed" } }

Search only covers inline payloads (up to 256 KiB). Payloads moved to object storage are not full-text indexed.

Write tools

Write tools are off by default. To enable them, create an API key that also carries mcp:write, plus the scope each tool needs:

Tool	Scopes	Purpose
retry_delivery	deliveries:retry, mcp:write	Requeue one delivery.
replay_event	deliveries:retry, mcp:write	Re-derive deliveries for one event.
create_endpoint	endpoints:write, mcp:write	Create an endpoint without destinations.
update_endpoint	endpoints:write, mcp:write	Rename, pause, or change signing config.

Without mcp:write, write tools are omitted from tools/list and calls to them fail. Destinations and secrets are still managed through the REST API or console.

Protocol details

• Supported revisions: 2025-06-18, 2025-03-26, 2024-11-05.
• Transports: Streamable HTTP, POST /mcp with Content-Type: application/json.
• Notifications (for example notifications/initialized) return 202 with an empty body.
• JSON-RPC batches are rejected with -32600; send one message per request.
• Tool failures return an MCP result with isError: true and a CODE: message text block. Protocol-level problems use standard JSON-RPC errors (-32601 unknown method, -32602 unknown tool or invalid params).

Limits

• MCP calls share the REST API rate limit: 600 requests per minute per key.
• List tools return at most 100 rows per call and accept an opaque cursor for the next page.
• get_metrics accepts the same 90-day, 2000-bucket limits as GET /v1/metrics.