What can you do with this server?

This server enables seamless transfer and management of conversation context between different AI chats, AI systems (Claude, ChatGPT, etc.), or projects within the same AI. Core Features: * Save conversations - Store full conversation context with auto-generated keys and titles, summaries, and metadata * List saved handoffs - View lightweight summaries of all saved conversations without loading full content * Load conversations - Retrieve full conversation content by key with optional message limiting * Clear data - Delete specific handoffs by key or clear all saved conversations * Monitor storage - Check usage statistics and configured limits Technical Capabilities: * Auto-connect sharing - Automatically shares handoffs across multiple MCP clients (Claude Desktop, Claude Code, etc.) via background HTTP server * Auto-reconnection - Seamlessly recovers when server goes down without manual intervention * Memory-based storage - Lightweight temporary storage with FIFO auto-cleanup when limits reached (no disk writes) * Flexible configuration - Customize storage limits, connection settings, and server behavior via environment variables * Human-readable format - Uses standard Markdown format (## User / ## Assistant) for conversation storage

Which integrations are available for this server?

Uses Markdown as the common format for saving and loading conversation contexts, ensuring that handoffs between AI sessions are human-readable and preserve structure such as user and assistant roles.

How do I use Conversation Handoff MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Conversation Handoff MCP save our discussion about the API design for later review" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

conversation-handoff-mcp

npm version License: MIT MCP Apps

MCP server for transferring conversation context between AI chats or different projects within the same AI.

日本語ドキュメント

Features

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.

{ "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+). The conversation field stores the complete verbatim content — AI is instructed not to summarize or abbreviate messages (v0.6.1+).

// 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_merge (v0.6.0+)

Merge multiple related handoffs into one. Useful for combining discussions from separate sessions.

// Merge two handoffs (chronological order by default) handoff_merge(keys: ["session-1", "session-2"]) // With custom key and delete sources handoff_merge( keys: ["design-v1", "design-v2", "design-v3"], new_key: "design-final", new_title: "Final Design Document", delete_sources: true, strategy: "sequential" )

Parameter	Required	Default	Description
`keys`	Yes	-	Array of handoff keys to merge (min 2)
`new_key`	No	auto	Key for merged handoff
`new_title`	No	auto	Title for merged handoff
`new_summary`	No	auto	Summary for merged handoff
`delete_sources`	No	`false`	Delete source handoffs after merge
`strategy`	No	`"chronological"`	`"chronological"` (by creation time) or `"sequential"` (array order)

handoff_stats

Check storage usage and limits.

handoff_stats()

MCP Apps UI (v0.5.0+)

For MCP Apps-compatible clients, handoff_list automatically opens an interactive UI. Non-compatible clients receive the standard JSON response.

Features

List View: Card-based list showing title, source AI, and date
Detail View: Expandable cards showing summary and conversation (parsed as User/Assistant messages)
Load (v0.5.2+): Insert handoff content into chat to continue conversation
Delete: Remove handoffs directly from UI

Known Limitations

Note: According to the MCP Apps specification, sendMessage should add messages directly to the conversation and trigger a model response. However, Claude Desktop's current implementation inserts the message into the chat input field instead, requiring the user to press Enter. When you click "Load", the handoff content will be inserted into the input field - press Enter to send it to Claude. This behavior is expected to improve in future Claude Desktop updates.

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_TTL environment variable
Set to 0 to 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
POST	/handoff/merge	Merge multiple handoffs
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)
`HANDOFF_AUDIT`	(disabled)	`true` or `1` to enable audit logging (same as `--audit`)

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

Security

Prompt Injection Protection

The handoff_load output includes security markers to protect against prompt injection attacks:

Warning banner: Alerts AI that content is user-provided and untrusted
Code blocks: User content is wrapped in code blocks to prevent interpretation as instructions
End marker: Clear boundary marking end of user content

This prevents malicious content stored in handoffs from being interpreted as AI instructions.

License

MIT

Author

trust-delta

Conversation Handoff MCP

conversation-handoff-mcp

Features

Installation

Configuration File Locations

Via npm (Recommended)

Local Build

Tools

handoff_save

handoff_list

handoff_load

handoff_clear

handoff_merge (v0.6.0+)

handoff_stats

MCP Apps UI (v0.5.0+)

Features

Known Limitations

Auto-Connect Mode (v0.4.0+)

How It Works

Operating Modes

Memory-Based Storage

Auto-Reconnection

Server Auto-Shutdown (TTL)

MCP Client Configuration

Manual Server Start (Optional)

HTTP Endpoints

Workflow Example

Configuration

Connection Settings (v0.4.0+)

Storage Limits

Configuration Example (Claude Desktop)

Conversation Format

Security

Prompt Injection Protection

License

Author

Resources

Tools

Latest Blog Posts

MCP directory API