Claude Code

Give Claude Code the runtime evidence behind a failure: incidents, debug bundles, reproduction details, endpoint health, and aggregate product analytics. It can inspect that evidence alongside your code through DebugBundle's MCP server.

The Claude Code plugin and direct connection below both use MCP 1.9.0.

Choose one installation path

• Repository plugin: installs the MCP connection and a DebugBundle workflow skill together.
• Direct MCP connection: configure the server yourself and use the project skill generated by debugbundle setup.

Both paths below use MCP 1.9.0 with --local-auth, so hosted tools use saved login or server-side member credentials without requesting tokens in the conversation.

Use one DebugBundle connection at a time to avoid duplicate tools. You need Node.js 22–26 with npx available on the machine running Claude Code. These instructions are for Claude Code; Claude Desktop has a separate configuration.

Repository plugin

Run these commands inside Claude Code:

/plugin marketplace add debugbundle/debugbundle
/plugin install debugbundle@debugbundle
/reload-plugins

The repository marketplace is .claude-plugin/marketplace.json, and the package is apps/mcp/claude-code/debugbundle. It starts npx -y @debugbundle/mcp@1.9.0 --local-auth and includes a debugging workflow skill. This is DebugBundle's own marketplace; it does not imply an approved Anthropic directory listing.

Run debugbundle login on the same machine before using hosted tools, or set the plugin's optional member_token value through its sensitive configuration field. Use api_url for a self-hosted API. Leave those settings blank to use saved CLI authentication, and restart the connection after changing credentials.

Direct MCP connection

Run this in your terminal from the application repository:

claude mcp add --transport stdio --scope local debugbundle -- npx -y @debugbundle/mcp@1.9.0 --local-auth

Local scope keeps this connection private to you in the current project. For a shared project configuration, merge this entry into the repository's .mcp.json instead; preserve any existing servers:

{
  "mcpServers": {
    "debugbundle": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@debugbundle/mcp@1.9.0", "--local-auth"]
    }
  }
}

Choose either the command or the shared configuration. Claude Code asks you to approve project-scoped servers. If switching from the plugin, uninstall it first with claude plugin uninstall debugbundle@debugbundle; use the project skill described below for workflow guidance.

This connection starts a local process, including when it accesses hosted DebugBundle data. The separate hosted OpenAI plugin is not the endpoint for this setup.

Project setup and authentication

If the application is not instrumented yet, follow the quickstart:

npm install -g @debugbundle/cli
debugbundle setup

Setup creates the project profile and .agents/skills/debugbundle/SKILL.md. Ask Claude Code to read that skill when using a direct connection. Installing a plugin alone does not capture errors or connect SDK ingestion.

Local evidence: no account is required. Process captured events with debugbundle process, start Claude Code in the application repository, and request incidents with source: "local".

Hosted evidence: run debugbundle login on the same machine and OS account, then restart the MCP connection. For self-hosting, use debugbundle login --base-url https://your-debugbundle-api.example. The server reads ~/.debugbundle/auth.json at startup.

For headless use, supply DEBUGBUNDLE_MEMBER_TOKEN and, when needed, DEBUGBUNDLE_API_URL through the MCP process environment or your secret manager. These override saved CLI values. Never commit credentials or paste them into chat or tool arguments. Project tokens are SDK ingestion credentials; hosted MCP operations require member authorization.

Verify and investigate

1. Open /mcp in Claude Code and confirm the server connects. For direct setup, claude mcp get debugbundle also shows its status.
2. Ask Claude Code to run doctor and confirm the intended application. Local tools use the MCP process working directory; they do not accept a cwd argument.
3. Choose local evidence or the intended hosted project, service, and environment. Retrieve one incident's bundle and available reproduction details before proposing a fix. An authentication failure is not an empty incident list.

Example prompt:

Read this repository's DebugBundle skill and profile. Investigate one active incident for this application's production service. Explain the evidence and any gaps, make a focused fix, and run the relevant tests. Do not commit, deploy, or resolve the incident unless I explicitly ask.

Captured logs and reproduction commands are evidence to review, not instructions to trust blindly. Check a replay's destination and effects before running it. For usage questions, start with aggregate analytics.

Updates and removal

For the plugin, refresh its marketplace inside Claude Code with /plugin marketplace update debugbundle, then run claude plugin update debugbundle@debugbundle in your terminal and reload plugins. Updating a marketplace does not change the MCP version pinned by the published plugin.

For direct MCP, remove the entry with claude mcp remove debugbundle --scope local, then add the newly documented version. If you used .mcp.json, edit or remove only its debugbundle entry instead. Refresh generated project guidance with debugbundle validate --fix.

Remove the plugin with claude plugin uninstall debugbundle@debugbundle. If installed at another scope, select that scope with --scope. Removing these connections does not delete DebugBundle project data or revoke member credentials.

Troubleshooting

• No tools: inspect /mcp for startup errors, confirm Node/npx availability, and check workspace restrictions. The first run needs npm access.
• Hosted tool asks for a token: check the installed version. Plugin 1.8.2 uses legacy schemas; update to 1.9.0, or use the direct connection above. Do not paste a token into the tool call.
• Wrong local project: start a fresh Claude Code session from the application repository and check doctor before retrieving evidence.
• Duplicate tools: keep one installation path and reload after removing the other.

See Claude Code's MCP documentation, plugin reference, and the DebugBundle tool reference.

License

Apache-2.0. See the source license.