conversation-handoff-mcp
MCP server for transferring conversation context between AI chats or different projects within the same AI.
Features
- 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.
{
"mcpServers": {
"conversation-handoff": {
"command": "npx",
"args": ["-y", "conversation-handoff-mcp"]
}
}
}
For global installation:
npm install -g conversation-handoff-mcp
Local Build
git clone https://github.com/trust-delta/conversation-handoff-mcp.git
cd conversation-handoff-mcp
npm install
npm run build
MCP configuration:
{
"mcpServers": {
"conversation-handoff": {
"command": "node",
"args": ["/path/to/conversation-handoff-mcp/dist/index.js"]
}
}
}
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+).
// With explicit key and title
handoff_save(
key: "project-design",
title: "Project Design Discussion",
summary: "Decided on MCP server design approach",
conversation: "## User\nQuestion...\n\n## Assistant\nAnswer..."
)
// Auto-generated key and title (v0.4.0+)
handoff_save(
summary: "Decided on MCP server design approach",
conversation: "## User\nQuestion...\n\n## Assistant\nAnswer..."
)
// → key: "handoff-20241208-143052-abc123" (timestamp + random)
// → title: "Decided on MCP server design approach" (from summary)
handoff_list
Get list of saved handoffs (summaries only).
handoff_list()
handoff_load
Load full content of a specific handoff.
handoff_load(key: "project-design")
handoff_load(key: "project-design", max_messages: 10) // Last 10 messages only
handoff_clear
Delete handoffs.
handoff_clear(key: "project-design") // Specific key
handoff_clear() // Clear all
handoff_stats
Check storage usage and limits.
handoff_stats()
Auto-Connect Mode (v0.4.0+)
Starting with v0.4.0, the server automatically starts in the background when an MCP client connects. No manual setup required!
How It Works
[User launches Claude Desktop]
→ MCP client starts
→ Scans ports 1099-1200 in parallel for existing server
→ If no server found: auto-starts one in background
→ Connects to server
→ (User notices nothing - it just works!)
[User launches Claude Code later]
→ MCP client starts
→ Scans ports 1099-1200 in parallel
→ Finds existing server
→ Connects to same server
→ Handoffs are shared!
Operating Modes
| Mode | When | Behavior |
|---|---|---|
| Auto-Connect (default) | No HANDOFF_SERVER set | Discovers or auto-starts server |
| Explicit Server | HANDOFF_SERVER=http://... | Connects to specified URL |
| Standalone | HANDOFF_SERVER=none | No server, in-memory only |
Memory-Based Storage
Handoff data is stored in memory only:
- Data is shared across all connected MCP clients via the HTTP server
- Data is lost when the server process stops
- No files are written to disk - lightweight and clean
- Perfect for temporary context sharing during active sessions
- FIFO Auto-Cleanup: When limit is reached, oldest handoff is automatically deleted (no errors)
Auto-Reconnection
When the shared server goes down during operation:
[Server stops unexpectedly]
→ User calls handoff_save()
→ Request fails (connection refused)
→ Auto-reconnection kicks in:
→ Rescan ports 1099-1200 for existing server
→ If found: connect to it
→ If not found: start new server in background
→ Retry the original request
→ User sees success (transparent recovery!)
- Configurable retry limit via
HANDOFF_RETRY_COUNT(default: 30) - On final failure: outputs pending content for manual recovery
- Other MCP clients automatically discover the new server on their next request
Server Auto-Shutdown (TTL)
The server automatically shuts down after a period of inactivity:
- Default: 24 hours of no requests
- Configurable via
HANDOFF_SERVER_TTLenvironment variable - Set to
0to disable auto-shutdown - Next MCP client request will auto-start a new server
MCP Client Configuration
Standard configuration (recommended) - Just works with auto-connect:
{
"mcpServers": {
"conversation-handoff": {
"command": "npx",
"args": ["-y", "conversation-handoff-mcp"]
}
}
}
Specify custom server:
{
"mcpServers": {
"conversation-handoff": {
"command": "npx",
"args": ["-y", "conversation-handoff-mcp"],
"env": {
"HANDOFF_SERVER": "http://localhost:3000"
}
}
}
}
Force standalone mode (no server):
For Claude Desktop only. Claude Desktop cannot transfer conversations between projects by default, but since it shares memory space as a single app, this MCP server enables handoffs between projects. Claude Code and CLI tools run as separate processes per tab/session, so handoffs don't work in this mode.
{
"mcpServers": {
"conversation-handoff": {
"command": "npx",
"args": ["-y", "conversation-handoff-mcp"],
"env": {
"HANDOFF_SERVER": "none"
}
}
}
}
Manual Server Start (Optional)
If you prefer manual control:
# Default port (1099)
npx conversation-handoff-mcp --serve
# Custom port
npx conversation-handoff-mcp --serve --port 3000
HTTP Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /handoff | Save a handoff |
| GET | /handoff | List all handoffs |
| GET | /handoff/:key | Load a specific handoff |
| DELETE | /handoff/:key | Delete a specific handoff |
| DELETE | /handoff | Delete all handoffs |
| GET | /stats | Get storage statistics |
| GET | / | Health check |
Workflow Example
Scenario: Design discussion in Claude Desktop → Implementation in Claude Code
-
In Claude Desktop - Have a design discussion:
User: Let's design an authentication system for my app. Assistant: I recommend using JWT with refresh tokens... [detailed discussion continues] -
Save the conversation - When ready to hand off:
User: Save this conversation for implementation in Claude Code. Assistant: (calls handoff_save) ✅ Handoff saved with key: "auth-design-20241208" -
In Claude Code - Load and continue:
User: Load the auth design discussion. Assistant: (calls handoff_load) # Handoff: Authentication System Design [Full conversation context loaded] I see we discussed JWT with refresh tokens. Let me implement that...
Key Points:
- The AI automatically formats and saves the conversation
- Context is fully preserved including code snippets and decisions
- No manual copy-paste needed
Note: The server automatically starts in the background when the first MCP client connects. No manual startup required.
Configuration
Customize behavior via environment variables.
Connection Settings (v0.4.0+)
| Variable | Default | Description |
|---|---|---|
HANDOFF_SERVER | (auto) | none for standalone, or explicit server URL |
HANDOFF_PORT_RANGE | 1099-1200 | Port range for auto-discovery |
HANDOFF_RETRY_COUNT | 30 | Auto-reconnect retry count |
HANDOFF_RETRY_INTERVAL | 10000 | Auto-reconnect interval (ms) |
HANDOFF_SERVER_TTL | 86400000 (24h) | Server auto-shutdown after inactivity (0 = disabled) |
Storage Limits
| Variable | Default | Description |
|---|---|---|
HANDOFF_MAX_COUNT | 100 | Maximum number of handoffs |
HANDOFF_MAX_CONVERSATION_BYTES | 1048576 (1MB) | Maximum conversation size |
HANDOFF_MAX_SUMMARY_BYTES | 10240 (10KB) | Maximum summary size |
HANDOFF_MAX_TITLE_LENGTH | 200 | Maximum title length |
HANDOFF_MAX_KEY_LENGTH | 100 | Maximum key length |
Configuration Example (Claude Desktop)
{
"mcpServers": {
"conversation-handoff": {
"command": "npx",
"args": ["-y", "conversation-handoff-mcp"],
"env": {
"HANDOFF_MAX_COUNT": "50",
"HANDOFF_MAX_CONVERSATION_BYTES": "524288"
}
}
}
}
Conversation Format
## User
User's message
## Assistant
AI's response
License
MIT
Author
trust-delta