Content
# MCP Session Manager
[](https://badge.fury.io/js/mcp-session-manager)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
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)
```bash
npm install -g mcp-session-manager
```
### From Source
```bash
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
```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.
### 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`)
```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:
```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
```
### 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
```bash
curl http://localhost:3199/status
```
### View daemon logs
```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
```
### Daemon won't start
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
```
### 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
```bash
curl -X POST http://localhost:3199/stop -d '{"name":"memory"}'
curl -X POST http://localhost:3199/start -d '{"name":"memory"}'
```
### Manual cleanup (Windows)
```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
```
### Manual cleanup (macOS/Linux)
```bash
# Remove lock files
rm ~/.mcp-session-manager/*.lock
# Kill orphaned processes
pkill -f "mcp-session-manager"
```
## Architecture
See [ARCHITECTURE.md](./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](./LICENSE) for details.
## Author
**Daichi Kudo**
- [Cognisant LLC](https://cognisant.io/) - CEO
- [M16 LLC](https://m16-llc.com/) - CTO
## Related Projects
- [Model Context Protocol](https://github.com/anthropics/model-context-protocol)
- [Claude Code](https://claude.ai/code)
- [memory-mcp-sqlite](https://github.com/anthropics/memory-mcp-sqlite)
