Getting Started

Default Path For Coding Agents

Breakdown is a hosted reasoning workflow service for agents running in other codebases. Agents should use a durable scoped bdk_... token from MCP Access, or create a short-lived approval session that exchanges into the same token type, then connect to the hosted MCP or REST APIs.

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

Quickstart

1. Start in your own repo, terminal, or agent console.
2. Read public discovery metadata from GET /api or GET /api/integrations/headless-onboarding.
3. Use a durable connection from MCP Client Connections in /settings, or create an agent setup session.
4. For setup sessions, ask the signed-in human to open the approval URL and verify the setup code.
5. After approval, exchange the setup secret for the scoped bdk_... token.
6. Persist the token in the host client or user-level launcher secret store that starts the agent.
7. Run diagnose_breakdown_setup or GET /api/integrations/codex/diagnostics to confirm token, scopes, and external-evaluator tool readiness.
8. Connect MCP at https://www.breakdown.sh/api/mcp or use REST under https://www.breakdown.sh/api/headless.
9. Persist graphs, reasoning steps, citations, blocked data gaps, and external-run state in Breakdown.

Create A Durable Client Connection

For persistent clients, sign in to Breakdown, open Settings, and use MCP Client Connections under MCP Access to create a named connection for the client. Copy the raw bdk_... token when it is shown; it is displayed once. The token remains valid until revoked, rotated, or until its optional expiry.

Create A Setup Session

A setup session lets an agent request access without asking the user to paste a raw token into the chat. The setup session expires quickly, but the exchanged token is a durable integration token unless an expiry was configured.

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

The response includes an approval URL, user code, exchange URL, and exchange secret. Open the approval URL while signed in to Breakdown, compare the setup code, and approve the requested scopes.

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

The exchange response returns the raw token once. Store it in the host client or user-level launcher secret store. BREAKDOWN_API_TOKEN is the supported environment variable for clients that cannot persist plugin auth directly.

For Codex Desktop fallback setup, put the MCP server reference in ~/.codex/config.toml on macOS/Linux or %USERPROFILE%\.codex\config.toml on Windows, and store the raw token in the OS user environment. On macOS, use ~/Library/LaunchAgents/sh.breakdown.codex-env.plist. On Linux, use ~/.config/environment.d/breakdown-codex.conf. On Windows, use HKEY_CURRENT_USER\Environment with value name BREAKDOWN_API_TOKEN.

Connect MCP

Use the hosted Streamable HTTP MCP endpoint with bearer-token authentication.

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

Use Headless REST

The headless REST API uses the same token and scopes as MCP.

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

External Evaluator Runs

Use external-evaluator mode when your host agent should do the model work with its own tools and connectors while Breakdown stores the workflow state. If a step needs current data, market data, web search, workspace files, or another connector the host agent does not have, mark the step blocked instead of fabricating an answer.

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 but did not include a token. Create a durable connection from MCP Client Connections in /settings, 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.

For MCP details, scopes, tool names, and REST metadata, see MCP Access. For contributor setup, see Local Development.