> ## Documentation Index > Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Set up MCP for Claude and AI agents > Connect Claude (Desktop, web, mobile), Claude Code, ChatGPT, Codex, Openclaw, Manus, and other MCP-compatible agents to your Breadbox instance. Breadbox's MCP server is ready as soon as your instance is running — there's nothing extra to install or start. You configure your AI client to point at Breadbox over Streamable HTTP (with an API key) or over stdio (when the `breadbox` binary is local). This page gathers the setup flow for each supported client. Client UIs move quickly. The configs below were verified against each vendor's current docs in late-2025 / early-2026 (source URLs are in HTML comments next to each section). If a screen name has changed by the time you read this, the underlying MCP config shape is almost always still valid. ## Prerequisites * A running Breadbox instance (local binary, Docker, or remote server). * An API key if you're connecting over HTTP — generate one from [API keys](/configuration/api-keys) in the admin dashboard. Breadbox API keys start with `bb_`. * Breadbox's MCP endpoint is `//mcp`. Remote clients require HTTPS. *** ## Claude Claude has two connection paths: the in-app **Connectors** UI (works across Desktop, web, and mobile, but only supports OAuth auth), and a **config file** flow for Claude Desktop specifically when you need static-header auth (the default Breadbox `X-API-Key` setup). Use whichever fits how your Breadbox is exposed. {/* Claude (Desktop / Web / Mobile) — unified UI */} {/* Verified: 2026-04 */} ### Connectors UI (desktop, web, mobile) Claude (Desktop, web at claude.ai, and mobile) adds remote MCP servers through its **Connectors** UI — no config file required. The same flow works across all three surfaces. Reference: [Use connectors to extend Claude's capabilities](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities#h_815337b08c). Custom connectors using remote MCP are available on **Free** (limited to one), **Pro**, **Max**, **Team**, and **Enterprise** plans. Go to **Customize → Connectors** in settings. From a chat you can also click the **+** in the lower-left (or type `/`), hover over **Connectors**, and pick **Manage connectors**. Click the **+** next to **Connectors** and choose **Add custom connector**. Fill in: * **Name**: `Breadbox` * **URL**: `https://your-breadbox-host/mcp` * **Advanced settings** (optional): OAuth Client ID and secret, only if you've put an OAuth proxy in front of Breadbox. Save. Start a new conversation, click the **+** in the composer, and attach the Breadbox connector. Claude prompts you to approve tool calls the first time each one runs. Team/Enterprise owners can restrict which Breadbox tools are allowed via **Tool permissions** (Always allow / Needs approval / Blocked) — Breadbox's read tools carry the `readOnlyHint` annotation so they can be distinguished from writes. The custom-connector dialog exposes a **URL** and optional **OAuth Client ID / secret** — it does **not** have a field for static HTTP headers. If your Breadbox is protected by a plain `X-API-Key` (the default), the UI path won't authenticate. Use the **Config file** flow below instead, or front Breadbox with an OAuth proxy. {/* Claude Desktop — config file */} {/* Verified: 2026-04 */} ### Config file (Claude Desktop) Edit Claude Desktop's config file directly when you want to attach a static auth header (like Breadbox's `X-API-Key`) or run in stdio mode against a local binary. The config file lives at: * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` Use when Breadbox is on another host or in Docker and you want to authenticate with a static API key. ```json theme={null} { "mcpServers": { "breadbox": { "type": "http", "url": "https://your-breadbox-host/mcp", "headers": { "X-API-Key": "bb_your_api_key_here" } } } } ``` Use when the `breadbox` binary is installed on the same machine. Stdio mode connects directly to Breadbox's database — no HTTP server, no API key. ```json theme={null} { "mcpServers": { "breadbox": { "type": "stdio", "command": "breadbox", "args": ["mcp-stdio"] } } } ``` The `breadbox` binary must be on your `PATH`, and the same `DATABASE_URL` / `ENCRYPTION_KEY` env vars that run `breadbox serve` must be visible to Claude Desktop. Restart Claude Desktop after saving. {/* Claude Code */} {/* Verified: 2026-04 */} ### Claude Code Claude Code has three scope options for MCP server config: | Scope | Where it's stored | Shared via git | | ------------------- | ----------------------------------------- | -------------- | | **Local** (default) | `~/.claude.json`, scoped to this project | No | | **Project** | `.mcp.json` in your project root | Yes | | **User** | `~/.claude.json`, applies to all projects | No | The easiest way to add Breadbox is with the `claude mcp add` CLI — it writes to the right file for the scope you pick. Choose project scope (`--scope project`) if you want the config committed alongside your code; local scope if you want it private. ```bash theme={null} # Remote Streamable HTTP with X-API-Key header claude mcp add --transport http --scope project --header "X-API-Key: bb_your_api_key_here" breadbox https://your-breadbox-host/mcp # Stdio against a local binary claude mcp add --transport stdio --scope project breadbox -- breadbox mcp-stdio ``` All flags (`--transport`, `--scope`, `--header`, `--env`) must appear **before** the server name. The `--` separator is only required for stdio, to divide the server name from the command and its args. ```json theme={null} { "mcpServers": { "breadbox": { "type": "http", "url": "https://your-breadbox-host/mcp", "headers": { "X-API-Key": "bb_your_api_key_here" } } } } ``` ```json theme={null} { "mcpServers": { "breadbox": { "type": "stdio", "command": "breadbox", "args": ["mcp-stdio"] } } } ``` *** ## ChatGPT and Codex OpenAI exposes MCP in two places: the **ChatGPT** web app (as "Custom apps" under Developer mode, currently in beta) and the **Codex CLI** (via `mcp_servers` in `config.toml`). ChatGPT's flow is UI-driven with OAuth-style auth; Codex is flexible and works with Breadbox's header-based API keys today. {/* ChatGPT Custom apps */} {/* https://developers.openai.com/api/docs/guides/developer-mode */} {/* ------------------------------------------------------------------ */} ### ChatGPT custom apps (beta) Custom MCP apps are available in ChatGPT on **Plus**, **Pro**, **Business**, **Enterprise**, and **Education** accounts on the web. Reference: [Developer mode and MCP apps in ChatGPT (Help Center)](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt-beta) and the [Developer mode guide](https://developers.openai.com/api/docs/guides/developer-mode). **Auth compatibility caveat.** ChatGPT's custom apps accept **OAuth**, **No Authentication**, or **Mixed Authentication** — the dialog does not accept static headers like `X-API-Key`. Breadbox today only authenticates via `X-API-Key`, so the ChatGPT path currently requires either (a) fronting Breadbox with an OAuth proxy, or (b) exposing `/mcp` with No Authentication behind network-level access control you trust. For a header-based flow, use **Codex CLI** below instead. In ChatGPT on the web, open **Settings → Apps → Advanced settings → Developer mode** and toggle it on. The **Create app** button only appears once Developer mode is enabled. Back in **Apps**, click **Create app** next to Advanced settings. Provide a name (`Breadbox`) and point it at your remote MCP server URL (`https://your-breadbox-host/mcp`). Choose the authentication mode your deployment supports — OAuth, No Auth, or Mixed. Open a new chat and attach the Breadbox app from the tools menu. ChatGPT respects tool `readOnlyHint` annotations — tools without that hint (Breadbox writes like `trigger_sync`, `update_transactions`, `submit_report`) will prompt for explicit confirmation before each call. ChatGPT Custom apps require HTTPS and a publicly reachable URL — no localhost / LAN-only setups. Expose Breadbox through a proper tunnel or reverse proxy first. See [Make Breadbox reachable from the internet](/installation/remote-hosting). {/* Codex CLI */} {/* https://developers.openai.com/codex/config-reference */} {/* ------------------------------------------------------------------ */} ### Codex CLI OpenAI's Codex CLI stores MCP config in `~/.codex/config.toml` (or project-scoped `.codex/config.toml` in a trusted project). Unlike ChatGPT's Custom apps, Codex accepts static HTTP headers, so Breadbox's `X-API-Key` auth works directly. You can also add a server with `codex mcp add -- `. ```toml theme={null} # Remote Streamable HTTP [mcp_servers.breadbox] url = "https://your-breadbox-host/mcp" http_headers = { "X-API-Key" = "bb_your_api_key_here" } startup_timeout_sec = 10 tool_timeout_sec = 60 ``` For environment-sourced keys, use `env_http_headers` instead of `http_headers`: ```toml theme={null} [mcp_servers.breadbox] url = "https://your-breadbox-host/mcp" env_http_headers = { "X-API-Key" = "BREADBOX_API_KEY" } ``` For stdio against a local binary: ```toml theme={null} [mcp_servers.breadbox] command = "breadbox" args = ["mcp-stdio"] ``` *** {/* Openclaw */} {/* https://docs.openclaw.ai */} {/* ------------------------------------------------------------------ */} ## Openclaw [Openclaw](https://openclaw.ai) is a persistent, VM-hosted autonomous agent platform. It runs continuously, routes conversations across messaging channels (Slack, Telegram, WhatsApp, Discord, and others), spawns sub-agents for parallelised work, and maintains session state across runs — a natural fit for recurring household financial workflows. By connecting Breadbox as an MCP server inside Openclaw, you get a permanent agent that can query your transactions, review the backlog, and notify you out-of-band without any per-session setup. See [Recurring workflows with Openclaw](/guides/openclaw-recurring-workflows) for scheduled review patterns. Openclaw's MCP registry is managed with the `openclaw mcp` CLI. Run these commands on the machine where your Openclaw gateway is installed. Openclaw stores MCP server definitions as JSON under `mcp.servers` in its config; use `openclaw mcp set` to register Breadbox. Breadbox's `/mcp` endpoint speaks Streamable HTTP. Pass `transport` and `headers` with your API key: ```bash theme={null} openclaw mcp set breadbox '{ "url": "https://your-breadbox-host/mcp", "transport": "streamable-http", "headers": { "X-API-Key": "bb_your_api_key_here" } }' ``` Verify the entry was saved: ```bash theme={null} openclaw mcp show breadbox --json ``` Use SSE transport if your Openclaw version does not support `streamable-http`: ```bash theme={null} openclaw mcp set breadbox '{ "url": "https://your-breadbox-host/mcp", "headers": { "X-API-Key": "bb_your_api_key_here" } }' ``` If the `breadbox` binary is installed on the same host as the Openclaw gateway, you can use stdio transport instead. No API key is required — stdio connects directly to the database. ```bash theme={null} openclaw mcp set breadbox '{ "command": "breadbox", "args": ["mcp-stdio"] }' ``` The `breadbox` binary must be on your `PATH`, and the same `DATABASE_URL` / `ENCRYPTION_KEY` env vars that run `breadbox serve` must be set in the Openclaw gateway's environment. If you prefer to edit the config file directly instead of using the CLI, the shape under `mcp.servers` is: ```json theme={null} { "mcp": { "servers": { "breadbox": { "url": "https://your-breadbox-host/mcp", "transport": "streamable-http", "headers": { "X-API-Key": "bb_your_api_key_here" } } } } } ``` Openclaw agents that hold a **full-access** Breadbox API key can trigger syncs, create rules, update transactions, and submit reports — all autonomously. Unless you have observed several correct review cycles and are confident in your agent prompts, generate a **read-only** API key for Openclaw first. You can always swap it for a full-access key once you trust the agent's behavior. For recurring scheduled review patterns — having Openclaw wake up on a cron, query the `needs-review` backlog, and notify you via Slack or another connected channel — see [Recurring workflows with Openclaw](/guides/openclaw-recurring-workflows). *** {/* Manus */} {/* #connecting-a-custom-mcp-server */} {/* ------------------------------------------------------------------ */} ## Manus [Manus](https://manus.im) connects to remote MCP servers through its Custom MCP Servers integration. You configure Breadbox's `/mcp` endpoint through Manus's UI — there's no JSON config file to edit. Full reference: [Manus — Connecting a Custom MCP Server](https://manus.im/docs/integrations/custom-mcp#connecting-a-custom-mcp-server). Manus only accepts MCP servers reachable over HTTPS, so your Breadbox instance needs a public URL with TLS. If you're running locally, set that up first — see [Make Breadbox reachable from the internet](/installation/remote-hosting). In Manus, go to **Settings → Integrations → Custom MCP Servers** and click **Add Server**. * **Server name**: `Breadbox` (or whatever label makes sense to you). * **Server URL**: `https://your-breadbox-host/mcp` * **Authentication**: choose the header / API-key option and set: * Header name: `X-API-Key` * Header value: your Breadbox API key (`bb_...`) — generate one from **Settings → API Keys** in the admin dashboard. Manus supports API keys, Bearer tokens, OAuth tokens, and other credentials; Breadbox today authenticates with a header, so the API-key flow is the supported path. Manus verifies it can reach the server and lists the tools Breadbox exposes. Once the server shows as connected, Breadbox's tools appear in Manus's available integrations and become callable from any Manus task. OAuth-over-MCP between Breadbox and Manus hasn't been validated end-to-end yet. For now, header-based `X-API-Key` auth is the recommended path. If you test OAuth and it works, please open an issue so we can update these docs. *** {/* Generic / any MCP-compatible agent */} ## Any other MCP client Any agent that speaks MCP over Streamable HTTP can connect. Point it at `/mcp` and attach your API key: ```text theme={null} URL: https://your-breadbox-host/mcp Header: X-API-Key: bb_your_api_key_here ``` The endpoint handles the Streamable HTTP verbs: * `POST /mcp` — JSON-RPC requests * `GET /mcp` — SSE stream (supports session resumption) * `DELETE /mcp` — terminates the session *** ## Connection URL reference | Deployment | Transport | URL or command | | ---------------------- | --------- | -------------------------------- | | Docker Compose (local) | HTTP | `http://localhost:8080/mcp` | | Remote server | HTTP | `https://your-breadbox-host/mcp` | | Local binary | Stdio | `breadbox mcp-stdio` | *** ## Read-only vs. read-write API keys have a scope that controls what the connected agent can do. A **read-only** key gives the agent access to all query tools — listing accounts, searching transactions, checking sync status — but prevents it from triggering syncs or submitting reports. A **full-access** key allows the agent to trigger manual syncs and submit reports in addition to reading data. For most analysis and Q\&A use cases, a read-only key is sufficient and limits what the agent can affect. Use a full-access key only when you want the agent to trigger syncs or submit reports on your behalf. Stdio mode always has full access because it connects directly to the database.