Set up MCP for Claude and AI agents

Breadbox’s 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 in the admin dashboard. Breadbox API keys start with bb_.
Breadbox’s MCP endpoint is /<your-host>/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.

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. Custom connectors using remote MCP are available on Free (limited to one), Pro, Max, Team, and Enterprise plans.

Open Connectors

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.

Add a custom connector

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.

Approve and use

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.

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

Streamable HTTP
Stdio

Use when Breadbox is on another host or in Docker and you want to authenticate with a static API key.

{
  "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.

{
  "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

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.

CLI (recommended)
Project .mcp.json (Streamable HTTP)
Project .mcp.json (Stdio)

# 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.

{
  "mcpServers": {
    "breadbox": {
      "type": "http",
      "url": "https://your-breadbox-host/mcp",
      "headers": {
        "X-API-Key": "bb_your_api_key_here"
      }
    }
  }
}

{
  "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 (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) and the Developer mode guide.

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.

Enable Developer mode

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.

Create the Breadbox app

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.

Attach it in a chat

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.

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 <name> -- <command...>.

# 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:

[mcp_servers.breadbox]
url = "https://your-breadbox-host/mcp"
env_http_headers = { "X-API-Key" = "BREADBOX_API_KEY" }

For stdio against a local binary:

[mcp_servers.breadbox]
command = "breadbox"
args = ["mcp-stdio"]

Openclaw

Openclaw 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 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.

Streamable HTTP (recommended)
SSE
Stdio

Breadbox’s /mcp endpoint speaks Streamable HTTP. Pass transport and headers with your API key:

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:

openclaw mcp show breadbox --json

Use SSE transport if your Openclaw version does not support streamable-http:

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.

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:

{
  "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 backlog, and notify you via Slack or another connected channel — see Recurring workflows with Openclaw.

Manus

Manus 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.

Expose Breadbox over HTTPS

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.

Open Custom MCP Servers in Manus

In Manus, go to Settings → Integrations → Custom MCP Servers and click Add Server.

Fill in the server details

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.

Save and test

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.

Any other MCP client

Any agent that speaks MCP over Streamable HTTP can connect. Point it at /mcp and attach your API key:

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.

​Prerequisites

​Claude

​Connectors UI (desktop, web, mobile)

​Config file (Claude Desktop)

​Claude Code

​ChatGPT and Codex

​ChatGPT Custom apps (beta)

​Codex CLI

​Openclaw

​Manus

​Any other MCP client

​Connection URL reference

​Read-only vs. read-write

Prerequisites

Claude

Connectors UI (desktop, web, mobile)

Config file (Claude Desktop)

Claude Code

ChatGPT and Codex

ChatGPT Custom apps (beta)

Codex CLI

Openclaw

Manus

Any other MCP client

Connection URL reference

Read-only vs. read-write