MCP Server
Open in the app: API Keys
Overview
The Bread Crumbs MCP server exposes conversation, contact, reporting and knowledge base 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/mcpDo 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. |
x-workspace-id | Yes | Numeric workspace ID. You can also pass |
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 | IDs in tool input? |
|---|---|---|---|
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 | |
list-knowledge | List or search the Q&A entries in the workspace knowledge base. With `query`, returns the closest entry in meaning first, then entries containing the text; without it, the newest entries. Returns the `qaId` for the tools below. | workspace only | |
add-knowledge | Add a question and answer to the workspace knowledge base that the AI agent uses. Creates a published entry on the Crumby → Q&A page. Refused when a similar question already exists (its `qaId` is returned). Owner/Admin only. | workspace only | |
update-knowledge | Change the question and/or answer of a Q&A. Published entries are re-embedded so the AI agent uses the new text. Owner/Admin only. | workspace only | |
remove-knowledge | Permanently delete a Q&A from the knowledge base. Owner/Admin only. | workspace only | |
list-sources | List the source documents (files and text snippets) in the knowledge base, newest first, filtered by name or type. | workspace only | |
read-text-source | Read the full text of a text source (MD, TXT). | workspace only | |
add-text-source | Add a Markdown document as a text source, like a text snippet on the Crumby → Sources page. Refused when a source with a similar name exists. Owner/Admin only. | workspace only | |
update-text-source | Replace the full text of a text source (MD, TXT) and re-process it. Owner/Admin only. | workspace only | |
remove-source | Permanently delete a source of any type: its file, vectors and record. Owner/Admin only. | workspace only |
The tools that add, update or remove knowledge (add-knowledge, update-knowledge, remove-knowledge, add-text-source, update-text-source, remove-source) need Owner or Admin access: a workspace API key, an agent API key with the Owner or Admin role, or an Owner or Admin user token.
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 |
HTTP 400 — Missing or invalid workspaceId | Missing/non-numeric workspace | Set |
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 |
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 + |
Claude Custom Connector asks for OAuth only | UI does not support API keys | Use Desktop + |
Related docs
- 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)