Codex Plugin

Choose The Right Path

Do not clone the Breakdown repo just to use hosted Breakdown. Install the plugin from Git, or point your MCP client directly at the hosted endpoint.

Install The Public Plugin

Install the repo marketplace and plugin from Git. The sparse flags fetch only the marketplace manifest and plugin package.

codex plugin marketplace add alamorre/breakdown.sh --ref main --sparse .agents/plugins --sparse plugins/breakdown
codex plugin add breakdown@breakdown

For a tagged release, replace --ref main with the release tag. Start a new Codex thread after installing or updating so the plugin skills, prompts, assets, and MCP server config are loaded.

Package Contents

Recommended Hosted MCP Connection

Create a named Breakdown MCP connection once, copy the credential once, and store it in the client or launcher secret store that starts Codex. The resulting bdk_... token is durable until revoked, rotated, or until an optional expiry.

1. Sign in to Breakdown.
2. Open Settings and use MCP Client Connections under MCP Access.
3. Choose Codex, Claude, Cursor, OpenAI API, or Other to load the client-specific snippet.
4. Grant the minimum scopes needed for the workflow.
5. Copy the raw token when it is shown. It is displayed once.
6. Store it outside the repository in the user-level Codex/plugin secret store or launcher secret store that starts Codex Desktop.
7. Run diagnose_breakdown_setup and confirm state: "ready".

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

Set BREAKDOWN_API_TOKEN to the copied bdk_... token in the environment or secret store used by the MCP client. Do not store raw tokens in repo-local .codex/config.toml, committed files, issue comments, or chat. Revoke or rotate client tokens from Settings under MCP Access. Settings also shows last-used status and a full URL fallback with ?access_token=... for clients that cannot set headers; prefer bearer headers because URLs are easier to leak.

Agent-Native Setup Session

Use the approval-session path when an agent can start setup from inside the MCP client and the user can approve in the browser. The setup session is short-lived, but the exchanged bdk_... token is a normal integration token: it remains valid until revoked, rotated, or until its optional expiry.

1. Install the plugin from Git and start a new Codex thread.
2. Create an agent setup session at https://www.breakdown.sh/api/integrations/agent-setup-sessions.
3. Open the returned approval URL while signed in to Breakdown.
4. Verify the setup code and approve only the scopes needed for the session.
5. Exchange the setup secret for a scoped bdk_... token.
6. Persist the token in the user-level Codex or launcher secret store that starts Codex Desktop.
7. Run diagnose_breakdown_setup and confirm state: "ready".

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

If diagnose_breakdown_setup reports missing_token, create a durable MCP connection from Settings or create and approve an agent setup session. Do not treat missing_token as permission to simulate a Breakdown run outside Breakdown unless the user explicitly asks for that fallback.

Advanced Fallback: OS-Level Token Storage

Use these locations only when Codex cannot persist plugin authentication itself. Keep the Codex MCP server config in the user-level Codex config file and keep the raw token in the OS user environment.

Codex config file paths: ~/.codex/config.toml on macOS and Linux, or %USERPROFILE%\.codex\config.toml on Windows. The config should reference the environment variable, not the raw token.

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

On macOS, persist the token for GUI-launched Codex Desktop with this LaunchAgent file: ~/Library/LaunchAgents/sh.breakdown.codex-env.plist.

<?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, there is no plaintext file path for the user environment. 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')

Revoke plugin connections from Settings under MCP Client Connections. Revoked, missing, malformed, or unknown tokens are reported separately by diagnose_breakdown_setup and GET /api/integrations/codex/diagnostics.

Connection Check

Ask Codex to run diagnose_breakdown_setup after plugin setup. A ready response confirms the MCP server is loaded, the token is valid, the external-evaluator tools are present, and the token has the scopes needed for get_next_step, submit_step_result, and mark_step_blocked.

If diagnose_breakdown_setup is missing from the tool list, the plugin or MCP server is not loaded in the current Codex session. Start a new Codex thread after install or update and check that the Breakdown plugin is enabled.

curl https://www.breakdown.sh/api/integrations/codex/diagnostics   -H "Authorization: Bearer $BREAKDOWN_API_TOKEN"   -H "Accept: application/json"

Without a bearer token, the diagnostics endpoint returns state: "missing_token"so agents do not have to guess from a generic MCP failure.

Release-Test Authentication

Plugin release smoke tests should not depend on one-time approval URLs. Create or rotate a Release Testing token from Settings under MCP Access, then store the copied value as BREAKDOWN_RELEASE_TEST_TOKEN in GitHub Actions or the agent runtime secret store.

The release-test token is scoped to graphs:read, graphs:write, runs:external_execute, and runs:write_results. Settings shows its purpose, scopes, last-used time, and revoked state so it can be audited or rotated from a phone.

MCP Surface

The plugin exposes hosted MCP tools for graph editing, workflow execution, and external evaluator runs where Codex performs each step and writes results back.

Resources

Codex can also read graph resources for graph lists, graph detail, manifests, nodes, run status, external runs, and external step context.

Safety

Destructive tools advertise destructive annotations and confirmation metadata. Clients should still ask before deleting graphs, deleting nodes or edges, replacing imports, applying destructive patches, or cancelling active runs. Use apply_graph_patch with dryRun=true before applying graph mutations.

Verify

After installation, start a fresh Codex thread and ask it to run diagnose_breakdown_setup, then list Breakdown graphs. That exercises the Git marketplace package, persistent token availability, hosted MCP connection, tools/list, external-evaluator tool discovery, and a read-only graph path.

python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/breakdown
pnpm exec vitest run src/lib/mcp/codex-plugin-release.test.ts src/app/api/mcp/route.test.ts
pnpm lint
pnpm typecheck

Direct Hosted MCP

Use this path when a client does not need the packaged Codex plugin.

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

For the full setup-session flow, see MCP Access.

Local Or Self-Hosted Override

The committed plugin config always points at the hosted MCP endpoint. For local development, do not edit and commit plugins/breakdown/.mcp.json.

Prefer direct MCP config while developing the app:

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

For plugin packaging tests, create a throwaway copy of plugins/breakdown. Change that copy's .mcp.json to localhost, and install the throwaway marketplace entry.

Troubleshooting

diagnose_breakdown_setup is missing means the plugin or MCP server is not installed, enabled, or loaded in this Codex session. Install or enable the plugin and start a new Codex thread.

state: "missing_token" means the client reached Breakdown without an bearer token. Create a durable MCP connection token from Settings under MCP Access, or create and approve an agent setup session, then persist the resulting token in the user-level Codex or launcher secret store. If the client cannot persist plugin auth yet, set BREAKDOWN_API_TOKEN in the environment that starts Codex.

state: "invalid_token", state: "revoked_token", or state: "expired_token" means the token is present but cannot be used. Rotate or recreate the token from Settings under MCP Access.

403 Missing required scope means the token is valid but too narrow for the requested tool. Create a new token with the minimum additional scope needed. state: "missing_scope" lists the exact missing scopes.

If Codex cannot see the plugin after install or update, start a new thread so Codex reloads plugin skills and MCP server definitions.