# conversation-handoff-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/trust-delta/conversation-handoff-mcp  
**GitHub Stars:** 6  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/conversation-handoff-mcp

## Description
Hand off conversation context between Claude Desktop projects and across MCP clients. Memory-based, no file clutter.

## Tools
Capabilities this server exposes over MCP:

- **handoff_save** — Save a conversation handoff for later retrieval. Use this to pass conversation context to another AI or project.

## Long conversations (>~100KB)
If the conversation is large, **save the first chunk with this tool**, then call `handoff_append` repeatedly with the remaining chunks. Doing one giant `handoff_save` can fail with an XML parse / tool-input error because Claude Code encodes tool arguments as XML internally and very large strings can break that encoding.

## Format Selection
- **structured** (default): Organize content using the template below. Much faster — reduces output tokens to ~5-20% of the original conversation. Best for most handoffs.
- **verbatim**: Save the complete word-for-word conversation. Use only when exact wording matters (e.g., legal text, precise error messages).

## Structured Template (for format="structured")
```
## Key Decisions
- [Decision]: [Rationale]

## Implementation Details
[What was built/changed, with relevant code snippets]

## Code Changes
[Files modified with brief description]

## Open Issues
- [Issue]: [Status/Context]

## Next Steps
- [ ] Action item
```

Omit sections that don't apply. Add custom sections if needed.
- **handoff_list** — List all saved handoffs with summaries. Returns lightweight metadata without full conversation content. Opens interactive UI if supported.
- **handoff_load** — Load a specific handoff by key. Returns full conversation content.
- **handoff_clear** — Clear handoffs. If key is provided, clears only that handoff. Otherwise clears all.
- **handoff_stats** — Get storage statistics and current limits. Useful for monitoring usage.
- **handoff_restart** — Restart the shared HTTP server. Useful when the server is in an unhealthy state. All stored handoffs will be lost (data is in-memory).
- **handoff_merge** — Merge multiple handoffs into one. Combines conversations and metadata from related handoffs into a single unified handoff.
- **handoff_add_comment** — Add a comment or annotation to an existing handoff. Comments are included when loading the handoff.
- **handoff_delete_comment** — Delete a comment from a handoff by its comment ID.
- **handoff_append** — Append a conversation chunk to an existing handoff. Use this to upload long conversations in multiple pieces.

## When to use
- The full conversation is over ~100KB.
- handoff_save fails with an XML parse / tool-input error on a long conversation.

Claude Code encodes tool-call arguments as XML internally; very large `conversation` strings can break that encoding (e.g., when the payload contains tag-like substrings). Splitting the upload into smaller chunks avoids that failure mode.

## How to use
1. Call `handoff_save` first with the initial portion (and all metadata: title, summary, etc.) to create the handoff.
2. Call `handoff_append` repeatedly with subsequent chunks until the full conversation is uploaded.
3. Chunks are concatenated as-is — include any newlines or separators inside each chunk.

The cumulative conversation size must stay within the storage limit (default 1 MiB).
- **handoff_search** — Search handoffs by tags, text query, project, AI, status, or date range. Returns matching handoff summaries without full conversation content. Use this to discover relevant handoffs in multi-agent workflows.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "conversation-handoff-mcp": {
    "command": "npx",
    "args": ["-y","conversation-handoff-mcp"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/conversation-handoff-mcp/readme_