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