conversation-handoff-mcp

MCP server for transferring conversation context between AI chats or different projects within the same AI.
日本語ドキュメント
Features
- **Prompt Injection Protection (v0.14.0+)**: handoff_load returns stored content inside untrusted-content markers — a warning banner, a one-time boundary token that content cannot forge, and code fences widened past any backtick run in the body
- **Sender Metadata (v0.14.0+)**: Optional from_project / spawner_dispatch_id / sender_agent_id let an orchestrator record who sent a handoff, without tying the server to any one ecosystem
- **Tags & Search (v0.12.0+)**: Tag handoffs with structured labels (project:foo, issue:176) and discover them with handoff_search — multi-criteria filtering by tags, text, project, AI, status, and date range
- **Handoff Metadata (v0.11.0+)**: Enrich handoff_list with message count, size, status, and next action — decide on work resumption without loading full conversations
- **Comments/Annotations (v0.10.0+)**: Add notes and annotations to handoffs for cross-session context
- **Server Restart (v0.9.0+)**: Restart the shared HTTP server from any MCP client — useful after package updates
- **Audit Logging (v0.7.0+)**: Optional structured JSONL logging for diagnostics (--audit flag)
- **Verbatim Conversation Saving (v0.6.1+)**: AI saves complete conversations without summarization or abbreviation
- **Merge Handoffs (v0.6.0+)**: Combine multiple related handoffs into one unified context
- **MCP Apps UI (v0.5.0+)**: Interactive UI for browsing and managing handoffs on compatible clients
- **Auto-Connect (v0.4.0+)**: Server automatically starts in the background - no manual setup required
- **Auto-Reconnection (v0.4.0+)**: Seamlessly reconnects when server goes down - no manual intervention needed
- **Memory-Based Storage**: Lightweight temporary clipboard design - no files written to disk
- **Common Format**: Human-readable Markdown format
- **Lightweight API**: Returns only summaries when listing to save context
- **Auto-Generated Keys (v0.4.0+)**: Key and title are now optional in handoff_save
Installation
Works with Claude Desktop, Claude Code, Codex CLI, Gemini CLI, and other MCP clients.
Configuration File Locations
| Client | Config File |
|--------|-------------|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Claude Code | ~/.claude/settings.json |
| Codex CLI | ~/.codex/config.toml |
| Gemini CLI | ~/.gemini/settings.json |
| Cursor | ~/.cursor/mcp.json |
| ChatGPT Desktop | In-app settings (Developer Mode) |
Via npm (Recommended)
No pre-installation required - runs via npx.
For global installation:
Local Build
MCP configuration:
> **Note**: Codex CLI uses TOML format. See Codex MCP documentation for details.
Tools
handoff_save
Save conversation context. Key and title are auto-generated if omitted (v0.4.0+). The conversation field stores the complete verbatim content — AI is instructed not to summarize or abbreviate messages (v0.6.1+).
Sender metadata (v0.14.0+)
Three optional fields let an orchestrator record *who* sent a handoff, so the receiving agent can trace it back without the operator typing it in by hand:
| Field | Meaning |
|-------|---------|
| from_project | Source project / repository scope |
| spawner_dispatch_id | Dispatch ID of the sending orchestrator, when it runs under one |
| sender_agent_id | Stable identifier of the sending orchestrator / agent |
All of them are optional and **opaque to this server** — no format is enforced, and nothing downstream requires them. Clients that omit them behave exactly as before. They are returned by both handoff_list and handoff_load, and are left out of the output entirely when unset.
**Orchestrator integration.** This is the pattern tmai uses to auto-populate sender context when it wraps the save path — but nothing here is tmai-specific. Any orchestrator can adopt the same fields, and an ecosystem with no "dispatch" concept can simply leave them out.