agent-handoff-mcp

Centralized multi-project state & handoff MCP server (Streamable HTTP). AI agents (Claude Code, Codex, Cursor, …) save checkpoints in one session and resume in another with under 500 tokens of input overhead. The full specification is captured across the guides in the Documentation section.

Quickstart

cd agent-handoff
./dev.sh                 # bootstraps .venv, installs dev deps, starts the server
# with the web dashboard:  http://127.0.0.1:8766/
# MCP endpoint:            http://127.0.0.1:8765/mcp

dev.sh uses repo-local defaults (./state.db, loopback, dashboard on) and supports --fresh, --no-dashboard, --port, --dash-port, --token, --log, and --check (run lint+tests). See ./dev.sh --help. To run manually instead:

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
DATABASE_PATH=./state.db .venv/bin/python main.py

The server listens for MCP at http://127.0.0.1:8765/mcp and exposes a GET /health endpoint ({"status":"ok","db":"writable"}).

Related MCP server: Graph

Features

• 12 tools · 2 resources · 1 prompt — every command explained in docs/mcp-usage.md

• Handoff context < 500 tokens — deterministic ceil(len/4) metric with a documented truncation order

• Seed context — drop .md/.json files in a repo's .agent-handoff/ folder (glossary, API contracts, business flows) and the server folds them into the handoff summary + serves them on demand

• Git snapshots — save_checkpoint captures git diff HEAD --stat plus untracked files (capped at 200 lines / 4 KB)

• SQLite WAL with a single async writer connection (no database is locked)

• Fail-closed auth — Authorization: Bearer <token> required when MCP_AUTH_TOKEN is set; refuses to bind non-loopback without a token

• Code-graph integration — queries code-review-graph + graphify, and can store per-project graphs inside the MCP database instead of each repo

• Auto-start — the server can spawn and supervise graph-server subprocesses

Documentation

Tests

.venv/bin/python -m pytest -q

Covers the PRD acceptance criteria: migrations/WAL, path validation, git capture, the 500-token budget, retention pruning, fail-closed auth (401s), /health, 20 parallel mixed requests, code-graph capture, DB-backed graph storage, and auto-start supervision.