# 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:

```text
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

| Tool | Purpose |
|---|---|
| `handoff_whoami` | Show the authenticated identity, boundaries, and policy revision. |
| `handoff_send` | Send a structured handoff to an authorized recipient. |
| `handoff_inbox` | List handoffs addressed to the current identity. |
| `handoff_get` | Read a handoff and its append-only event history. |
| `handoff_acknowledge` | Accept queued or blocked work. |
| `handoff_update_status` | Mark work blocked/completed, or cancel it while queued. |

## 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.)

| Command | Purpose |
|---|---|
| `http` | Start the shared Streamable HTTP server. |
| `stdio` | Start a stdio server bound to `HANDOFF_AGENT_ID`. |
| `init --registry <path>` | Create a starter registry with disabled synthetic identities. |
| `validate --registry <path>` | Validate a registry without reading tokens or the database. |
| `issue --registry <path> --agent <id> --expires <iso8601>` | Issue an expiring token, printed once to stdout. |
| `rotate ...` | Replace an existing token; the old one stops working immediately. |
| `disable` / `enable` | Toggle an identity across all transports. |
| `revoke` | Remove an identity's token binding. |
| `token` | Generate a token and digest without touching a registry. |

`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:

```bash
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](docs/QUICKSTART.md) for complete PowerShell and POSIX clean-room flows.

The default endpoints are:

```text
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:

```json
{
  "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](docs/CONFORMANCE-2026-10-21.md) 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](https://www.rfc-editor.org/rfc/rfc6750.html#section-3.1)
for bearer error responses; they are a focused request-shape check, not a
claim of full MCP/OAuth conformance.

| Case | Expected response | Observation (first run 22 October, fix 25 October 2026) |
|---|---|---|
| 1: no header | 401 plus Bearer challenge | Pass |
| 2: garbage token | 401 plus `error="invalid_token"` challenge | Pass |
| 3: expired static token | 401 plus `error="invalid_token"` challenge | Pass; registry expiry is already supported |
| 5: valid fixture token only in query | 400/401 plus Bearer challenge, never success | Pass: 401 |
| 6: valid header plus `access_token` in JSON body | 400 plus OAuth `invalid_request` | Pass since 25 October: 400 plus `invalid_request` challenge (was a 400 JSON-RPC rejection) |
| 6: valid header plus form-body token | 400 plus OAuth `invalid_request` | Pass since 25 October: 400 plus `invalid_request` challenge (was a 415) |
| 7: wrong scheme, missing space, empty Bearer | 400 `invalid_request` or 401 plus Bearer challenge | Pass: 401 for all 3 |

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](docs/QUICKSTART.md)
- [Protocol and lifecycle](docs/PROTOCOL.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Security model](SECURITY.md)
- [Registry JSON Schema](schema/agent-registry.schema.v1.json)
- [Roadmap](ROADMAP.md)
- [Release validation, 2026-10-01](docs/RELEASE_EVIDENCE_2026-10-01.md)
- [Changelog](CHANGELOG.md)

## 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](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](docs/RECOVERY.md) 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.