MCP Server

Open in the app: API Keys

Overview

The Bread Crumbs MCP server exposes conversation, contact and reporting tools to external AI clients such as OpenAI Codex, Claude Desktop, Claude Code, and Cursor.

Use it when your AI assistant should read or act on Bread Crumbs data: search clients and conversations, send messages, tag contacts, assign conversations, run reports, and more.

Every request must include an Authorization credential (raw API key) and a workspace ID. You can find your workspace ID at Workspace settings.

Endpoint

Bread Crumbs registers the server under id breadcrumbs-tools. Prefer Streamable HTTP for all clients:

https://gateway.bcrumbs.net/api/mcp/breadcrumbs-tools/mcp

⚠️

Do not use the built-in SSE path (/api/mcp/breadcrumbs-tools/sse) for Claude or mcp-remote. Bread Crumbs allows only one SSE transport on the shared server and often fails with Already connected to a transport. Streamable HTTP is the supported path.

Authentication

Every MCP request must include:

Header / param	Required	Description
`Authorization`	`Yes`	Raw API key (preferred for MCP), e.g. `bcak_…`. Generate keys in the dashboard or via the API Keys API.
`x-workspace-id`	`Yes`	Numeric workspace ID. You can also pass `workspaceId` as a query parameter. Find it in the app under Workspace.
`x-client-id`	`Optional`	Client ID for client-scoped tools.
`x-conv-id`	`Optional`	Conversation ID for conversation-scoped tools.
`x-integration-id`	`Optional`	Integration (channel) ID for conversation-scoped tools.

Protected MCP traffic is rate-limited to 30 requests per minute per user / workspace.

Available tools

Tool ID	Description	Context needed
`add-message-tool`	`Send a text reply to the current conversation.`	workspace + conv + integration
`end-conversation-tool`	`End the current conversation.`	workspace + conv + integration
`handover-conversation`	`Hand over the conversation to a human agent.`	workspace + conv
`get-conversation`	`Get conversation metadata (status, assignee, tags, stage).`	workspace + conv
`get-conversation-messages`	`List messages for a conversation.`	workspace + conv (client optional)
`assign-conversation`	`Assign or reassign the conversation to an agent or AI.`	workspace + conv + integration
`patch-conversation`	`Update conversation stage or order/reference number.`	workspace + conv + integration
`search-clients`	`Search clients by phone, name, email, city, code, or tags.`	workspace only
`search-conversations`	Search conversations by client, assignee, status, tags, or integration. Returns `id`, `clientId`, and `integrationId` for follow-up tools.	workspace only
`tag-client`	`Add a tag to a client.`	workspace + client
`untag-client`	`Remove a tag from a client.`	workspace + client
`tag-conversation`	`Add a tag to a conversation.`	workspace + conv + integration
`untag-conversation`	`Remove a tag from a conversation.`	workspace + conv + integration
`list-tags`	`List available workspace tags.`	workspace only
`get-quick-replies`	`Fetch workspace quick-reply templates.`	workspace only
`reporting-tool`	`Fetch operational reports (conversations, agents, open need response).`	workspace only

Client setup

OpenAI Codex

Create an API key in the dashboard (or via the API Keys API).
Add the server to ~/.codex/config.toml.
Restart Codex / reload MCP servers.

Prefer sending the API key via a custom header (raw key, no Bearer):

[mcp_servers.breadcrumbs]
url = "https://gateway.bcrumbs.net/api/mcp/breadcrumbs-tools/mcp"
 
[mcp_servers.breadcrumbs.http_headers]
"Authorization" = "bcak_YOUR_API_KEY"
"x-workspace-id" = "12"

Or load the key from an environment variable:

[mcp_servers.breadcrumbs]
url = "https://gateway.bcrumbs.net/api/mcp/breadcrumbs-tools/mcp"
 
[mcp_servers.breadcrumbs.env_http_headers]
"Authorization" = "BC_API_KEY"
 
[mcp_servers.breadcrumbs.http_headers]
"x-workspace-id" = "12"

Claude Desktop

Claude Desktop’s Custom Connector UI only supports OAuth client id/secret. That path does not work with our API-key auth, and claude.ai web custom connectors have the same limitation.

For Desktop, use mcp-remote as a local stdio bridge with Streamable HTTP (--transport http-only).

Config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "breadcrumbs": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gateway.bcrumbs.net/api/mcp/breadcrumbs-tools/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_TOKEN}",
        "--header",
        "x-workspace-id:12"
      ],
      "env": {
        "AUTH_TOKEN": "bcak_YOUR_API_KEY"
      }
    }
  }
}

Then fully quit and reopen Claude Desktop.

⚠️

On some Claude Desktop builds, spaces inside --header args are mangled. Put the key in an env var and use Authorization:${AUTH_TOKEN} with no space after the colon.

Claude Code / Cursor

Use HTTP transport with headers in .mcp.json (Streamable HTTP):

{
  "mcpServers": {
    "breadcrumbs": {
      "type": "http",
      "url": "https://gateway.bcrumbs.net/api/mcp/breadcrumbs-tools/mcp",
      "headers": {
        "Authorization": "bcak_YOUR_API_KEY",
        "x-workspace-id": "12"
      }
    }
  }
}

Common errors

Symptom	Likely cause	Fix
`HTTP 401 — no authorization header`	Missing `Authorization`	Add raw API key.
`HTTP 401 — Unauthorized`	`Invalid/expired credential or wrong workspace`	Check key and `x-workspace-id`.
`HTTP 400 — Missing or invalid workspaceId`	`Missing/non-numeric workspace`	Set `x-workspace-id` (or `workspaceId` query).
`HTTP 403`	`Credential valid but not allowed for workspace`	Use a key/token with access to that workspace.
`HTTP 404`	Wrong path (e.g. `/api/mcp` without `/breadcrumbs-tools/mcp`)	Use `/api/mcp/breadcrumbs-tools/mcp`.
`HTTP 429`	`Rate limit (30 req/min per user/workspace/path)`	Retry after the window; reduce tool chatter.
`Already connected to a transport`	`SSE / shared Bread Crumbs SSE limit`	Use Streamable HTTP + `--transport http-only`.
`Claude Custom Connector asks for OAuth only`	`UI does not support API keys`	Use Desktop + `mcp-remote`, or Claude Code / Codex.

API Keys — generate and manage API keys
Conversations API — conversation data model
Messaging API — message types and sending
Tags API — tag types and usage
Custom AI integration — the inverse pattern (Bread Crumbs calls your AI endpoint)

Custom AI Embedded Inbox