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_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 | | 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

1. 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]

2. 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"

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