Codex

Give Codex runtime error reports, incidents, deterministic debug bundles, reproductions, endpoint health, and product analytics while it works in your repository.

This developer integration uses the existing @debugbundle/mcp stdio server with the opt-in --local-auth profile, including authorized management tools. This profile removes per-tool credential arguments and uses the server's saved CLI login or explicitly forwarded environment. MCP 1.9.0 is the minimum version; older releases can reject hosted calls before applying saved auth. It is separate from the read-only OpenAI plugin for ChatGPT and Codex, which is not publicly installable yet. No hosted OAuth change is required for the developer integration.

Choose one installation path

• Codex app or CLI: install the repository plugin to get MCP and the bundled workflow skill together.
• Codex IDE extension, or clients without repository plugins: configure MCP directly and use the project skill generated by debugbundle setup.

Use one developer MCP connection per Codex host. If you already configured DebugBundle directly, remove that entry with codex mcp remove debugbundle before installing the plugin. This removes only the Codex connection, not your DebugBundle data or CLI login. Keep an existing hosted read-only connection when needed, but choose the intended connection explicitly for each task.

Prerequisites: Node.js 22–26 with npx available on the Codex host, and a current Codex client. The commands below use codex plugin add; check codex plugin --help if an older client differs. Direct MCP configuration is also available through the client's MCP settings.

Repository plugin

After MCP 1.9.0 is published to npm and this package is released on the repository's default branch:

codex plugin marketplace add debugbundle/debugbundle
codex plugin add debugbundle-codex@debugbundle

For a checkout containing this package, add the absolute checkout path instead of the GitHub source (the pinned MCP version must still be published or installed locally):

codex plugin marketplace add /absolute/path/to/debugbundle
codex plugin add debugbundle-codex@debugbundle

The marketplace is .agents/plugins/marketplace.json; its package is plugins/debugbundle-codex. This repository marketplace is a distribution source, not an OpenAI directory approval. The plugin pins @debugbundle/mcp@1.9.0 with --local-auth and includes no credentials, custom transport, background hooks, or hosted app mapping.

Start a fresh Codex conversation after installation. In the app, open Plugins and select the DebugBundle marketplace to inspect the installed package. In the CLI, codex plugin list --marketplace debugbundle shows its state; /mcp shows the connected server. A managed workspace may restrict repository sources or tool access.

Direct MCP connection

codex mcp add debugbundle -- npx -y @debugbundle/mcp@1.9.0 --local-auth

Equivalent entry in ~/.codex/config.toml, or .codex/config.toml for a trusted project:

[mcp_servers.debugbundle]
command = "npx"
args = ["-y", "@debugbundle/mcp@1.9.0", "--local-auth"]

The app, CLI, and IDE extension share this configuration when they use the same Codex host. This is a local process connection; do not substitute the hosted OpenAI endpoint or run codex mcp login debugbundle for this path.

Project setup and authentication

For a project that has not been instrumented yet, install the DebugBundle CLI and run setup from its repository:

npm install -g @debugbundle/cli
debugbundle setup

Setup creates .debugbundle/profile.json, the project workflow at .agents/skills/debugbundle/SKILL.md, and the managed AGENTS.md instructions where applicable. Review the generated profile and SDK setup before using it. Installing the Codex plugin alone does not instrument an application or connect it to cloud ingestion.

Local-only: no DebugBundle account is required. Use debugbundle process to process captured local events, then have Codex call list_incidents with source: "local" after starting Codex in the application repository. An empty list before capture is expected.

Hosted or self-hosted: authenticate on the machine and OS account where the MCP process runs:

debugbundle login

For self-hosting, use debugbundle login --base-url https://your-debugbundle-api.example so the CLI auth state records the intended API. The server loads ~/.debugbundle/auth.json at startup; restart its connection after login, token rotation, or changing the API host. Connecting SDK ingestion uses debugbundle connect separately.

For headless direct MCP setups, add the following names to the same server table and supply their values through the Codex process environment or a secret manager:

env_vars = ["DEBUGBUNDLE_MEMBER_TOKEN", "DEBUGBUNDLE_API_URL"]

DEBUGBUNDLE_API_URL is optional for the default hosted API. Environment values override the stored CLI auth values. Do not commit credentials or put tokens into CLI command arguments, skills, chat messages, or MCP tool arguments. Project tokens are SDK write-only ingestion credentials; hosted MCP operations require member authorization. The repository plugin's default path uses the existing CLI login; use the direct configuration above when explicit environment forwarding is required.

Verify and investigate

1. Start a fresh conversation in the intended repository and inspect /mcp. For direct configuration, codex mcp list also confirms the saved entry; plugin servers are managed under Plugins.
2. Start Codex in the application repository and ask it to use doctor. MCP tools use the server process working directory; they do not accept a cwd argument.
3. For local evidence, list incidents with source: "local". For hosted evidence, identify the intended project and list its incidents with source: "cloud". Missing authentication or denied access is not an empty project.
4. Retrieve one incident's context, bundle, and reproduction. Preserve explicit pending, missing, or failed artifact states.
5. Make a focused code change and run the repository's tests. Review reproduction commands and their effects before execution. Deployment, synthetic traffic, probes, incident resolution, and other production changes require authorization for those actions.

Example prompt:

Read this repository's DebugBundle skill and profile. Investigate the latest active incident for this project's production service using the developer MCP connection. Explain the evidence, add a regression, and propose a tested fix. Report separately what was tested locally and what still needs live verification.

For an existing local issue, explicitly request local evidence and provide the repository path. Start product-usage questions with aggregate analytics; generate an AnalyticsBundle only when an authorized, bounded analysis needs a durable artifact.

Updates and removal

For a GitHub marketplace, refresh the repository and reinstall the package, then start a fresh conversation:

codex plugin marketplace upgrade debugbundle
codex plugin add debugbundle-codex@debugbundle

For a local-path marketplace, update the checkout and rerun only codex plugin add; marketplace upgrade applies to Git sources.

For direct MCP, rerun the add command with the newly documented pinned MCP version. For generated project skills, debugbundle validate --fix refreshes managed guidance while preserving the reviewed profile.

Remove the developer plugin:

codex plugin remove debugbundle-codex@debugbundle

If you no longer use this marketplace, remove its source with codex plugin marketplace remove debugbundle. Remove a direct connection with codex mcp remove debugbundle. These operations do not delete project data, revoke member tokens, or uninstall the separate OpenAI plugin.

Troubleshooting

• No tools: check the selected Codex host, Node/npx availability, plugin enablement, workspace policy, and /mcp startup errors. The first run downloads the pinned npm package and needs registry access.
• Authentication fails after login: restart the MCP connection and confirm login happened on the same host and OS account. Never paste the auth file into chat.
• Wrong or empty local project: start a fresh session in the application directory and explicitly choose source: "local". For direct MCP, set cwd = "/absolute/path/to/application" in its server table when the host starts it elsewhere.
• Duplicate tools: keep either the developer plugin or direct stdio registration. The hosted OpenAI connection is a separate, explicitly read-only surface.
• A write tool is missing: check which connection is active. Never weaken the hosted OAuth boundary or switch credentials to bypass an access restriction.

See Codex MCP documentation, OpenAI plugin packaging, and the DebugBundle MCP reference.

License

Apache-2.0. See the source license.