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