MCP server for transferring conversation context between AI chats or different projects within the same AI. - 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 -
Add this skill
npx mdskills install trust-delta/conversation-handoff-mcpWell-documented MCP server enabling conversation context transfer with auto-connect and interactive UI
1# conversation-handoff-mcp23[](https://www.npmjs.com/package/conversation-handoff-mcp)4[](https://opensource.org/licenses/MIT)5[](https://github.com/trust-delta/conversation-handoff-mcp/actions/workflows/ci.yml)6[](https://github.com/anthropics/mcp-apps)78<a href="https://glama.ai/mcp/servers/@trust-delta/conversation-handoff-mcp">9 <img width="380" height="200" src="https://glama.ai/mcp/servers/@trust-delta/conversation-handoff-mcp/badge" />10</a>1112MCP server for transferring conversation context between AI chats or different projects within the same AI.1314[日本語ドキュメント](README.ja.md)1516## Features1718- **Audit Logging (v0.7.0+)**: Optional structured JSONL logging for diagnostics (`--audit` flag)19- **Verbatim Conversation Saving (v0.6.1+)**: AI saves complete conversations without summarization or abbreviation20- **Merge Handoffs (v0.6.0+)**: Combine multiple related handoffs into one unified context21- **MCP Apps UI (v0.5.0+)**: Interactive UI for browsing and managing handoffs on compatible clients22- **Auto-Connect (v0.4.0+)**: Server automatically starts in the background - no manual setup required23- **Auto-Reconnection (v0.4.0+)**: Seamlessly reconnects when server goes down - no manual intervention needed24- **Memory-Based Storage**: Lightweight temporary clipboard design - no files written to disk25- **Common Format**: Human-readable Markdown format26- **Lightweight API**: Returns only summaries when listing to save context27- **Auto-Generated Keys (v0.4.0+)**: Key and title are now optional in `handoff_save`2829## Installation3031Works with Claude Desktop, Claude Code, Codex CLI, Gemini CLI, and other MCP clients.3233### Configuration File Locations3435| Client | Config File |36|--------|-------------|37| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |38| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |39| Claude Code | `~/.claude/settings.json` |40| Codex CLI | `~/.codex/config.toml` |41| Gemini CLI | `~/.gemini/settings.json` |42| Cursor | `~/.cursor/mcp.json` |43| ChatGPT Desktop | In-app settings (Developer Mode) |4445### Via npm (Recommended)4647No pre-installation required - runs via npx.4849```json50{51 "mcpServers": {52 "conversation-handoff": {53 "command": "npx",54 "args": ["-y", "conversation-handoff-mcp"]55 }56 }57}58```5960For global installation:6162```bash63npm install -g conversation-handoff-mcp64```6566### Local Build6768```bash69git clone https://github.com/trust-delta/conversation-handoff-mcp.git70cd conversation-handoff-mcp71npm install72npm run build73```7475MCP configuration:7677```json78{79 "mcpServers": {80 "conversation-handoff": {81 "command": "node",82 "args": ["/path/to/conversation-handoff-mcp/dist/index.js"]83 }84 }85}86```8788> **Note**: Codex CLI uses TOML format. See [Codex MCP documentation](https://developers.openai.com/codex/mcp/) for details.8990## Tools9192### handoff_save9394Save 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+).9596```text97// With explicit key and title98handoff_save(99 key: "project-design",100 title: "Project Design Discussion",101 summary: "Decided on MCP server design approach",102 conversation: "## User\nQuestion...\n\n## Assistant\nAnswer..."103)104105// Auto-generated key and title (v0.4.0+)106handoff_save(107 summary: "Decided on MCP server design approach",108 conversation: "## User\nQuestion...\n\n## Assistant\nAnswer..."109)110// → key: "handoff-20241208-143052-abc123" (timestamp + random)111// → title: "Decided on MCP server design approach" (from summary)112```113114### handoff_list115116Get list of saved handoffs (summaries only).117118```text119handoff_list()120```121122### handoff_load123124Load full content of a specific handoff.125126```text127handoff_load(key: "project-design")128handoff_load(key: "project-design", max_messages: 10) // Last 10 messages only129```130131### handoff_clear132133Delete handoffs.134135```text136handoff_clear(key: "project-design") // Specific key137handoff_clear() // Clear all138```139140### handoff_merge (v0.6.0+)141142Merge multiple related handoffs into one. Useful for combining discussions from separate sessions.143144```text145// Merge two handoffs (chronological order by default)146handoff_merge(keys: ["session-1", "session-2"])147148// With custom key and delete sources149handoff_merge(150 keys: ["design-v1", "design-v2", "design-v3"],151 new_key: "design-final",152 new_title: "Final Design Document",153 delete_sources: true,154 strategy: "sequential"155)156```157158| Parameter | Required | Default | Description |159|-----------|----------|---------|-------------|160| `keys` | Yes | - | Array of handoff keys to merge (min 2) |161| `new_key` | No | auto | Key for merged handoff |162| `new_title` | No | auto | Title for merged handoff |163| `new_summary` | No | auto | Summary for merged handoff |164| `delete_sources` | No | `false` | Delete source handoffs after merge |165| `strategy` | No | `"chronological"` | `"chronological"` (by creation time) or `"sequential"` (array order) |166167### handoff_stats168169Check storage usage and limits.170171```text172handoff_stats()173```174175## MCP Apps UI (v0.5.0+)176177For MCP Apps-compatible clients, `handoff_list` automatically opens an interactive UI. Non-compatible clients receive the standard JSON response.178179### Features180181- **List View**: Card-based list showing title, source AI, and date182- **Detail View**: Expandable cards showing summary and conversation (parsed as User/Assistant messages)183- **Load (v0.5.2+)**: Insert handoff content into chat to continue conversation184- **Delete**: Remove handoffs directly from UI185186### Known Limitations187188> **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.189190## Auto-Connect Mode (v0.4.0+)191192Starting with v0.4.0, the server **automatically starts in the background** when an MCP client connects. No manual setup required!193194### How It Works195196```197[User launches Claude Desktop]198 → MCP client starts199 → Scans ports 1099-1200 in parallel for existing server200 → If no server found: auto-starts one in background201 → Connects to server202 → (User notices nothing - it just works!)203204[User launches Claude Code later]205 → MCP client starts206 → Scans ports 1099-1200 in parallel207 → Finds existing server208 → Connects to same server209 → Handoffs are shared!210```211212### Operating Modes213214| Mode | When | Behavior |215|------|------|----------|216| Auto-Connect (default) | No `HANDOFF_SERVER` set | Discovers or auto-starts server |217| Explicit Server | `HANDOFF_SERVER=http://...` | Connects to specified URL |218| Standalone | `HANDOFF_SERVER=none` | No server, in-memory only |219220### Memory-Based Storage221222Handoff data is stored **in memory only**:223224- Data is shared across all connected MCP clients via the HTTP server225- Data is lost when the server process stops226- No files are written to disk - lightweight and clean227- Perfect for temporary context sharing during active sessions228- **FIFO Auto-Cleanup**: When limit is reached, oldest handoff is automatically deleted (no errors)229230### Auto-Reconnection231232When the shared server goes down during operation:233234```235[Server stops unexpectedly]236 → User calls handoff_save()237 → Request fails (connection refused)238 → Auto-reconnection kicks in:239 → Rescan ports 1099-1200 for existing server240 → If found: connect to it241 → If not found: start new server in background242 → Retry the original request243 → User sees success (transparent recovery!)244```245246- Configurable retry limit via `HANDOFF_RETRY_COUNT` (default: 30)247- On final failure: outputs pending content for manual recovery248- Other MCP clients automatically discover the new server on their next request249250### Server Auto-Shutdown (TTL)251252The server automatically shuts down after a period of inactivity:253254- Default: 24 hours of no requests255- Configurable via `HANDOFF_SERVER_TTL` environment variable256- Set to `0` to disable auto-shutdown257- Next MCP client request will auto-start a new server258259### MCP Client Configuration260261**Standard configuration (recommended)** - Just works with auto-connect:262263```json264{265 "mcpServers": {266 "conversation-handoff": {267 "command": "npx",268 "args": ["-y", "conversation-handoff-mcp"]269 }270 }271}272```273274**Specify custom server:**275276```json277{278 "mcpServers": {279 "conversation-handoff": {280 "command": "npx",281 "args": ["-y", "conversation-handoff-mcp"],282 "env": {283 "HANDOFF_SERVER": "http://localhost:3000"284 }285 }286 }287}288```289290**Force standalone mode (no server):**291292For 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.293294```json295{296 "mcpServers": {297 "conversation-handoff": {298 "command": "npx",299 "args": ["-y", "conversation-handoff-mcp"],300 "env": {301 "HANDOFF_SERVER": "none"302 }303 }304 }305}306```307308### Manual Server Start (Optional)309310If you prefer manual control:311312```bash313# Default port (1099)314npx conversation-handoff-mcp --serve315316# Custom port317npx conversation-handoff-mcp --serve --port 3000318```319320### HTTP Endpoints321322| Method | Path | Description |323|--------|------|-------------|324| POST | /handoff | Save a handoff |325| POST | /handoff/merge | Merge multiple handoffs |326| GET | /handoff | List all handoffs |327| GET | /handoff/:key | Load a specific handoff |328| DELETE | /handoff/:key | Delete a specific handoff |329| DELETE | /handoff | Delete all handoffs |330| GET | /stats | Get storage statistics |331| GET | / | Health check |332333### Workflow Example334335**Scenario: Design discussion in Claude Desktop → Implementation in Claude Code**3363371. **In Claude Desktop** - Have a design discussion:338 ```339 User: Let's design an authentication system for my app.340341 Assistant: I recommend using JWT with refresh tokens...342 [detailed discussion continues]343 ```3443452. **Save the conversation** - When ready to hand off:346 ```347 User: Save this conversation for implementation in Claude Code.348349 Assistant: (calls handoff_save)350 ✅ Handoff saved with key: "auth-design-20241208"351 ```3523533. **In Claude Code** - Load and continue:354 ```355 User: Load the auth design discussion.356357 Assistant: (calls handoff_load)358 # Handoff: Authentication System Design359 [Full conversation context loaded]360361 I see we discussed JWT with refresh tokens. Let me implement that...362 ```363364**Key Points:**365- The AI automatically formats and saves the conversation366- Context is fully preserved including code snippets and decisions367- No manual copy-paste needed368369> **Note**: The server automatically starts in the background when the first MCP client connects. No manual startup required.370371## Configuration372373Customize behavior via environment variables.374375### Connection Settings (v0.4.0+)376377| Variable | Default | Description |378|----------|---------|-------------|379| `HANDOFF_SERVER` | (auto) | `none` for standalone, or explicit server URL |380| `HANDOFF_PORT_RANGE` | `1099-1200` | Port range for auto-discovery |381| `HANDOFF_RETRY_COUNT` | 30 | Auto-reconnect retry count |382| `HANDOFF_RETRY_INTERVAL` | 10000 | Auto-reconnect interval (ms) |383| `HANDOFF_SERVER_TTL` | 86400000 (24h) | Server auto-shutdown after inactivity (0 = disabled) |384| `HANDOFF_AUDIT` | (disabled) | `true` or `1` to enable audit logging (same as `--audit`) |385386### Storage Limits387388| Variable | Default | Description |389|----------|---------|-------------|390| `HANDOFF_MAX_COUNT` | 100 | Maximum number of handoffs |391| `HANDOFF_MAX_CONVERSATION_BYTES` | 1048576 (1MB) | Maximum conversation size |392| `HANDOFF_MAX_SUMMARY_BYTES` | 10240 (10KB) | Maximum summary size |393| `HANDOFF_MAX_TITLE_LENGTH` | 200 | Maximum title length |394| `HANDOFF_MAX_KEY_LENGTH` | 100 | Maximum key length |395396### Configuration Example (Claude Desktop)397398```json399{400 "mcpServers": {401 "conversation-handoff": {402 "command": "npx",403 "args": ["-y", "conversation-handoff-mcp"],404 "env": {405 "HANDOFF_MAX_COUNT": "50",406 "HANDOFF_MAX_CONVERSATION_BYTES": "524288"407 }408 }409 }410}411```412413## Conversation Format414415```markdown416## User417User's message418419## Assistant420AI's response421```422423## Security424425### Prompt Injection Protection426427The `handoff_load` output includes security markers to protect against prompt injection attacks:428429- **Warning banner**: Alerts AI that content is user-provided and untrusted430- **Code blocks**: User content is wrapped in code blocks to prevent interpretation as instructions431- **End marker**: Clear boundary marking end of user content432433This prevents malicious content stored in handoffs from being interpreted as AI instructions.434435## License436437MIT438439## Author440441trust-delta442
Full transparency — inspect the skill content before installing.