DebugBundle MCP server

@debugbundle/mcp

Local artifact safety in 1.19.4

Retained bundle and reproduction paths must stay in their canonical local artifact directories. Unsafe metadata returns invalid_local_artifact_path without reading, rewriting or deleting unrelated files. Symlinked files/directories fail closed. Normal local stores and their existing size allowance are preserved; local state and processing writes use guarded atomic replacement. This supersedes earlier clients.

Cloud cache safety in 1.19.4

Upgrade to 1.19.4 for incident-ID validation before cloud requests and cache writes. Unsafe IDs return invalid_incident_id; UUIDs and existing opaque IDs remain supported. Cloud cache reads, writes and retention reject symbolic links; writes use guarded atomic replacement. This corrects a path traversal present in earlier clients.

Installation guidance in 1.19.4

Prefer one project per system across service repositories, reuse existing connections, and keep separate projects for different access or privacy policies. Inspect existing projects before first-time connect; name matching does not infer system membership.

Local correlation safety in 1.19.1

Trace correlation crosses services only within the same project and environment. If an older cache contains mixed retained source events, reads and incremental processing fail with local_incident_scope_mismatch. Preserve the local store, then explicitly rebuild from its retained event files using debugbundle process --preset <minimal|balanced|investigative> with the desired capture preset. This rebuild regenerates local incident/artifact state; it does not change cloud records or the retained event files.

Project/service consolidation 1.19.1

Add logical service context and checked project-merge preview, apply, status, verification, resume and cancellation. Existing identities, credentials and restricted scopes remain compatible. Merge apply requires a qualified compatible core 1.21.0 runtime and remains disabled by default.

Connected doctor diagnostics check API health and saved access-token authentication with a one-incident probe restricted to cloud_project_id. Missing or blank connected project scope fails before any request. Incident contents are discarded and are not included in the report. Local-only diagnostics make no cloud request.

Connected-workspace incident lists use the saved connection's cloud_project_id unless projectId is explicitly supplied. This also applies to source: "cloud" and every cloud page. An unusable connected project fails with invalid_local_connection_config before the list request; specify the intended project or repair the connection. Local evidence and unconnected account-wide member reads retain their existing behaviour.

MCP server for runtime error reporting, crash reporting, incident response, endpoint health checks, debug bundles, and product analytics. DebugBundle lets agents inspect customer-facing incidents, deterministic bundles, product-usage evidence, reproductions, probes, alerts, webhooks, projects, and setup state through the same management surface as the API and CLI. It is production debugging infrastructure, not a generic infrastructure-monitoring or observability platform.

Corrective update 1.18.3

Connected incident lists now retain their selected cloud project across all pages, including explicit cloud reads. Invalid connected scope fails before the list request. Tool names, schemas, access-token authentication and local evidence selection remain compatible. The coordinated OpenClaw plugin repairs native ESM loading and adds installed-host/runtime checks; marketplace security acceptance stays separate.

Install

Ordinary authenticated MCP includes account/project notification preferences, channel-specific pause/resume, and daily email scheduling with local time and IANA timezone. These tools use the same permissions and policies as the API and CLI; the hosted read-only and restricted catalogs remain unchanged. See the tool reference.

Run the stdio server directly with npm:

npx @debugbundle/mcp

Or install globally:

npm install -g @debugbundle/mcp
debugbundle-mcp

Supported Node.js versions: 22.x through 26.x.

MCP Client Config

{
  "mcpServers": {
    "debugbundle": {
      "command": "npx",
      "args": ["@debugbundle/mcp"]
    }
  }
}

Use npx -y @debugbundle/mcp in clients that require noninteractive package execution.

Install Matrix

Environment	Recommended path	Notes
Generic local MCP client	npx @debugbundle/mcp	stdio transport
Claude Desktop local MCP	local MCP server config	uses local machine auth/config
Claude Code plugin	/plugin marketplace add debugbundle/debugbundle	installs bundled MCP config and DebugBundle skill
Codex developer plugin	codex plugin add debugbundle-codex@debugbundle	repository marketplace; local MCP and workflow skill
Codex direct MCP	codex mcp add debugbundle -- npx -y @debugbundle/mcp@1.23.0 --local-auth	app, CLI, and IDE on the same host
Cursor	MCP config with npx @debugbundle/mcp	stdio transport
VS Code / GitHub MCP Registry	com.debugbundle/mcp	official registry metadata
OpenClaw / ClawHub	DebugBundle skill plus MCP config	use the published skill for workflow guidance
CI/headless agents	DEBUGBUNDLE_MEMBER_TOKEN	never use a project token
Self-hosted DebugBundle	DEBUGBUNDLE_API_URL plus access-token authentication	points the server at your API base URL

This package is the supported public local stdio path. The separate OpenAI Plugin uses an OAuth-protected read-only remote endpoint at https://mcp.debugbundle.com/mcp. Its review/publication process is independent and does not alter this package's catalog or authentication.

Local authentication profile

MCP 1.9.0 adds npx @debugbundle/mcp --local-auth. This opt-in profile removes bearerToken from tool schemas, rejects per-call credentials and unknown fields, and uses only the server's startup CLI/environment access-token authentication. Hosted tools that require an access token fail with mcp_tool_error:auth_state_missing before an API request when auth is absent; run debugbundle login on that host or configure the server environment and restart the connection. Local-only retrieval remains available without a token. The default invocation preserves the legacy schemas and explicit per-tool token precedence.

Codex

Codex can use the existing stdio server independently of the hosted OpenAI plugin. See the Codex developer package and Codex setup guide for the repository marketplace, direct configuration, authentication, verification, and removal. The repository plugin must be released on the default branch before GitHub installation works; local checkout installation is available for candidate validation.

Claude Desktop

In Claude Desktop, open Settings > Developer, edit the local MCP config, and add:

{
  "mcpServers": {
    "debugbundle": {
      "command": "npx",
      "args": ["-y", "@debugbundle/mcp"]
    }
  }
}

Run debugbundle login first to reuse local CLI auth state, or add DEBUGBUNDLE_MEMBER_TOKEN to the server environment for managed/headless use. Set DEBUGBUNDLE_API_URL only for self-hosted or non-default API hosts.

Claude Code Plugin

Claude Code users can add DebugBundle's first-party marketplace from this repository:

/plugin marketplace add debugbundle/debugbundle
/plugin install debugbundle@debugbundle

The plugin package lives at apps/mcp/claude-code/debugbundle and bundles a Claude Code skill. See the Claude Code setup guide for the plugin's pinned MCP version, direct MCP configuration, authentication, verification, updates, and removal. It is also structured for Claude community marketplace review; do not describe it as listed in claude-community until Anthropic accepts and publishes it.

Authentication

Mode	Use	Notes
CLI auth state	Local developer machines	Reuses ~/.debugbundle/auth.json when available.
DEBUGBUNDLE_MEMBER_TOKEN	Headless or marketplace-managed clients	Access tokens are for CLI/API/MCP read and management operations.
Per-tool bearerToken	Explicit advanced automation	Overrides default auth for that call only.
Project token	SDK ingestion only	Do not use project tokens for MCP retrieval or management.

What Agents Can Do

• Read public project acquisition/activation definitions and aggregate reports with list_analytics_flows and get_analytics_flow_report; owners/admins can manage them with save_analytics_flow and archive_analytics_flow. These developer tools use the same project authorization and flow services as API, CLI and web. The separate hosted OpenAI catalog is unchanged.

• List active incidents and fetch full incident context.

• Fetch deterministic debug bundles and reproduction artifacts.

• Discover observed filter choices with get_analytics_filter_options for an authorised project, period, granularity and service/environment. Bounded sets expose values and truncated, with approved custom keys and no generation quota. Empty/unavailable choices must not be replaced with invented defaults. This tool is ordinary MCP only; restricted agent/OpenAI catalogues stay unchanged.

• Query aggregate usage, routes, device/browser/OS/language segments, referrers, actions, funnels, and journey patterns without waiting for an analysis artifact through get_usage_summary, get_route_metrics, get_device_breakdown, get_action_metrics, get_funnel_analysis, and related reads.

• Inspect retained redacted journey samples, analytics opportunities, and generated AnalyticsBundles; request a bounded analysis artifact when aggregate metrics alone are insufficient.

• Read analytics settings before proposing privacy, retention, consent, capture, or approved custom-dimension changes; update them only with explicit owner/admin intent.

• List saved analytics funnels and, with owner/admin access, create, update, or archive reusable funnel definitions through list_saved_analytics_funnels, create_saved_analytics_funnel, update_saved_analytics_funnel, and archive_saved_analytics_funnel.

• Inspect hosted health checks, probes, alerts, webhooks, projects, members, billing, capture policy, and GitHub automation state.

• Run local and hosted verification through tools such as verify_local, verify_cloud, doctor, smoke, and analyze.

verify_app_event provides real SDK-driven app proof, matching the CLI's verify cloud --expect-app-event. Pass projectId and at least one of service, traceId, or requestId; environment, maxAgeMinutes, and authFilePath are optional. It reads existing incidents/bundles and never sends synthetic events. The existing verify_cloud schema and description remain unchanged. The new tool is available through ordinary and local-auth stdio MCP and its OpenClaw projection; hosted read-only and restricted agent catalogs remain unchanged.

• Resolve or reopen incidents after verification.

For analytics questions, use direct aggregate tools first and generate an AnalyticsBundle only when a bounded analysis needs a durable artifact. The product does not create one bundle per visit.

Troubleshooting

Symptom	Check
Node.js launch failure	Use Node.js 22.x through 26.x. Configure the client to use a supported node or npx runtime.
Missing local auth	Run debugbundle login, or set DEBUGBUNDLE_MEMBER_TOKEN for headless and managed clients.
Invalid token	Use a dbundle_mem_ access token. Project tokens are SDK ingestion-only credentials.
Wrong API host	Leave DEBUGBUNDLE_API_URL unset for DebugBundle Cloud; set it only for self-hosted or non-default API hosts.
Local repo not initialized	Run debugbundle setup before local-only diagnostics, local bundle analysis, or generated project-skill workflows.

Links

• Docs: https://debugbundle.com/docs/mcp
• Agent workflows: https://debugbundle.com/docs/agent-workflows
• LLM index: https://debugbundle.com/llms.txt
• MCP tool schema: https://debugbundle.com/schemas/mcp-tools.json
• OpenAI Plugin candidate: https://debugbundle.com/docs/mcp/openai-plugin
• Official MCP Registry metadata: https://github.com/debugbundle/debugbundle/blob/main/apps/mcp/server.json

Security And Trust

• Official MCP Registry name: com.debugbundle/mcp.
• Official npm package: @debugbundle/mcp.
• Source repository: https://github.com/debugbundle/debugbundle/tree/main/apps/mcp
• License: Apache-2.0.
• The server uses stdio transport and local process credentials. It does not include hidden hosted management auth.
• Public examples must use placeholders only; never paste real access tokens, project tokens, webhook secrets, or customer configuration into marketplace listings.

License

Apache-2.0.

disconnect_github_installation calls the existing organization-wide disconnect route. It requires the active organization's owner and removes repository assignments for all its projects, including cleanup after downgrade. It does not uninstall the App on GitHub. Install/reconnect uses the dashboard browser flow to retain the signed state cookie. The ordinary/local-auth catalog now contains 134 tools; the hosted 23-tool and restricted five-tool profiles remain unchanged.

test_webhook_event accepts all eight supported webhook events through the existing scoped test service. The legacy test_webhook schema remains verification-only. Both queue a signed synthetic envelope without creating real incidents or bundles.

Public status pages

get_public_status_page, list_public_status_page_options, save_public_status_page and preview_public_status_page manage owner-controlled publication through the same API as Project Health. Read the options, select checks explicitly and save {title, enabled, projects:[{project_id, check_ids}]}. A save with enabled: false unpublishes without changing the URL. Publish only on the owner's instruction: selected project/check names and aggregate availability become public; URLs and diagnostics stay private. New checks remain private. The hosted read-only and restricted-agent profiles do not expose publication tools. See the status-page guide.