Getting started

MCP setup

Wire Pixelhooks into an AI agent so it can create bins and wait for requests.

Pixelhooks ships an MCP server, @pixelhooks/mcp, that lets an AI agent create bins and inspect captured requests directly — no browser, no manual curl. It runs locally over stdio and talks to the public Pixelhooks API, so there's nothing to host.

The headline tool is wait_for_request: point a service at a bin, then ask the agent to wait, and it blocks until the next request lands and hands back the full detail.

Install

The server runs via npx, so there's no global install. Add it to your client's MCP configuration.

The server talks to the hosted Pixelhooks API out of the box — there's nothing to host or configure.

Claude Code

claude mcp add pixelhooks -- npx -y @pixelhooks/mcp

Or add it to .mcp.json in your project:

{
  "mcpServers": {
    "pixelhooks": {
      "command": "npx",
      "args": ["-y", "@pixelhooks/mcp"]
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pixelhooks": {
      "command": "npx",
      "args": ["-y", "@pixelhooks/mcp"]
    }
  }
}

Cursor

Add the same mcpServers block to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project), then restart Cursor.

Tools

Tool	Arguments	Returns
`create_bin`	—	New bin id, its capture URL, and a human view URL.
`get_bin`	`binId`	Bin metadata (confirms it exists).
`list_requests`	`binId`	Captured request summaries, newest first.
`get_request`	`binId`, `requestId`	One request in full: method, headers, query, path, body.
`wait_for_request`	`binId`, `timeoutMs?`	Blocks until the next request arrives, then returns it. Bounded (default 25s); returns a "no request yet" result on timeout.
`list_my_bins`	`cursor?`	Your account's bins (newest first) with capture/view URLs. Up to 500 per call; when `hasMore` is set, pass the returned `nextCursor` back as `cursor` for the next page.
`delete_bin`	`binId`	Removes a bin from your account — an unlink, not a destructive delete, so captured data persists.
`rename_bin`	`binId`, `label?`	Sets or clears a bin's label. Omit or empty `label` to clear it; max 255 characters.
`get_response_config`	`binId`	Reads a bin's configured capture response (`{ configured, config }`).
`set_response_config`	`binId`, `status?`, `contentType?`, `body?`, `headers?`, `delayMs?`	Configures the response the capture endpoint serves — a full replacement (omitted fields revert to defaults).
`clear_response_config`	`binId`	Clears a bin's response config, reverting the capture endpoint to `200 OK`.

list_my_bins, delete_bin, rename_bin, get_response_config, set_response_config, and clear_response_config are account-scoped: set PIXELHOOKS_API_TOKEN (a personal access token) in the server config to use them. Without a token they return an actionable error rather than acting anonymously.

A typical loop

A debugging session usually looks like this:

create_bin → the agent gets a capture URL like https://hooks.pixelhop.io/h/abc123cuid.
The agent configures the service under test (or asks you to) to send to that URL.
wait_for_request with the binId → the agent blocks until the webhook fires, then receives the method, headers, and body of exactly what was sent.
If nothing arrives within the timeout, the tool returns a "no request yet" result and the agent can simply call it again.

The bin id is the only key to its requests — treat capture URLs as secrets and don't paste them where you wouldn't paste a token.

What's next

llms.txt and agents — let an agent read these docs directly.
REST API reference — what each tool calls under the hood.