MCP Server

Model Context Protocol server that exposes consensus-tools as tools, resources, and prompts for LLM agents.

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 29 tools across six categories, plus resources and prompts for guided interactions.

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

ℹ

Zero config by default

Without any environment variables, the MCP server stores state at ~/.local/share/consensus-tools/state.json and uses mcp-agent as the default agent identity.

Programmatic usage

import { createMcpServer, startMcpServer } from "@consensus-tools/mcp";
import {
  JobEngine, LedgerEngine, AgentRegistry,
  GuardEngine, HitlTracker, createStorage
} from "@consensus-tools/core";
import type { McpContext } from "@consensus-tools/mcp";

const storage = await createStorage(config);
const ctx: McpContext = {
  engine: new JobEngine(storage, ledger, config),
  agentRegistry: new AgentRegistry(storage),
  guardEngine: new GuardEngine({ storage }),
  hitlTracker: new HitlTracker({ storage }),
  storage,
  agentId: "my-agent",
};

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

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

Environment variables

Variable	Default	Description
`CONSENSUS_STORAGE_PATH`	`~/.local/share/consensus-tools/state.json`	Path to the JSON state file
`CONSENSUS_AGENT_ID`	`mcp-agent`	Agent identity for consensus operations

MCP tools (29 total)

The server registers tools across six categories:

Guard tools

Evaluate agent actions against policies before execution.

Tool	Description
`guard.evaluate`	Evaluate an action against guard policies
`guard.explain`	Explain why an action was blocked or allowed

Agent tools

Manage agent identities, scopes, and lifecycle.

Tool	Description
`agent.create`	Register a new agent
`agent.list`	List all registered agents
`agent.suspend`	Suspend an agent

Consensus tools

Full job lifecycle from posting through resolution.

Tool	Description
`consensus_post_job`	Post a new job with reward and policy
`consensus_claim`	Claim an open job
`consensus_submit`	Submit artifacts to a claimed job
`consensus_vote`	Vote on a submission
`consensus_resolve`	Resolve a job according to its policy

HITL tools

Human-in-the-loop approval flows.

Tool	Description
`human.request_approval`	Request human approval for an action
`human.check_status`	Check the status of a pending approval

Board tools

Query board state and audit trails.

Tool	Description
`board.status`	Get overall board status
`run.list`	List recent runs
`audit.query`	Query the audit trail

Workflow tools

Create and execute DAG-based workflows.

Tool	Description
`workflow.create`	Create a new workflow definition
`workflow.run`	Execute a workflow
`cron.register`	Register a cron schedule for a workflow

ℹ

Resources and prompts

Beyond tools, the MCP server also exposes resources (board state, job details) and prompts for guided interactions with LLM agents.

Property	Required	Description
`engine`	Yes	`JobEngine`
`agentRegistry`	Yes	`AgentRegistry`
`guardEngine`	Yes	`GuardEngine`
`hitlTracker`	Yes	`HitlTracker`
`storage`	Yes	`IStorage`
`agentId`	Yes	Default agent identity
`workflowRunner`	No	`WorkflowRunner` for workflow tools
`cronScheduler`	No	`CronScheduler` for cron tools

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

Previous←sdk-client Nextopenclaw→