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.

Related MCP server: agent-coord

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.

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

Tools

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