MCP Server

Overview

@consensus-tools/mcp is a Model Context Protocol (MCP) server that gives Claude Code or any MCP-compatible client access to the full consensus-tools stack. It registers 31 tools across six areas, plus resources and prompts for guided interactions. Consensus tools use snake_case; the rest use dotted names.

Installation

pnpm add @consensus-tools/mcp

Quick start

Claude Code integration

Add to your .claude/settings.local.json:

{
  "mcpServers": {
    "consensus-tools": {
      "command": "npx",
      "args": ["@consensus-tools/mcp"]
    }
  }
}

With environment configuration:

{
  "mcpServers": {
    "consensus-tools": {
      "command": "npx",
      "args": ["@consensus-tools/mcp"],
      "env": {
        "CONSENSUS_STORAGE_PATH": "/path/to/state.json",
        "CONSENSUS_AGENT_ID": "my-agent"
      }
    }
  }
}

Environment variables

MCP tools (31 total)

The standalone server (via npx @consensus-tools/mcp) registers 31 tools across six areas.

Guard & Policy (10)

Evaluate agent actions against policies before execution.

The domain guard tools accept ergonomic payload keys (filesChanged, diff, content, replyText, deployEnv, requestedPermissions, attachments, ...); the adapter translates them to the evaluator contract before evaluation.

Agent (4)

Manage agent identities, scopes, and lifecycle.

Consensus jobs (5)

Full job lifecycle from posting through resolution.

Human-in-the-loop (1)

Board & Audit (6)

Query board state and audit trails.

Workflow & Cron (5)

Available when the context provides a workflowRunner / cronScheduler (the standalone server wires both).

Resources

The server exposes board data as MCP resources (application/json):

resources/list enumerates one entry per discovered board.

Prompts

Three guided prompts help clients drive common flows:

Programmatic usage

The standalone entry point is the reference wiring. To embed the server in your own process:

import { startMcpServer, createMcpServer, type McpContext } from "@consensus-tools/mcp";
import {
  LocalBoard, AgentRegistry, GuardEngine, HitlTracker,
} from "@consensus-tools/core";
import { createStorage } from "@consensus-tools/storage";
import { createGuardEvaluatorRegistry } from "@consensus-tools/guards";

const storage = await createStorage(config);
const board = new LocalBoard(config, storage);
await board.init();

const agentRegistry = new AgentRegistry(storage);
const ctx: McpContext = {
  engine: board.engine,
  agentRegistry,
  guardEngine: new GuardEngine({ storage, agentRegistry, evaluatorRegistry: createGuardEvaluatorRegistry() }),
  hitlTracker: new HitlTracker({ storage }),
  storage,
  agentId: "my-agent",
  // workflowRunner / cronScheduler are optional — provide them to enable
  // the workflow.* and cron.* tools.
};

// Option 1: start on stdio (typical for MCP)
await startMcpServer(ctx);

// Option 2: get the Server instance for a custom transport
const server = createMcpServer(ctx);

API reference

createMcpServer(ctx)

Creates an MCP Server instance with all tools, resources, and prompts registered. Returns the server without connecting a transport.

startMcpServer(ctx)

Creates the server and connects it via stdio transport. This is the standard entry point when running as an MCP server process.

McpContext

The advertised server version is read from package.json, so initialize always reports the published version.

Trust model

The standalone server is designed for a single, trusted MCP client (your own agent) against a local board. Understand these boundaries before exposing it to an untrusted or multi-tenant client:

• human.approve reports client-asserted identity. The approver field is whatever the client sends — it is not authenticated. Treat human.approve as an integration point for a trusted approval UI, not as a security boundary against an adversarial caller.
• policy.assign is an operator-level lever. It can loosen or tighten a board's guard policy. In an untrusted deployment, gate this tool to operators.
• Guards evaluate the caller's self-declared payload. Guards catch mistakes and enforce policy for a cooperating agent; they are not a sandbox around a hostile one.
• Approval bookkeeping is race-safe under a single sequential writer. The stdio server processes one request at a time. A deployment that fronts the server with a concurrent transport should serialize human.approve calls per run.

Related

• OpenClaw -- Alternative agent adapter via the OpenClaw plugin system
• SDK Node -- REST API server (MCP uses the same engines directly)
• Local Board -- Local dev server to pair with MCP during development