dashclaw

@dashclaw/mcp-server

MCP server for DashClaw governance. Exposes 17 governance tools, 2 stdio-only support tools, and 3 read-only resources over Model Context Protocol: evaluate policy, record evidence, invoke registered capabilities, wait for approvals, and read the decision ledger. Works with Claude Code, Claude Desktop, Claude Managed Agents, and any MCP-compatible client.

The governance tools register only when DASHCLAW_URL and DASHCLAW_API_KEY are both set; without them the server registers nothing and warns on stderr if exactly one is present.

Quick Start

Claude Code / Cowork (stdio)

npx -y @dashclaw/mcp-server --url https://your-dashclaw.vercel.app --key oc_live_xxx --agent-id claude-code

Or add to your MCP config (.mcp.json for Claude Code, or claude mcp add):

{
  "mcpServers": {
    "dashclaw": {
      "command": "npx",
      "args": ["-y", "@dashclaw/mcp-server"],
      "env": {
        "DASHCLAW_URL": "https://your-dashclaw.vercel.app",
        "DASHCLAW_API_KEY": "oc_live_xxx",
        "DASHCLAW_AGENT_ID": "claude-code"
      }
    }
  }
}

Claude Desktop main chat: do not use stdio. Desktop runs local MCP servers on its bundled Node, which crashes this server. Use the OAuth custom connector instead — no local process, works in chat and Cowork.

About DASHCLAW_AGENT_ID: this is the name that shows up on /fleet, /decisions, and every other governance surface. If you omit it, the server auto-derives an agent_id from the MCP protocol's clientInfo.name (e.g. claude-ai for Claude Desktop, cursor-vscode for Cursor) so calls don't silently commingle with other agents — but a human-friendly name like claude-desktop is what you actually want for dashboard readability. Explicit configuration always wins over auto-derivation.

Claude Managed Agents (Streamable HTTP)

If you're running DashClaw, the MCP endpoint is built in at /api/mcp:

agent = client.beta.agents.create(
    name="Governed Agent",
    model="claude-sonnet-4-6",
    tools=[{"type": "agent_toolset_20260401"}],
    mcp_servers=[{
        "type": "url",
        "url": "https://your-dashclaw.vercel.app/api/mcp",
        "headers": {"x-api-key": "oc_live_xxx"},
        "name": "dashclaw"
    }],
)

Claude Desktop

Use the OAuth custom connector (next section) — it is the verified path for Desktop chat, web, and Cowork, and needs no install. The old one-click .mcpb bundle is retired: it ran the stdio server on Desktop's bundled Node, which crash-loops. If you still have a dashclaw extension installed from it, uninstall it (Settings → Extensions) before adding the connector.

Claude custom connector (remote, OAuth)

Self-hosted DashClaw is addable as a Claude custom connector with no API key in the UI — Claude's connector flow requires OAuth, not headers:

1. In Claude: Settings → Connectors → Add custom connector.
2. Paste https://<your-instance>/api/mcp.
3. Claude discovers /.well-known/oauth-protected-resource, registers via DCR, and opens your DashClaw login + a consent screen.
4. Authorize → the 17 governance tools appear, scoped to your workspace.

Works on Free/Pro/Max/Team/Enterprise (Free is capped at one custom connector). The legacy x-api-key path (Managed Agents) is unchanged.

Plugin (skills) via marketplace

To also load the DashClaw skills (governance protocol + platform intelligence) in the Claude app: Customize → Plugins → "+" → Add marketplace → github: ucsandman/DashClaw, then install the dashclaw plugin.

Tools (17 governance + 2 stdio support)

Grouped by domain. See src/tools.ts for the canonical definitions.

Core governance (9) — the guard / record / invoke loop plus discovery and session lifecycle.

Tool	Description
dashclaw_guard	Evaluate policies before risky actions
dashclaw_record	Log actions to audit trail
dashclaw_invoke	Execute a registered capability through the server's guard, approval, execution-claim, effect, and outcome seam
dashclaw_capabilities_list	Discover available APIs
dashclaw_policies_list	See active governance policies
dashclaw_wait_for_approval	Block until a human resolves an approval
dashclaw_session_start	Register agent session
dashclaw_session_end	Close agent session
dashclaw_session_retro	Read the session's own defensibility retro (clean/review/flagged posture)

Session linkage: after dashclaw_session_start, the server auto-stamps that session's id onto every dashclaw_record in the same connection (stdio). Pass session_id on dashclaw_record to override, or to attribute explicitly on the HTTP transport (POST /api/mcp), where each request is stateless.

Enforcement boundary

dashclaw_guard, dashclaw_record, and dashclaw_wait_for_approval are cooperative tools. They return policy and audit state, but the MCP host or model still chooses whether to honor it. Use a host interception hook when you need a mechanical gate around ordinary MCP tools.

dashclaw_invoke is the bounded effect seam. DashClaw holds the registered capability configuration, evaluates the exact invocation against current policy, records it, enforces approval, and atomically claims one execution attempt before making the external call. Approval and plan grants are consumed at that claim, not by the earlier guard evaluation. If execution finishes but the outcome cannot be recorded, the tool reports unknown execution state and does not describe a retry as safe. Reconcile the external system first.

Retrospection (2) — record assumptions; recent governed-action ledger.

Tool	Description
dashclaw_assumption_record	Record an unverified assumption underpinning an action
dashclaw_decisions_recent	Recent governed-action ledger

Agent identity (1) — operator-approved pairing of an unidentified agent to a registered identity.

Tool	Description
dashclaw_pair	Enroll agent identity: keypair locally, public key to /api/pairings

Team Tasks (3) — create a Team Task, append an inter-agent timeline event, update task status.

Tool	Description
dashclaw_task_create	Create a Team Task — one record per multi-agent /team run
dashclaw_task_event	Append one event to a Team Task timeline (delegation, reply, status, approval_needed, result, error, done)
dashclaw_task_update	Update a Team Task: status transitions and stored transport session ids

Plans (2) — submit a preflight plan for one-card operator review and poll its review state. Preview and review responses are evidence; the live action is re-evaluated and any grant is consumed only by its execution claim.

Tool	Description
dashclaw_plan_submit	Submit an ordered step list for preflight review; approved steps become scoped, expiring grants consumed only by an execution claim
dashclaw_plan_status	Check a submitted plan's overall and per-step verdict

DashClaw-gated stdio tools (2)

Registered by src/tools/index.ts on the local stdio server only, gated on the same DASHCLAW_URL + DASHCLAW_API_KEY credentials as the governance set:

Tool	Description
dashclaw_status	Check DashClaw gate configuration and reachability
export_dashclaw_evidence	Export local audit entries carrying DashClaw guard/evidence metadata

Resources (3)

URI	Description
dashclaw://policies	Active policy set
dashclaw://agent/{agent_id}/history	Recent action history (last 50)
dashclaw://status	Instance health + operational metrics

Configuration

Set these in your MCP client's env block (preferred — scoped to the server process, invisible to your terminals) or your shell. The annotated template lives in .env.example.

CLI Arg	Env Var	Default	Description
--url	DASHCLAW_URL	http://localhost:3000	DashClaw instance URL — with DASHCLAW_API_KEY, enables the governance tool set
--key	DASHCLAW_API_KEY	(empty)	API key (oc_live_ prefix)
--agent-id	DASHCLAW_AGENT_ID	(empty)	Default agent ID (auto-derived from MCP clientInfo.name when empty)
	DASHCLAW_MODE	authoritative	DashClaw gate mode (only authoritative is supported)
	DASHCLAW_LOCAL_HOME	<cwd>/.dashclaw-local	Where local state lives (see Storage below)
	DASHCLAW_TIMEOUT_MS	30000	DashClaw API request timeout
	DASHCLAW_LOCK_STALE_MS	30000	Stale file-lock threshold for local state files
	DASHCLAW_AUDIT_MAX_ENTRIES	(unlimited)	Cap retained audit entries

CLI args take precedence over environment variables.

Note: This server reads DASHCLAW_URL (not DASHCLAW_BASE_URL); the hooks and CLI in the DashClaw repo read DASHCLAW_BASE_URL.

Storage

Local-first state under .dashclaw-local/ in the working directory (override with DASHCLAW_LOCAL_HOME). Plain JSON — human-readable, diffable, zero native dependencies:

File	Holds
state.json	The local default workspace
audit.log	Append-only JSONL audit trail read by the DashClaw evidence tools

Secrets are never written here — tokens stay in the environment, read at call time.

License

Apache-2.0. This package incorporates code from an upstream Apache-2.0 project — see NOTICE for the attribution.

Releasing

After bumping version in mcp-server/package.json, run from the repo root:

npm run release:mcp

One command does everything, and re-running is always safe (already-published steps are skipped):

1. Syncs server.json versions to package.json (commit the change if it edits the file).
2. Publishes to npm — your browser opens for the security-key 2FA prompt.
3. Publishes to the official MCP Registry via mcp-publisher — if the saved GitHub token expired, it re-runs the device-flow login (enter the printed code at github.com/login/device) and retries.

Prereqs (one-time): npm login, and the official mcp-publisher binary from modelcontextprotocol/registry releases — never npm i -g mcp-publisher, that name is squatted by an unrelated package.