> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pickupbell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server overview

> PickupBell ships a Model Context Protocol server so AI agents can operate on the same data your dashboard shows.

## Endpoint

```
https://api.pickupbell.com/api/mcp
```

All MCP traffic is JSON-RPC 2.0 over HTTP. We implement the three methods Claude / ChatGPT / Cursor actually use:

* `initialize` — no auth, returns protocol version + server info.
* `tools/list` — no auth, returns the static tool catalog.
* `tools/call` — **requires `Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000`**.

## Claude Desktop config

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "pickupbell": {
      "transport": { "type": "http", "url": "https://api.pickupbell.com/api/mcp" },
      "headers":   { "Authorization": "Bearer 550e8400-e29b-41d4-a716-446655440000" }
    }
  }
}
```

The Settings → API & MCP page in the dashboard pre-fills this snippet with your active key's prefix — copy it, paste the full secret in place of the prefix, restart Claude.

## Scopes apply identically

The key's scope set controls what each tool can do. A key without `leads:write` can call `list_leads` but not `update_lead`. The error comes back as a JSON-RPC error object:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32002,
    "message": "missing scope: leads:write",
    "data": { "httpStatus": 403 }
  }
}
```

## Scrubbing applies identically

Every tool output flows through the same PII scrubber as the REST path. If your key lacks `transcripts:read`, `get_call` returns the row with `transcript: null`.

## Full tool catalog

See [MCP tools](/mcp/tools) for every tool, its input schema, and the scope it requires.

## Why MCP?

Three reasons over the REST API:

1. **Discoverability.** Claude can `tools/list` and reason about what to do. No README needed.
2. **Input validation.** Each tool ships a JSON Schema input spec — the client can render forms and validate before calling.
3. **Reasoning over multi-step workflows.** "Close last week's AC-repair leads that already booked" is one sentence to the LLM — no code to write.

The REST API stays first-class for deterministic integrations (Zapier, homegrown pipelines). Use whichever fits.