Agent Handoff MCP Server

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.

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.

Local HTTP conformance check

Run npm run conformance from a source checkout after npm ci. It validates server.json against the existing pinned Registry schema, starts an isolated loopback server and disposable SQLite registry fixture, checks missing and invalid bearer requests with curl, and runs the official framework plus an Inspector tools/list and read-only handoff_whoami call. It requires curl and network access for the exactly pinned npx tools. No operator registry, existing database, stored login or live service is used.

The asserted spec revision is 2026-07-28, using @modelcontextprotocol/conformance@0.2.0-alpha.12 --requirements 2026-07-28. The current HTTP transport targets 2025-11-25; stateless request handling alone does not establish support for the newer lifecycle. Inspector @modelcontextprotocol/inspector@2.11.0 explicitly uses its legacy protocol era for the application smoke. The upstream framework has no bearer-header flag, so a test-only fetch adapter adds the ephemeral fixture header solely to that loopback endpoint. Production authentication is exercised unchanged.

The check currently exits 1 on the revision gap. Findings and redacted logs go to ignored release-evidence/conformance/ (override with HANDOFF_CONFORMANCE_OUTPUT). Every check runs even when another fails. Failures are never silently baselined or repaired in the runner. See the first-run findings before proposing this as a release gate. This command does not publish or modify CI.

Bearer request negative tests

Run npm run test:auth-negative after npm ci in a source checkout. This dependency-free runner uses the existing disposable registry/SQLite harness on 127.0.0.1, with a random port and freshly generated fixture credentials. It accepts no remote endpoint or stored-token override. It runs every probe, prints only names and status codes, writes sanitised results under ignored release-evidence/auth-negative/results.json, and exits 1 if any expected response is missing. It does not change CI. A successful header-authenticated tools/list control guards against a broken fixture.

The numbered cases use RFC 6750 sections 2 and 3.1 for bearer error responses; they are a focused request-shape check, not a claim of full MCP/OAuth conformance.

Case 6 was a finding on the first run. Since 25 October /mcp rejects any JSON or form body that carries access_token, with or without a header, with HTTP 400 and a Bearer error="invalid_request" challenge, before the token is checked. Form bodies are parsed (16 KB cap) only to find that field; MCP requests must still be JSON. The form probe uses RFC 6750's form-encoded access_token; the JSON probe separately checks the same field on an otherwise valid MCP request.

Cases 4, 8-12 are N/A to this static-token profile today: no JWT audience, issuer, per-token OAuth scope hierarchy or Protected Resource Metadata is implemented. Revisit them with an OAuth resource-server migration; N/A is not evidence of compliance. Unknown tokens still fail even though an issuer claim is not evaluated. Case 3 is not N/A: static registry credentials already have expires_at, and this runner and existing e2e tests exercise expiry. Existing rotation, disabled-token and handoff authorisation tests also remain in place.

For external conformance tooling, the package names are mcp-spec-check and @modelcontextprotocol/conformance; the existing pinned official framework command above is unchanged. This runner installs neither package and adds no dependency. Proposed CI wiring belongs in the PR description until the response findings are resolved.

Operational metrics

Set HANDOFF_MCP_METRICS=1 to record in-process counters for handoffs created, accepted (claimed), expired and store errors, plus per-tool call duration histograms. Only the initial queued-to-accepted move counts as a claim. The default is off. When enabled, both HTTP and stdio servers write one JSON snapshot to local stderr at startup, every 60 seconds and on graceful shutdown. For example, HANDOFF_MCP_METRICS=1 agent-handoff-mcp stdio 2>metrics.jsonl captures the running process's snapshots without mixing them with MCP stdout. The snapshot from src/metrics.ts uses an OpenTelemetry OTLP JSON-shaped resourceMetrics/scopeMetrics structure. It has only fixed metric names, counts, timings and a bounded tool-name label; no handoff content, titles, agent text or tokens enter the recorder. No network exporter or public metrics endpoint is installed. The expired counter remains 0 because the current handoff lifecycle has no expiry transition.

Documentation

The draft MCP Registry manifest launches the npm binary with the stdio argument and requires HANDOFF_AGENT_ID, HANDOFF_MCP_REGISTRY and HANDOFF_MCP_DB from the operator. It creates no identities or credentials. The namespace uses the exact GitHub owner spelling, io.github.SarutobiSasuke8. prepublishOnly includes check:registry; publishing and registry login remain separate operator actions. Builds omit source maps and their JavaScript links.

• Clean-room quickstart
• Protocol and lifecycle
• Architecture
• Security model
• Registry JSON Schema
• Roadmap
• Release validation, 2026-10-01
• Changelog

Scope boundary

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

Optional inbox notifications

Set HANDOFF_MCP_NOTIFICATION_FILE to an absolute path to append a local JSONL notice when a new handoff lands. Notifications are off by default. Each line contains only handoffId, senderId, recipientId, status and timestamp. It contains no title, body, attachments or other handoff content. An idempotent retry does not emit a second notice. Protect the file as operational metadata; it reveals agent identities and handoff timing. A notification write failure is logged without handoff content and does not undo the committed handoff.

License

Apache-2.0. See LICENSE.

Recovery and local release evidence

Use agent-handoff-mcp backup <out-file> for a live WAL snapshot with the validated registry, and restore <file> into fresh files after stopping servers. Existing destinations require --force; live servers, corrupt backups and incomplete restores remain blocked. See Recovery for commands, policy reconciliation and the limits of local process guards.

The local SQLite store applies ordered, recorded migrations at startup in a schema_migrations table. It recognises existing unversioned stores and records their observed schema before applying pending changes. A store with a newer schema version refuses to open with a clear error; use a compatible binary rather than downgrading the database.

npm run release:dry-run produces local checks, e2e recovery proof, allowlist verification, SPDX SBOM, tarball and SHA-256 evidence under gitignored release-evidence/. Package publication remains an owner action.