handoff-mcp-server

An MCP server that lets an AI coding agent save the state of a task and pick it up again in a later session. The saved state is a small validated JSON document, not a transcript. It loads back as a short briefing: the objective, where the work stands, the files that matter and which lines in them, the decisions already made and why, and the next steps in priority order.

Why

Long coding sessions end before the task does. The context window fills, the session times out, the laptop closes. The next session starts from zero, or from a transcript that is mostly noise. What actually carries a task across sessions is small: what I was doing, where in the code, what I decided and why, and what is left. This server stores exactly that and nothing else.

I wrote it for my own multi-day tasks in Claude Code. A saved handoff is usually one to two thousand tokens when loaded, against tens of thousands for the session it came from.

Related MCP server: SloplessCode

Tools

The server exposes three tools over stdio.

save_handoff takes:

• session_id: a short slug, used as the filename (auth-bug-fix, payment-feature).

• task_objective, task_status (in_progress, blocked, needs_review), progress_summary.

• files: a list of { path, relevance, focus_ranges? }. Each focus range is { start, end, note }, so the next session can open the right lines instead of the whole file.

• decisions: a list of { decision, rationale }. The server stamps each with the save time.

• next_steps: a list of { action, priority } with priority high, medium or low.

The briefing format

load_handoff returns Markdown shaped like this. The example is fictional.

# Session Restoration

## Task: Make invoice PDF generation idempotent
**Status:** in_progress
**Progress:** Root cause found: the job enqueues twice on retry. Fix written, not yet tested.

## Relevant Files

### app/jobs/invoice_pdf_job.rb
Where the duplicate enqueue happens

Focus areas:
- Lines 14-31: perform method, the retry path re-enqueues instead of re-running
- Lines 40-52: new guard using the invoice id as the lock key

### spec/jobs/invoice_pdf_job_spec.rb
Has the failing case to extend

## Key Decisions

**Decision:** Lock on invoice id rather than job id
**Rationale:** Job ids change on retry; invoice id is stable and already indexed

## Next Steps

- [HIGH] Add a spec for the retry path
- [MEDIUM] Check the two other jobs that use the same retry helper
- [LOW] Remove the debug logging once the spec is green

Next steps are sorted by priority. Decisions are only printed when there are any.

Install

Requires Node 18 or later.

git clone https://github.com/Abdelwahab313/handoff-mcp-server.git
cd handoff-mcp-server
npm install
npm run build

npm install runs the build, so build/index.js exists once it finishes.

Claude Code

claude mcp add handoff-protocol -- node /absolute/path/to/handoff-mcp-server/build/index.js

Claude Desktop or any other MCP client

Add to the client's MCP configuration:

{
  "mcpServers": {
    "handoff-protocol": {
      "command": "node",
      "args": ["/absolute/path/to/handoff-mcp-server/build/index.js"]
    }
  }
}

How I use it

At the end of a session, or when the context is getting full, I ask the agent to save a handoff with a named session id. At the start of the next session I ask it to load that id before anything else. The briefing is short enough to read in full, so I can correct it before the agent acts on it.

Limits

• Storage is a flat directory in the home folder. Saving with an existing session_id overwrites it. There is no history.

• session_id becomes the filename unchanged. Keep it to letters, digits, dots and dashes.

• The token estimate is characters divided by four. It is a rough guide, not a count.

• No test suite yet. The schema validation on both save and load is the only guard.

License

MIT