mcp-reconnect

mcp-reconnect

Automated MCP server reconnection for Claude Code sessions running in tmux.

Real demo against Claude Code v2.1.150 — actual /mcp menu, actual cursor navigation, actual reconnect. See demo/README.md for how to rebuild.

Current version: v1.2.0

Claude Code has no programmatic API for MCP reconnect — the only way is through the interactive /mcp menu. This tool automates that entire sequence via tmux send-keys, handling single machines, multi-session environments, and remote hosts over SSH.

The Problem

Building MCP servers, you iterate. Edit the server code, restart the process, switch to your Claude Code session, /mcp → arrow down → Enter to reconnect, type the prompt you were working on. Every cycle. This is exactly the loop mcp-reconnect was built for — let the agent reconnect itself so you stay in flow instead of context-switching to drive a menu.

The same pain shows up at fleet scale: deploying new MCP server code or restarting server processes drops the connection on every active Claude Code session. With multiple sessions across multiple machines, manually walking /mcp → Reconnect on each one becomes the bottleneck.

mcp-reconnect handles both cases: one session, your session, every session — local or over SSH.

The Solution

mcp-reconnect drives the /mcp menu programmatically through tmux:

Escape        →  stop active generation
/mcp + Enter  →  submit the /mcp slash command
Enter         →  enter the menu
Down + Enter  →  select "Reconnect" (2nd option)
<prompt>      →  continuation message so Claude resumes work

Install

Standalone script

git clone https://github.com/palios-taey/mcp-reconnect.git
cd mcp-reconnect
sudo make install

This installs mcp-reconnect to /usr/local/bin. To customize:

sudo make install PREFIX=/opt/local

Claude Code plugin

/plugin marketplace add palios-taey/mcp-reconnect
/plugin install mcp-reconnect@mcp-reconnect

Or test locally:

claude --plugin-dir ./path/to/mcp-reconnect

Usage

# Reconnect all Claude Code tmux sessions on this machine
mcp-reconnect

# Reconnect specific sessions by name
mcp-reconnect weaver architect

# Reconnect all sessions on a remote host
mcp-reconnect --remote myserver

# Reconnect a specific session on a remote host
mcp-reconnect --remote myserver weaver

# Preview what would happen (no keys sent)
mcp-reconnect --dry-run

# Select menu items by visible text
mcp-reconnect --path Reconnect
mcp-reconnect --path taeys-hands --path Reconnect
mcp-reconnect --path taeys-hands --path "Show details"

Calling from within Claude Code

When mcp-reconnect is called from a Claude Code session itself (e.g., during a deploy script), it must run detached with a delay — otherwise the Escape keystroke kills the calling session before the bash tool returns.

nohup mcp-reconnect --delay 10 &>/dev/null & disown

The --delay flag waits N seconds before sending any keystrokes, giving the calling session time to finish its tool execution.

Options

Flag	Default	Description
--remote HOST	—	Target a remote machine via SSH
--delay N	0	Wait N seconds before starting (for detached use)
--settle-esc N	5	Seconds to wait after Escape
--settle-mcp N	2	Seconds to wait after /mcp submit
--settle-select N	5	Seconds to wait after selecting Reconnect
--path LABEL	—	Select a visible /mcp menu label; repeat for submenu paths
--server NAME	—	Shorthand for --path NAME --path Reconnect
--message MSG	(built-in)	Override the continuation prompt
--dry-run	—	Show actions without sending keys
--help	—	Show usage information

Path navigation

--path selects /mcp menu items by matching the visible cursor line, using a fixed-string, case-insensitive substring match. Repeat it to walk through nested menu levels:

# Reconnect in Claude Code's single-server menu
mcp-reconnect --path Reconnect

# Multi-server menu: choose a server, then reconnect it
mcp-reconnect --path taeys-hands --path Reconnect

# Choose a different action in the server submenu
mcp-reconnect --path taeys-hands --path "Show details"

--server NAME remains supported as a backwards-compatible shorthand for --path NAME --path Reconnect. --path and --server are mutually exclusive. --path is currently local-only; --path --remote HOST exits with a clear error instead of sending keys.

Requirements

• tmux — Claude Code sessions must be running inside tmux
• bash ≥ 4.0 (for mapfile and associative arrays)
• ssh — for --remote mode, with key-based authentication configured

No other dependencies. No Redis, no Python, no Node.js.

Design Decisions

These constraints were discovered through extensive production testing: