mcp-session-registry

Lightweight MCP server for multi-session awareness — lets AI agents know who else is active on the same machine.

Why

When you run multiple AI CLI sessions (Kiro, Claude Code, Gemini CLI) on the same machine, they are blind to each other. This causes:

• File conflicts — two sessions editing the same file
• Duplicated work — agents picking up the same task
• Wasted context — no way to know what another session is doing

mcp-session-registry solves this with a shared presence layer:

• Sessions register on spawn, declare a theme, and heartbeat every 2-3 minutes
• Sessions claim files/resources — other sessions see the claim before touching them
• Stale sessions (no heartbeat >5min) are automatically reaped
• Everything persists in SQLite — survives individual session crashes

Quick Start

# Run directly
uvx mcp-session-registry

# Or install
pip install mcp-session-registry

# Configure port (default: 8000)
MSR_PORT=3203 mcp-session-registry

MCP Tools

How It Works

Session A registers → gets session_id
Session A claims "src/main.py"
Session B calls session_conflicts(["src/main.py"])
  → returns: claimed by Session A (pid 1234, theme "refactor auth")
Session B picks a different file

Sessions that stop sending heartbeats are reaped after 5 minutes — their claims are released automatically.

Configuration

Integration with Kiro CLI

Add to your ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "session-registry": {
      "url": "http://localhost:3203/mcp",
      "autoApprove": ["session_register", "session_list", "session_heartbeat", "session_end", "session_claim", "session_release", "session_conflicts"]
    }
  }
}

Run as a systemd user service:

# ~/.config/systemd/user/session-registry.service
[Unit]
Description=MCP Session Registry

[Service]
ExecStart=%h/.local/bin/mcp-session-registry
Environment=MSR_PORT=3203
Restart=on-failure

[Install]
WantedBy=default.target

Health Check

curl http://localhost:3203/health
# {"status": "healthy", "version": "0.2.0", "uptime_seconds": 3600}

Development

git clone https://github.com/filhocf/mcp-session-registry
cd mcp-session-registry
uv sync
uv run pytest tests/ -v
uv tool run ruff check src/ tests/

License

Apache-2.0