Conversation Handoff MCP

What conversation-handoff-mcp MCP server does

The conversation-handoff-mcp MCP server provides temporary storage for moving conversation context between AI chats, projects, and compatible MCP clients. It uses a key-based handoff model: one session saves conversation content, and another session can list, search, or load that content later.

Stored content can include a summary, title, tags, project and AI metadata, status information, comments, and the conversation itself. Handoffs use a human-readable Markdown format. Keys and titles may be supplied explicitly or generated automatically from the saved data.

Storage is memory-based. The server does not write handoff files to disk, making it suitable for temporary context transfer rather than durable archival.

How it works

Call handoff_save to create a handoff, then use its key with handoff_load in another project or client. handoff_list returns metadata and summaries without loading complete conversations. handoff_search can find handoffs using tags, text, project, AI, status, and date-range filters.

The default structured format organizes a handoff around decisions, implementation details, code changes, open issues, and next steps. A verbatim option preserves the complete conversation when exact wording matters. For long inputs, save the first portion with handoff_save and add later portions with handoff_append. Chunks are concatenated as provided, including their newlines and separators.

The server also supports optional sender fields such as source project, dispatch ID, and sender agent ID. These values are recorded as metadata rather than interpreted by the server. Loaded content is marked as untrusted content with boundary protections intended to reduce prompt-injection risk.

Setup and configuration

The package can run through npx without a separate installation. MCP client configuration uses the conversation-handoff-mcp package as the server command. The README lists configuration locations for Claude Desktop, Claude Code, Codex CLI, Gemini CLI, Cursor, and ChatGPT Desktop, with each client using its own configuration format.

A global npm installation and a local source build are also documented. A local build requires cloning the repository, installing npm dependencies, running the build script, and pointing the client at the generated dist/index.js file.

Tools and capabilities

Available operations include:

• Save, append, load, list, search, clear, and delete conversation handoffs.
• Merge multiple handoffs chronologically or in a specified sequence.
• Add or remove comments attached to an existing handoff.
• Report storage usage and configured limits with handoff_stats.
• Restart the shared HTTP server with handoff_restart.
• Provide an interactive browsing interface to MCP Apps-compatible clients.

The UI can list handoffs, show details, load content, and delete entries. Clients without MCP Apps support receive the standard JSON responses instead.

Limitations and notes

The default cumulative storage limit is 1 MiB. Conversations larger than roughly 100 KB should be uploaded through repeated handoff_append calls, because a single very large tool argument can trigger XML parsing or encoding failures in Claude Code. The server does not provide durable persistence: restarting it removes all stored handoffs. In Claude Desktop, the MCP Apps load action inserts content into the chat input instead of automatically sending it, so the user must submit the message manually.