Agent Handoff MCP

Agent Handoff MCP is a small production-oriented Model Context Protocol server for coordinating work between autonomous agents. It gives agents a shared, file-backed handoff queue with atomic claiming, lineage tracking, terminal state cleanup, and aggregate status reporting. The goal is simple: stop duplicated agent work and make cross-agent ownership explicit.

Why This Exists

Multi-agent systems fail when two workers pick up the same task, when a failed handoff disappears from context, or when stale pending work silently accumulates. This server keeps the handoff lifecycle in one durable JSON store under ~/.local/share/agent-handoff by default. It is intentionally local-first, dependency-light, and easy to inspect. The store can be moved with AGENT_HANDOFF_DIR.

Tools

• create_handoff creates a pending handoff from one agent to another. It records sender, receiver, title, optional context, optional payload, parent lineage, and an optional TTL.
• claim_handoff atomically claims a pending handoff. If another agent already claimed it, the call fails instead of creating duplicate work.
• complete_handoff marks a claimed handoff as completed or failed and records result/error data.
• list_pending lists pending work assigned to a specific target agent and expires stale TTL-bound records.
• stats returns counts by status, counts by agent pair, and stale pending totals.
• purge_terminal deletes completed, failed, or expired records older than a configurable number of days.

Usage

Install dependencies, then run through any MCP client that supports stdio:

npm install
node index.js

Example handoff flow:

{
  "from_agent": "planner",
  "to_agent": "worker-a",
  "title": "Fix RapidAPI sync drift",
  "payload": {"path": "scripts/rapidapi-sync.sh"},
  "ttl_seconds": 86400
}

The receiving agent calls claim_handoff, performs the task, then calls complete_handoff. Every state transition appends an event, so the record remains auditable after completion.

Operational Notes

The server uses an atomic lock file around store reads/writes. It is designed for low-volume local orchestration, not a distributed queue across machines. For a single workstation or one shared mounted home directory, it is enough to prevent double-pickup and keep lineage available to later agents. If the process dies mid-call, terminal states remain readable and stale lock files are recovered after a short timeout.

Monetization Path

This is ready for MCPize-style distribution as a developer operations utility. The buyer value is cross-agent reliability: fewer duplicate edits, clearer ownership, and a durable record of what was delegated, claimed, and completed. It pairs naturally with coding-agent teams, local automation suites, and revenue/ops loops that need bounded ownership.