Connect an AI client with MCP

Default Hosted Path

Start from your own repo or agent console. Discover Breakdown through public metadata, create a durable MCP token from Settings under MCP Access, or create a setup session that a signed-in human approves in the browser. Both paths produce a bdk_... token for the hosted MCP endpoint. Do not clone the Breakdown repo for normal service usage.

Clone or sparse-install this repository only when you are contributing to Breakdown, self-hosting it, or testing Codex plugin packaging.

Remote MCP Quickstart

1. Read GET /api or GET /api/integrations/headless-onboarding for machine-readable setup metadata.
2. Create a durable MCP token from Settings under MCP Access, or create an agent setup session.
3. For setup sessions, open the returned approval URL while signed in to Breakdown.
4. Verify the setup code and approve the requested scopes.
5. Have the agent exchange the setup secret for the scoped bdk_... token.
6. Run diagnose_breakdown_setup or GET /api/integrations/codex/diagnostics to verify token, scopes, and external-evaluator tool readiness.
7. Configure your MCP client with https://www.breakdown.sh/api/mcp and an Authorization: Bearer bdk_... header.
8. Ask the client to list Breakdown tools or list your graphs. A successful connection should expose tools such as list_graphs, get_graph, and create_external_run.

Create A Durable Client Connection

For persistent clients, create a named client connection in Settings, copy the raw bdk_... credential once, and store it in the client or launcher secret store. The token remains valid until revoked, rotated, or until its optional expiry.

The settings flow includes client-specific snippets for Codex, Claude, Cursor, OpenAI API, and generic MCP clients. Prefer Authorization: Bearer bdk_... withhttps://www.breakdown.sh/api/mcp. A full URL fallback with ?access_token=... is available for clients that cannot set headers, but it is easier to leak through logs and history.

Create And Approve A Setup Session

curl https://www.breakdown.sh/api/integrations/agent-setup-sessions \
  -H "Content-Type: application/json" \
  -d '{"clientName":"Codex","providerName":"OpenAI"}'

The create response includes an approval URL, setup code, exchange URL, and exchange secret. The user opens the approval URL in a signed-in browser, verifies the code, and approves the requested scopes. The agent then exchanges the approved setup secret:

curl "$EXCHANGE_URL" \
  -H "Content-Type: application/json" \
  -d "{\"exchangeSecret\":\"$EXCHANGE_SECRET\"}"

The exchange response includes the raw token once, the MCP URL, the headless REST base URL, and an authorization header value. The setup session is short-lived, but the exchanged token is durable until revoked, rotated, or until its optional expiry.

Configure A Client

Clients that read MCP server configuration usually need a URL plus an environment variable containing the token.

[mcp_servers.breakdown]
url = "https://www.breakdown.sh/api/mcp"
bearer_token_env_var = "BREAKDOWN_API_TOKEN"

Then set BREAKDOWN_API_TOKEN to the durable bdk_... token before starting the client.

For Codex Desktop fallback setup, the MCP server reference belongs in ~/.codex/config.toml on macOS/Linux or %USERPROFILE%\.codex\config.toml on Windows. Do not put the raw token in that file; store it in the OS user environment.

On macOS, persist the token for GUI-launched Codex Desktop with ~/Library/LaunchAgents/sh.breakdown.codex-env.plist, then quit and reopen Codex Desktop.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>sh.breakdown.codex-env</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/launchctl</string>
    <string>setenv</string>
    <string>BREAKDOWN_API_TOKEN</string>
    <string>bdk_your_token_here</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/sh.breakdown.codex-env.plist 2>/dev/null || true
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/sh.breakdown.codex-env.plist

On Linux desktops that use the systemd user environment, persist the token with ~/.config/environment.d/breakdown-codex.conf, then log out and back in before launching Codex. For terminal-launched Codex CLI sessions, exporting BREAKDOWN_API_TOKEN in that shell also works for that process tree.

BREAKDOWN_API_TOKEN=bdk_your_token_here

On Windows, the persistent location is HKEY_CURRENT_USER\Environment, value name BREAKDOWN_API_TOKEN. Set it from PowerShell, then quit and reopen Codex Desktop. If Codex still cannot see it, sign out and back in.

[Environment]::SetEnvironmentVariable('BREAKDOWN_API_TOKEN', 'bdk_your_token_here', 'User')

curl https://www.breakdown.sh/api/mcp \
  -H "Authorization: Bearer $BREAKDOWN_API_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Release-Test Token

Pre-merge plugin smoke tests should use a durable release-test token instead of a one-time setup session. In Settings under MCP Access, use Release Testing to create or rotate a token with graphs:read, graphs:write, runs:external_execute, and runs:write_results.

Copy the raw token once and store it as BREAKDOWN_RELEASE_TEST_TOKEN in GitHub Actions or the agent runtime secret store. Release-test tokens identify their purpose in Settings, show last-used metadata, and can be rotated or revoked without accepting another approval URL.

REST And Bootstrap Metadata

MCP clients and agents can also discover integration metadata at /api, /.well-known/ai-plugin.json, /openapi.json, and /api/integrations/headless-onboarding. The headless REST API lives under /api/headless and uses the same bearer tokens and scopes.

curl https://www.breakdown.sh/api/headless/graphs \
  -H "Authorization: Bearer $BREAKDOWN_API_TOKEN" \
  -H "Accept: application/json"

Scopes

Available Tools

MCP tools are grouped around graph editing, workflow execution, and external evaluator runs where the host client performs each step with its own connectors.

External Evaluator Runs

External-evaluator mode lets the MCP client keep the model work in its own environment while Breakdown stores the graph, step state, outputs, citations, and blocked data gaps.

1. Create or import a graph.
2. Create an external run for that graph.
3. Claim the next runnable work packet with get_next_step.
4. Use the available host-client tools to do the work.
5. Submit the result with citations, or mark the step blocked.
6. Finalize the run when steps are submitted or intentionally blocked.

Safety And Current Data

• Tokens are scoped and can be revoked from Settings.
• Raw tokens are shown once and stored by Breakdown only as hashes.
• Destructive tools advertise destructive annotations and confirmation text.
• Clients should confirm before deleting graphs, replacing imports, applying destructive patches, or cancelling runs.
• Current-data or stock-analysis steps depend on host-agent tools such as web search, financial data, workspace files, or other connectors. If the host lacks the required tool, mark the step blocked instead of fabricating data.

Troubleshooting

Run diagnose_breakdown_setup from MCP or call GET /api/integrations/codex/diagnostics for a machine-readable setup state. Missing, invalid, revoked, expired, and under-scoped tokens are reported separately.

401 Missing bearer token means the request reached Breakdown without an bearer token. Create a durable token from Settings under MCP Access, or create and approve a setup session, exchange it for a bdk_... token, and persist it before retrying. It does not mean the agent should clone this repository.

403 Missing required scope means the token is valid but lacks the scope needed for that tool or route. Create a new token with the minimum additional scope needed.

Advanced Local Or Self-Hosted Use

Use local endpoints only when you are developing Breakdown, testing a self-hosted deployment, or validating Codex plugin packaging.

[mcp_servers.breakdown]
url = "http://localhost:3000/api/mcp"
bearer_token_env_var = "BREAKDOWN_API_TOKEN"

For local desktop clients that require stdio MCP, build and run the bundled MCP package from a Breakdown checkout:

{
  "mcpServers": {
    "breakdown": {
      "command": "node",
      "args": ["/absolute/path/to/breakdown.sh/packages/breakdown-mcp/dist/index.js"],
      "env": {
        "BREAKDOWN_BASE_URL": "https://www.breakdown.sh",
        "BREAKDOWN_API_TOKEN": "bdk_your_token_here"
      }
    }
  }
}

For Codex plugin-specific setup, see Codex Plugin.