MCP Tools Reference

This page documents every tool the DebugBundle MCP server exposes. Hosted tools can authenticate with DEBUGBUNDLE_MEMBER_TOKEN in the MCP server environment, CLI auth state from ~/.debugbundle/auth.json, or an optional per-call bearerToken parameter. bearerToken is omitted from parameter tables below for brevity.

OpenAI read-only subset

The local stdio server below retains its complete backwards-compatible catalog. The separate OpenAI Plugin 1.0.2 production candidate exposes only these twenty-three read-only tools:

list_projects, list_services, list_incidents, get_incident, get_incident_context, get_bundle, get_reproduction, list_improvements, get_improvement, get_improvement_bundle, get_usage_summary, get_route_metrics, get_journey_patterns, get_device_breakdown, get_referrer_metrics, get_action_metrics, list_funnel_metrics, get_funnel_analysis, get_incident_impact, list_health_checks, get_health_check, list_health_check_results, and list_health_check_daily_rollups.

The OpenAI inputs omit local source selection and credential fields, reject unknown fields, and use OAuth resource scopes including debugbundle:analytics:read. Every operation is read-only and returns an allowlisted structured projection. Mutation, individual analytics journeys, custom analytics dimensions, local filesystem/setup, artifact generation, token, billing, alert, webhook, probe, notification, and member-management tools are excluded. See OpenAI Plugin for its exact auth and privacy boundary.

Project and service consolidation

Ordinary member-authenticated MCP 1.19.0 adds the following tools. The hosted OpenAI read-only subset retains its existing 23-tool contract. See Projects and services for the checked workflow. Mutations require normal per-call approval in OpenClaw.

Existing list_projects accepts optional projectId for one retained view; existing list_services accepts optional offset for environment pagination. Existing update_alert, update_webhook and update_github_dispatch_rule accept optional projectScope: "current_project" to explicitly snapshot the current whole-project scope; ordinary edits retain their old scope. For capture rules use update.project_scope: "current_project". activate_probe optionally accepts sdkProjectId, sdkService and sdkTokenId for explicit deployed credential/name selection; the default preserves the original signing identity. Existing required inputs, credential separation and hosted schemas remain unchanged.

Public Status Pages

Public status pages reuse recorded health data and never execute checks. Publication is opt-in, and selected project/check names become public. New checks remain private.

Each tool takes projectId. Save also takes settings: {title, enabled, projects: [{project_id, check_ids}]}, with the anchor project first. Options accepts separate cursor or check_project_id/check_cursor pagination. Use the normal member authentication; these tools are excluded from hosted OpenAI and restricted agent-read profiles. See publication setup and the generated schemas.

Setup & Diagnostics

doctor

Run a full connectivity and configuration check.

Returns a diagnostic report with pass/fail status for each check.

validate

Validate your local DebugBundle configuration files.

verify_local

Verify local-mode setup (CLI installed, log directory writable, parser available).

verify_cloud

Verify cloud connectivity (API reachable, token valid, project accessible) or actively prove hosted incident creation.

trigger4xxStatus succeeds only when the target project's capture policy promotes that status. It is mutually exclusive with trigger5xx.

verify_app_event

Wait for a real SDK-driven app incident and verify its hosted bundle. This additive tool preserves the existing verify_cloud contract and uses the same verifier and result shape as debugbundle verify cloud --expect-app-event --json.

Provide at least one nonblank service, traceId, or requestId. Synthetic trigger options and unknown fields are rejected. The tool never generates synthetic events; it reads existing incident and bundle evidence. It is available in ordinary and local-auth stdio MCP and as debugbundle_verify_app_event in OpenClaw, not the restricted hosted OpenAI connection or agent-read profile.

smoke

Run a quick smoke test that sends a test event and verifies end-to-end processing.

---

Incident Retrieval

list_incidents

List incidents for the active project.

get_incident

Get full details of a specific incident.

resolve_incident

Mark an incident as resolved.

resolve_incidents

Mark incidents as resolved in bulk.

reopen_incident

Reopen a previously resolved incident.

reopen_incidents

Reopen incidents in bulk.

get_bundle

Retrieve the debug bundle for an incident.

get_reproduction

Get the reproduction artifact for an incident.

Returns reproduction commands (cURL, HTTPie) and JSON specifications when available.

get_logs

Retrieve raw log entries associated with an incident.

---

AnalyticsBundle

Project flow tools are list_analytics_flows, save_analytics_flow, archive_analytics_flow, and get_analytics_flow_report. All accept projectId and member authentication; save takes definition, archive/report take flowKey, and report accepts window (7d, 30d, 90d, default 30d). Save/archive require owner/admin. The same public definitions and partial-coverage reports are available in the API and CLI, for any customer project. These tools are outside the separate hosted OpenAI read-only catalog.

Analytics tools require member authentication. Project tokens are write-only SDK credentials and cannot call these tools. Metric/detail operations remain project-scoped; only opportunity and bundle lists may omit projectId for an accessible organization-wide inventory.

Common metric options are projectId, last, from, to, granularity, service, environment, and limit where supported.

get_usage_summary

Return sessions, page views, active/new/returning visitors, exits, conversions, and standard aggregate breakdowns for a project.

get_route_metrics

Return aggregate route pageviews, unique sessions, entrances, exits, bounces, and incident-linked sessions.

get_device_breakdown

Return device type, browser, OS, and language aggregates.

get_referrer_metrics

Return referrer-domain and bounded UTM source/medium/campaign aggregates.

get_action_metrics

Return semantic action, conversion, and fixed journey-marker aggregates.

list_funnel_metrics

List funnel entered/completed/drop-off/conversion summaries for a project.

get_funnel_analysis

Returns deterministic ordered step metrics in addition to the aggregate funnel summary.

get_journey_patterns

Return aggregate route transitions, unique sessions, transition share, and bounded retained sample references.

list_analytics_journey_samples

get_analytics_journey_sample

Returns a redacted structured timeline, not a raw visit or video replay.

get_incident_impact

Returns exact correlation-backed affected sessions, routes, funnels, segments, journey references, conversion availability, and current incident-impact bundle state.

list_analytics_opportunities

projectId is optional. Omit it only for an accessible cross-project inventory. Optional filters include status, kind, service, environment, severity, bundle status, date bounds, cursor, and limit.

get_analytics_opportunity

Requires projectId and opportunityId; returns one aggregate-only opportunity and its current generated-bundle state.

list_analytics_bundles

projectId is optional for cross-project inventory. Optional filters include generation status, analysis kind, service, environment, date bounds, cursor, and limit.

generate_analytics_bundle

Returns pending/failed state or a completed deterministic artifact. It does not generate one bundle per visit.

get_analytics_bundle

Requires projectId and bundleGenerationId; returns the existing generation status or completed artifact without requesting another generation.

get_analytics_settings

Requires projectId. Owners/admins receive manage access mode; members receive preview.

update_analytics_settings

Requires owner/admin access plus projectId and an update object. Settings include enabled state, privacy, consent, capture toggles, sampling, retention, saved-funnel cap, and Team controlled custom dimensions.

list_saved_analytics_funnels

List active definitions for projectId. Members may read definitions.

create_saved_analytics_funnel

Requires owner/admin access, projectId, funnelKey, displayName, and 2-20 ordered unique steps containing step_key and display_name.

update_saved_analytics_funnel

Requires owner/admin access, projectId, funnelKey, and at least one of displayName or ordered steps.

archive_saved_analytics_funnel

Requires owner/admin access, projectId, and funnelKey. Archival removes the active definition but retains historical aggregate evidence.

---

Token Management

list_project_tokens

List project tokens (SDK/ingestion tokens).

create_project_token

Create a new project token for SDK ingestion.

Returns the token plaintext once — store it immediately. Use allowedOrigins only for public write-only project tokens intentionally embedded in static browser apps. Allowlisted tokens reject requests without a matching Origin, so do not reuse them for server SDKs or relay forwarding. This reduces normal browser-origin abuse but is not a secret boundary.

revoke_project_token

Revoke a project token.

list_member_tokens

List member tokens (CLI/API/MCP tokens).

create_member_token

Create a new member token.

Returns the token plaintext once — store it immediately.

revoke_member_token

Revoke a member token.

list_agent_tokens

List metadata for restricted agent credentials on one project. Requires project owner/admin access through the ordinary member-authenticated MCP connection; token plaintext is never returned by this list.

create_agent_token

Create a single-project, read-only agent credential. Issuance is disabled by default on the API until an operator completes the mixed-fleet migration gate. The plaintext credential is returned once; store it in a protected environment or the restricted CLI profile.

revoke_agent_token

Revoke a restricted agent credential for one project. Existing agent reads fail after revocation.

---

Webhook Management

list_webhooks

List configured webhook endpoints.

create_webhook

Create a new webhook endpoint.

update_webhook

Update an existing webhook.

delete_webhook

Delete a webhook endpoint.

test_webhook

Send a test delivery to a webhook endpoint.

test_webhook_event

Queue a signed synthetic test for any of the eight supported webhook events. This additive tool retains the legacy test_webhook verification-only schema. The test uses the existing synthetic envelope and does not create a real incident or bundle.

Requires member authentication and endpoint creator or owner/admin authority. The hosted OAuth and restricted agent-read profiles do not expose this mutation.

list_webhook_deliveries

List recent deliveries for a webhook.

retry_webhook_delivery

Retry a failed webhook delivery.

---

Alert Management

list_alerts

List configured alert rules.

list_alert_groups

List direct alert deliveries and email digests for one project. Results contain safe status, channel, timestamps, and incident counts without destination secrets or raw event payloads.

get_alert_group

Inspect one group's safe metadata and a page of member incident IDs. Use its returned cursor for the next member page.

create_alert

Create a new alert rule.

For conditionType: "severity_threshold", severityLifecycleScope: "both" notifies for matching new incidents and matching regressions. Non-threshold conditions ignore this field because their condition already defines the lifecycle event.

severityMin: "high" does not match low-confidence opaque browser-native captures by default: opaque window_error infers low, and opaque resource_error infers medium.

For channel: "webhook", the updated MCP client requests a signed rule. Its creation response reveals alert.signing_secret once. Store it in the receiver and verify the X-DebugBundle-Signature: sha256=<hex> HMAC over the exact request body. Older rules also receive a signature header after a private key is provisioned; rotate a rule to reveal a new key for receiver verification.

update_alert

Update an existing alert rule.

rotate_alert_webhook_secret

Rotate a custom alert-webhook signing secret. The new alert.signing_secret appears only in this response. Update the receiver before requiring the new signature. The existing update_alert tool schema remains unchanged.

delete_alert

Delete an alert rule.

---

Slack Destinations

list_slack_destinations

List connected Slack destinations for a project organization.

Saved destinations remain readable after a downgrade to Free so agents can inspect the paused setup before the owner upgrades again.

get_slack_connect_url

Return a browser URL for Slack OAuth and channel selection.

test_slack_destination

Send a test message to a connected Slack destination.

delete_slack_destination

Delete a connected Slack destination when no alert rule or weekly report still references it. This cleanup action remains available after downgrade.

---

Weekly Reports

list_weekly_reports

List available weekly reports.

get_weekly_report

Get a specific weekly report with full analysis.

generate_weekly_report

Trigger generation of a new weekly report.

configure_weekly_reports

Configure weekly report settings.

---

Services

list_services

List all services discovered from ingested events.

---

Projects

list_projects

List projects in the organization.

create_project

Create a new project.

update_project

Update an existing project.

delete_project

Delete a project and all associated data.

---

Health Checks

list_health_checks

List hosted health checks for a project, including current plan limits.

get_health_check

Get one hosted health check by id.

create_health_check

Create a hosted health check for a public HTTP endpoint.

update_health_check

Update a hosted health check. Use this to change thresholds, status expectations, labels, or enabled state.

delete_health_check

Delete a hosted health check.

test_health_check

Run a side-effect-free target test using the same validation and guarded request execution as saved checks. This does not create incidents, retained result rows, or rollups.

list_health_check_results

List recent execution results for one hosted health check.

list_health_check_daily_rollups

List retained per-day status history for one hosted health check.

---

Probes

activate_probe

Activate a remote debug probe on a project.

Returns the probe object including a one-time trigger_token.

list_active_probes

List active probes for a project.

Saved remote probe activations remain readable after a downgrade to Free so agents can inspect the paused setup before the owner upgrades again.

Probe deactivation remains available as cleanup after downgrade; new remote activation requires the project to return to Solo or Team.

deactivate_probe

Deactivate a probe.

---

Capture Policy

get_capture_policy

Get the resolved capture policy for a project.

update_capture_policy

Update the capture policy for a project.

---

Capture Rules

list_capture_rules

List project capture rules.

create_capture_rule

Create a project capture rule.

update_capture_rule

Update a project capture rule.

delete_capture_rule

Delete a project capture rule.

suggest_capture_rules_from_incident

Suggest capture rules from an incident bundle without changing project state.

create_capture_rule_from_incident_suggestion

Create a project capture rule from one of the incident suggestions.

---

Billing

billing_plan_change

Available in core 1.19.0 and published MCP package 1.18.0.

Inspect, preview, schedule or cancel a Team-to-Solo change at the next renewal on the existing subscription. Owner access is required. Purchased extra capacity is retained at Solo pricing; Team stays active until the effective date.

Present the preview's effective date, estimated monthly total, tax, retained capacity and loss of Team features, then obtain explicit confirmation before scheduling. Nothing is charged or refunded immediately. Retry an uncertain confirmed request with its original token; do not invent a new change or create another subscription. Cancel releases the pending change and keeps Team. This tool is part of the ordinary member-authenticated server, not the restricted read-only connection.

get_billing_summary

Get the billing summary for the organization.

start_trial

Start an eligible no-card trial for the organization.

increase_capacity

Add extra capacity units with prorated billing.

schedule_capacity_reduction

Schedule a capacity reduction at the end of the billing cycle.

cancel_capacity_reduction

Cancel a scheduled capacity reduction.

---

Members

list_project_members

List members for a project.

list_project_member_invites

List pending invites for a project.

invite_project_member

Invite a collaborator to a project.

cancel_project_member_invite

Cancel a pending invitation.

update_project_member_role

Update the role of a project member.

remove_project_member

Remove a member from a project.

---

Analysis

analyze

Run deep analysis on an incident, combining bundle data, logs, and reproduction artifacts.

Returns a structured analysis including root cause hypothesis, affected components, severity assessment, and suggested fixes.

GitHub installation cleanup

disconnect_github_installation

Disconnect the installation for the active organization and remove repository assignments across all its projects. Requires the organization owner; cleanup remains available after downgrade. The App stays installed on GitHub. Install/reconnect uses the project GitHub dashboard browser flow to preserve its signed state cookie.

Next Steps

• MCP Server — Overview and authentication
• MCP Workflows — Practical agent patterns

Notification preferences

The ordinary MCP catalog exposes get_notification_preferences, update_notification_preferences, pause_notifications, and resume_notifications. Common input is bearerToken, optional audience: "personal" | "shared" (default personal) and optional project UUID projectId. Local-auth mode supplies credentials through the existing profile.

Update takes update: { channels: { email: "daily" }, daily: { time: "09:00", timezone: "Europe/Ljubljana" } }. Pause takes pause: { channels: ["email"], until: null, allow_health_checks: false }; use a future UTC ISO timestamp instead of null for a timed pause. Resume takes resume: { channels: ["email"] }. Channel modes and authorization match the API.

These management operations are excluded from the hosted read-only OpenAI and restricted-agent profiles. OpenClaw treats new operations as optional tools.