MCP Session Manager

Enables multiple Claude Code sessions to share MCP daemons without SIGINT conflicts.

The Problem

When running multiple Claude Code sessions simultaneously, each new session sends SIGINT to existing MCP processes, causing:

• Session disconnection: New session kills existing session's MCPs
• SQLite conflicts: Multiple processes accessing the same database
• State isolation: In-memory state (file watchers, indexes) not shared
• Resource contention: Process conflicts and crashes

The Solution

This session manager introduces a 3-layer architecture:

Session A                          Session B
    |                                  |
    v                                  v
[Proxy A] -------- HTTP -------- [MCP Daemon]
(stdio)            shared          (HTTP/SSE)
    |                                  |
[Claude A]                        [Claude B]

1. Singleton Daemons: Each MCP runs as a single daemon serving all sessions
2. Stdio Proxies: Lightweight proxies bridge Claude's stdio to daemon HTTP
3. SIGINT Protection: Proxies ignore signals, protecting the shared daemon
4. Auto-start: Daemons start automatically on first request

Installation

From npm (Recommended)

npm install -g mcp-session-manager

From Source

git clone https://github.com/daichi-kudo/mcp-session-manager.git
cd mcp-session-manager
npm install
npm run build

Quick Start

1. Generate Claude Config

# If installed globally
mcp-manager generate-config

# If installed from source
node dist/manager/index.js generate-config

This creates ~/.claude/mcp.json with proxy configurations.

2. Restart Claude Code

Close and reopen Claude Code. The proxies will automatically start daemons as needed.

3. Verify

Open multiple Claude Code sessions - they should all work simultaneously without conflicts.

Configuration

Claude Code (~/.claude/mcp.json)

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["path/to/mcp-session-manager/dist/proxy/index.js", "--target", "memory"]
    },
    "code-index": {
      "command": "node",
      "args": ["path/to/mcp-session-manager/dist/proxy/index.js", "--target", "code-index"]
    },
    "ast-grep": {
      "command": "node",
      "args": ["path/to/mcp-session-manager/dist/proxy/index.js", "--target", "ast-grep"]
    }
  }
}

Daemon Settings (src/shared/config.ts)

Customize daemon configurations:

{
  name: "memory",
  command: "node",
  args: ["path/to/memory-mcp-sqlite/dist/index.js", "--transport", "http", "--port", "3100"],
  port: 3100,
  transport: "streamable-http",
  env: { MEMORY_DB_PATH: "..." }
}

Ports

Daemon	Default Port	Transport
memory	3100	streamable-http
code-index	3101	streamable-http (SSE response)
ast-grep	3102	sse
Manager API	3199	HTTP

Manual Daemon Management

Start the manager for health monitoring and auto-restart:

# Start all daemons
mcp-manager --start-all

# Or from source
node dist/manager/index.js --start-all

Manager API

Endpoint	Method	Description
/ping	GET	Health check
/status	GET	All daemon statuses
/start	POST	Start a daemon ({"name": "memory"})
/stop	POST	Stop a daemon
/ensure	POST	Ensure daemon running (start if needed)
/start-all	POST	Start all daemons
/stop-all	POST	Stop all daemons

Troubleshooting

Check daemon status

curl http://localhost:3199/status

View daemon logs

# Windows
type %USERPROFILE%\.mcp-session-manager\memory.log
type %USERPROFILE%\.mcp-session-manager\code-index.log

# macOS/Linux
cat ~/.mcp-session-manager/memory.log
cat ~/.mcp-session-manager/code-index.log

Daemon won't start

1. Check if port is already in use:

   # Windows
   netstat -ano | findstr :3100
   
   # macOS/Linux
   lsof -i :3100

2. Remove stale lock files:

   # Windows
   del %USERPROFILE%\.mcp-session-manager\*.lock
   
   # macOS/Linux
   rm ~/.mcp-session-manager/*.lock

Session still disconnects

1. Verify proxy is configured in ~/.claude/mcp.json
2. Check proxy logs in Claude Code's MCP output
3. Ensure daemon is running: curl http://localhost:3100/health

Restart stuck daemon

curl -X POST http://localhost:3199/stop -d '{"name":"memory"}'
curl -X POST http://localhost:3199/start -d '{"name":"memory"}'

Manual cleanup (Windows)

# Remove lock files
Remove-Item $env:USERPROFILE\.mcp-session-manager\*.lock

# Kill orphaned processes
Get-Process node | Where-Object {$_.CommandLine -like "*mcp*"} | Stop-Process -Force

Manual cleanup (macOS/Linux)

# Remove lock files
rm ~/.mcp-session-manager/*.lock

# Kill orphaned processes
pkill -f "mcp-session-manager"

Architecture

See ARCHITECTURE.md for detailed design documentation.

Requirements

• Node.js 20+
• Windows, macOS, or Linux
• Existing MCP servers with HTTP/SSE transport support

Supported MCPs

MCP	Transport	Notes
memory-mcp-sqlite	streamable-http	Requires --transport http flag
code-index-mcp	streamable-http	SSE response, requires FastMCP
ast-grep-mcp	sse	Deprecated MCP 2024-11-05 format

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Author

Daichi Kudo

• Cognisant LLC - CEO
• M16 LLC - CTO

Related Projects

• Model Context Protocol
• Claude Code
• memory-mcp-sqlite