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

$3

`bash
npm install -g mcp-session-manager
`

$3

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

Quick Start

$3

`bash


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.

$3

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

$3

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

Configuration

$3

`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"]
}
}
}
`

$3

Customize daemon configurations:

`typescript
{
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:

`bash


Start all daemons

mcp-manager --start-all

Or from source

node dist/manager/index.js --start-all
`

$3

| 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

$3

`bash
curl http://localhost:3199/status
`

$3

`bash


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
`

$3

1. Check if port is already in use:
`bash
# Windows
netstat -ano | findstr :3100

# macOS/Linux
lsof -i :3100
`

2. Remove stale lock files:
`bash
# Windows
del %USERPROFILE%\.mcp-session-manager\*.lock

# macOS/Linux
rm ~/.mcp-session-manager/*.lock
`

$3

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

$3

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

$3

`powershell


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
`

$3

`bash


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