Session Collab MCP

Provider-agnostic MCP server for multi-agent / multi-session work: claim files, short working memory, protect paths, and detect conflicts.

Works over stdio or HTTP JSON-RPC with Claude Code, Codex, Grok, Cursor, and other MCP clients. Optional Claude Code packaging: plugin/.

Why

Same machine only — this is not a remote Git lock. Parallel coding sessions on one OS user overwrite each other because there is no shared “work intent.” This server is a local WIP registry: declare files, check conflicts, persist short notes, protect critical paths, then release.

Install

stdio (any MCP client)

{
  "mcpServers": {
    "session-collab": {
      "command": "npx",
      "args": ["-y", "session-collab-mcp@latest"]
    }
  }
}

HTTP + CLI

session-collab-http --host 127.0.0.1 --port 8765
session-collab doctor --base-url http://127.0.0.1:8765

MCP-over-HTTP: POST /mcp. Convenience REST: /v1/* (1:1 with MCP tools). Localhost needs no token; non-local binds require SESSION_COLLAB_HTTP_TOKEN and SESSION_COLLAB_ALLOWED_HOSTS (or --allowed-host). Host/Origin are validated; /health uses the same checks (bearer required when a token is set).

Claude Code plugin

/plugin marketplace add leaf76/session-collab-mcp
/plugin install session-collab@session-collab-plugins

Global: npm install -g session-collab-mcp

Local repo: npm run install:local then point MCP config at dist/cli.js.

Workflow

Use only for non-trivial / multi-session work.

1. collab_session_start — same name+project reuses; restore_context default false
2. collab_claim action=create — batch files; atomic claim-or-block; paths normalized to project_root. check is optional probe-only
3. collab_memory_save — short notes only (≤800 chars, rejected if longer; not a vault)
4. collab_claim action=release then collab_session_end

list / status / claim happy-path are compact unless detail=true.

Mode (collab_config)	Behavior
strict	Block overlapping claims
smart (default)	Claim safe files/symbols; queue blocked ones
bypass	Overlap only with allow_conflicts=true

Prefer symbol-level claims when sharing a file. Overlap returns waiting_for_coordination or partial_claim_created.

Tools

Tool	Purpose
collab_session_start / _end / _list / _update	Register, end, list, heartbeat
collab_config	Conflict mode and auto-release options
collab_status	Snapshot (counts unless detail=true)
collab_claim	create, check, release, list
collab_memory_save / _recall / _clear	Working memory (finding, decision, state, todo, important, context)
collab_protect	register, check, list (plans and created files)

v2.0 breaking changes: MIGRATION.md. Full history: CHANGELOG.md. Security reports: SECURITY.md.

Data

SQLite is per machine / OS user (WAL, offline). Path order:

1. SESSION_COLLAB_DB if set
2. ~/.session-collab/collab.db if it already exists
3. legacy ~/.claude/session-collab/collab.db if it already exists
4. otherwise create ~/.session-collab/collab.db

collab_session_start returns scope: "local-machine" and db_path. Claude Code plugin PreToolUse denies Write/Edit on files claimed by another session (SESSION_COLLAB_HOOK_DISABLE=1 to skip).

Development

Node.js 18+. npm install && npm run build

npm run typecheck
npm run lint
npm run test
npm run test:http      # needs a local listen port
npm run test:release

Optional legacy bundle: SESSION_COLLAB_INCLUDE_LEGACY=true npm run build (not in the v2 tool list).

Related

• lazy-desktop-mcp
• lazy_mobile_mcp
• lazy-media-mcp

License

MIT © leaf76