MCP Server

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Streamable HTTP (remote deployment)

For containerized or remote deployments, use HTTP transport:

clawbutler-mcp --transport http --port 8080

Agents (7 tools)

list_agents, get_agent, get_agent_governance_view, enable_agent, disable_agent, set_agent_lifecycle, get_agent_config

Agent operations plus lifecycle transitions, governance summaries, and configuration inspection.

Cost & Budgets (4 tools)

get_cost_summary, get_cost_by_agent, get_cost_trend, list_budgets

Cost tracking with date ranges, per-agent breakdown, trend analysis, and budget monitoring.

Config Safety (5 tools)

list_config_snapshots, take_config_snapshot, diff_config_snapshots, preview_rollback, execute_rollback

Config versioning — browse snapshots, create manual save points, semantic diff, dry-run rollback, and execute rollback.

Audit & Activity (3 tools)

search_audit_events, get_audit_event, get_recent_activity

Audit trail with flexible filters and recent activity stream for investigation.

Connectors (4 tools)

list_connectors, get_connector_detail, test_connector, diagnose_connector

Gateway connector management — list, inspect, test connectivity, and run diagnostics.

Intelligence (4 tools)

get_root_cause_analysis, get_reliability_scores, get_agent_reliability, get_value_comparison

Root-cause analysis, reliability scoring, and value comparison.

Operations (6 tools)

get_killswitch_status, activate_killswitch, deactivate_killswitch, check_health, get_trust_status, get_dashboard

Kill switch, health checks, trust status, and dashboard KPI summary.

Runbooks (4 tools)

list_runbooks, get_runbook, execute_runbook, get_runbook_run

Runbook automation — browse, execute with inputs, and track one run timeline.

Governance (4 tools)

preview_policy_decision, get_runtime_host_card, preview_task_grant, record_governance_evidence

Preview policy and task-grant decisions, reuse stable RuntimeHostCard data, and record governance evidence without opening broader write surfaces.

Runtime Hosts (9 tools)

list_runtime_hosts, get_runtime_host_detail, get_runtime_host_governance_view, discover_runtime_host, batch_add_runtime_host_instances, sync_runtime_host_sessions, get_runtime_host_managed_state, list_runtime_host_managed_sessions, list_runtime_host_managed_permissions

Pair machines, discover Hermes / Claude Code / Codex / OpenClaw instances, preview governance, batch-add connectors, sync attach-mode sessions, and inspect managed runtime state / sessions / pending permissions.

Morning ops check

Ask your AI assistant to give you a morning briefing on your agent fleet.

"Check my ClawButler dashboard — how many agents are online,
what's today's cost, and any pending approvals?"

Cost investigation

Drill into a cost spike without leaving your editor.

"Show me cost by agent for the last 7 days.
Which agent had the highest spend?"

Emergency response

AI-assisted incident response with kill switch and audit trail.

"Agent coordinator is behaving unexpectedly.
Check its health, then activate the kill switch with reason
'unexpected behavior — investigating'."

Config rollback

Review and roll back a bad config change.

"List the last 5 config snapshots for agent coordinator.
Diff version 3 vs 4, then preview a rollback to version 3."

Audit investigation

Search audit events to trace who changed what and when.

"Search audit events for risk_level=high in the last 3 days.
Show me the full details of the most recent one."

Connector diagnosis

Diagnose a connectivity issue with your gateway.

"List my connectors. The OpenClaw gateway seems slow —
run a diagnosis on it and tell me what's wrong."

Runtime host discovery and managed inspection

Discover Hermes / Claude Code / Codex / OpenClaw instances on a paired machine, add only the ones you want governed, project attach-mode sessions into ClawButler, then inspect managed session summaries and pending permissions.

"List my runtime hosts. Discover the paired MacBook,
add the Codex and Claude Code instances as connectors,
then sync the latest attach-mode sessions for investigation,
show me the managed sessions on the Codex instance,
and list any pending managed permissions."

"Tool not found" or no tools appear in IDE

Ensure clawbutler-mcp is installed and the command path is correct. Run `uvx clawbutler-mcp --help` to verify. Check your IDE's MCP log for connection errors.

401 Unauthorized / authentication errors

Verify CLAWBUTLER_TOKEN is set correctly. For long-lived automation, create an org-bound service token via the API or `ap service-token create`; interactive user access tokens still work for short-lived use.

Connection refused / timeout

Check CLAWBUTLER_API_URL points to your running ClawButler instance. For self-hosted setups, ensure the API is accessible from the machine running the MCP server.

Tools work but return empty data

This usually means the API returned an empty data array — your instance may not have agents/costs/connectors configured yet. Try get_dashboard first to verify connectivity.

How to use with Docker / remote servers?

Use HTTP transport: `clawbutler-mcp --transport http --port 8080`. This starts a Streamable HTTP server that any MCP client can connect to over the network.