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 (5 tools)

list_agents, get_agent, enable_agent, disable_agent, get_agent_config

Full agent lifecycle — view status, enable or disable, and inspect configuration.

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.

Runtime Hosts (5 tools)

list_runtime_hosts, get_runtime_host_detail, discover_runtime_host, batch_add_runtime_host_instances, sync_runtime_host_sessions

Pair machines, discover Hermes / Claude Code / Codex / OpenClaw instances, batch-add connectors, and sync attach-mode sessions.

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 session sync

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

"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."

"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. Tokens are the same as the CLI — generate one from Settings > API Tokens in the web dashboard.

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.