Agent Handoff MCP

A local-first Model Context Protocol server for bounded, auditable handoffs between AI agents.

Agent Handoff MCP gives Claude, Codex, local agents, and other MCP clients a shared inbox without giving one model control over another. Agents can send structured work, acknowledge it, report a blocker, complete it, or cancel work they originally queued. Every transition is attributable and retained in SQLite.

Why this exists

Multi-agent systems often pass work through chat transcripts, ad hoc files, or vendor-specific orchestration. That loses ownership, lifecycle state, authorization boundaries, and a durable audit trail. This server turns a handoff into a small protocol object:

sender -> queued -> accepted -> completed
                   |             ^
                   v             |
                 blocked --------+

sender may cancel only while queued

The server coordinates work; it does not execute agents, fetch references, read arbitrary files, or create autonomous agent loops.

Related MCP server: agent2agent

MCP tools

Design properties

• SQLite shared state with WAL mode and parameterized queries

• Streamable HTTP and stdio transports

• Opaque UUID handoff, event, and thread identifiers

• Explicit send_to and receive_from authorization with no permissive defaults

• Per-agent disclosure ceilings: public-safe, internal, or restricted

• Strict registry validation: unknown keys, duplicates, and unsupported versions are rejected

• Immutable policy snapshots: every operation is checked against the current registry, so disabling an identity, rotating a token, or narrowing a relationship takes effect on live sessions without a restart

• Hashed, expiring bearer-token bindings for HTTP

• Idempotency keys for safe retries

• Maximum reply-chain depth to limit automated ping-pong

• Strict message, array, reference, and request-size limits

• Sender/recipient-only reads, re-authorized against current policy

• Append-only lifecycle events; no MCP delete tool

• References are stored as inert strings and never dereferenced

Command line

The package installs one dispatcher binary, agent-handoff-mcp, whose name matches the package so npx @sarutobi-sasuke/agent-handoff-mcp <command> resolves directly once the package is published to npm. (It is not published yet; use a source checkout until then.)

agent-handoff-http, agent-handoff-stdio, agent-handoff-token, and agent-handoff-validate are also installed as direct aliases.

Quick start

Requirements: Node.js 22.13 or newer.

For a source checkout:

git clone https://github.com/SarutobiSasuke8/agent-handoff-mcp.git
cd agent-handoff-mcp
npm ci
npm run build
cp .env.example .env
node dist/src/cli.js init --registry ./config/agents.yaml
node dist/src/cli.js issue --registry ./config/agents.yaml --agent example-alpha --expires 2027-01-01T00:00:00Z
node dist/src/cli.js issue --registry ./config/agents.yaml --agent example-beta --expires 2027-01-01T00:00:00Z
node dist/src/cli.js enable --registry ./config/agents.yaml --agent example-alpha
node dist/src/cli.js enable --registry ./config/agents.yaml --agent example-beta
node dist/src/cli.js validate --registry ./config/agents.yaml
npm run check
npm start

Each issue command prints that identity's raw token exactly once; hand it to that client over a secure channel. Only SHA-256 digests are stored. See docs/QUICKSTART.md for complete PowerShell and POSIX clean-room flows.

The default endpoints are:

GET  http://127.0.0.1:3220/healthz   liveness and policy state
GET  http://127.0.0.1:3220/readyz    readiness; 503 while the policy is degraded
POST http://127.0.0.1:3220/mcp
Authorization: Bearer handoff_<agent-specific-token>

The server binds to localhost by default. Put an authenticated private-network or TLS boundary in front of it before any remote deployment.

Stdio mode

Each stdio client supplies its identity through its own process environment while sharing the same SQLite database and registry:

{
  "command": "node",
  "args": ["/absolute/path/agent-handoff-mcp/dist/src/cli.js", "stdio"],
  "env": {
    "HANDOFF_AGENT_ID": "example-beta",
    "HANDOFF_MCP_DB": "/absolute/shared/path/handoffs.sqlite",
    "HANDOFF_MCP_REGISTRY": "/absolute/path/agents.yaml"
  }
}

Use HTTP when multiple clients should connect to one long-running service. Use stdio for local clients that can safely receive a fixed identity through their own configuration. Both transports re-check the registry on every operation, so revocation applies to running stdio sessions too.

Documentation

• Clean-room quickstart

• Protocol and lifecycle

• Architecture

• Security model

• Registry JSON Schema

• Roadmap

• Changelog

Scope boundary

This project is a coordination primitive, not a general task platform. Shared task boards, decisions, broadcasts, presence, leases, notifications, context promotion, and remote dispatch belong behind future optional modules. The six-tool handoff surface remains the stable core.

License

Apache-2.0. See LICENSE.