Content
# mcp-multi-agents
A local MCP (Model Context Protocol) server that provides **shared context continuity** across any MCP-compatible AI IDE. When you switch between VS Code + Claude Code, Antigravity, Cursor, or Codex CLI — your memory, project conventions, and active tasks follow you.
---
## The Problem
Every AI IDE session starts cold. Switch from VS Code + Claude Code to Antigravity when you run out of tokens, and the new session has no idea:
- What you were working on
- What decisions you made
- What files you touched
- What your project's conventions are (CLAUDE.md)
- What tasks are in progress
This project solves all of that.
---
## How It Works
```
┌─────────────────────────────────────────────────────────────┐
│ Shared Storage Layer │
│ │
│ ~/.claude-mem/claude-mem.db ← memory observations │
│ ~/.mcp-agents/handoffs.json ← session checkpoints │
│ ~/.mcp-agents/tasks.json ← persistent task list │
│ ~/project/CLAUDE.md ← project conventions │
└─────────────────────────────────────────────────────────────┘
↑ ↑ ↑
claude-mem MCP mcp-multi-agents filesystem
(existing plugin) (this project) (always shared)
↑ ↑
┌──────┴───┐ ┌──────┴────────┐
│ VS Code │ │ Antigravity │
│ Cursor │ │ Codex CLI │
└──────────┘ └───────────────┘
```
Both of the above MCP servers are connected simultaneously by each IDE. They communicate with the **same background worker** (`127.0.0.1:37777`) and read/write the **same files**, so context is shared without any syncing.
---
## Prerequisites
- **Node.js 18+** — `node --version`
- **claude-mem plugin** — must be installed globally in Claude Code
- Verify: `~/.claude-mem/claude-mem.db` exists and `~/.claude-mem/worker.pid` is present when Claude Code is running
- **npm** — for installing dependencies
---
## Installation
```bash
cd /home/konsing/mcp-multi-agents
npm install
npm run build
```
That's it. The server binary is now at `dist/index.js`.
---
## MCP Tools Reference
### `session_start`
The most important tool. Call it at the **start of any session** in any IDE. Returns a full context snapshot in a single call.
**Input:**
```json
{ "project_path": "/absolute/path/to/project" }
```
**Returns:**
- Last handoff checkpoint (what the previous session was working on)
- Last 5 recent claude-mem observations for the project
- All active tasks
- Full CLAUDE.md content (all files from project root up to `~/.claude/CLAUDE.md`)
**Example prompt for any IDE:**
> "Call session_start with project_path `/home/konsing/my-project` and tell me what context you find."
---
### `handoff_save`
Checkpoint your current state **before closing a session or switching IDEs**. The more detail you provide, the faster the next session ramps up.
**Input:**
```json
{
"project_path": "/home/konsing/my-project",
"current_task": "Implementing the OAuth callback handler in src/auth.ts",
"recent_files": ["src/auth.ts", "src/routes/callback.ts", "tests/auth.test.ts"],
"decisions": [
"Using PKCE flow instead of implicit for security",
"Token storage in httpOnly cookies, not localStorage"
],
"next_steps": [
"Write tests for the token refresh logic",
"Update CLAUDE.md with the auth architecture decision"
],
"ide_source": "vscode-claude"
}
```
Saves to:
1. `~/.mcp-agents/handoffs.json` (always, instant)
2. claude-mem as a "decision" observation (best-effort, requires worker running)
---
### `handoff_load`
Load the most recent checkpoint for a project without calling `session_start`. Useful when you just want the handoff without the full context dump.
**Input:**
```json
{ "project_path": "/home/konsing/my-project" }
```
---
### `read_project_context`
Read all CLAUDE.md files for a project. Walks up the directory tree collecting every CLAUDE.md it finds, then appends `~/.claude/CLAUDE.md` (global defaults).
**Input:**
```json
{ "project_path": "/home/konsing/my-project" }
```
**Why this matters:** Claude Code automatically reads CLAUDE.md files. Antigravity, Cursor (without configuration), and Codex CLI do not. This tool bridges that gap — call it at session start in any non-Claude-Code IDE to inject your project conventions.
---
### `list_tasks`
List persistent tasks. Tasks survive session ends, IDE switches, and reboots.
**Input:**
```json
{
"project_path": "/home/konsing/my-project",
"status": "active"
}
```
`status` options: `"active"` (default), `"completed"`, `"all"`
---
### `create_task`
Create a task visible in all IDEs.
**Input:**
```json
{
"project_path": "/home/konsing/my-project",
"title": "Add rate limiting to the API",
"description": "Use sliding window algorithm, limit to 100 req/min per user"
}
```
---
### `update_task`
Update a task's title, description, or status.
**Input:**
```json
{
"id": "uuid-from-list-tasks",
"status": "completed"
}
```
---
## IDE Setup
### VS Code + Claude Code
Claude Code auto-discovers `.mcp.json` files. The file already exists in this project root:
```json
{
"mcpServers": {
"mcp-multi-agents": {
"type": "stdio",
"command": "node",
"args": ["/home/konsing/mcp-multi-agents/dist/index.js"]
}
}
}
```
For a **project that isn't this repo**, add the same `.mcp.json` to that project's root, or add it to your global Claude Code settings at `~/.claude/settings.json` under `mcpServers`.
After adding: run `/reload-plugins` in Claude Code or restart the session.
**Note:** claude-mem is already active globally via the plugin system — you do not need to add it manually.
---
### Antigravity
Open Antigravity's MCP server settings and add both entries from `antigravity-mcp.json`:
```json
{
"mcpServers": {
"mcp-multi-agents": {
"command": "node",
"args": ["/home/konsing/mcp-multi-agents/dist/index.js"]
},
"claude-mem": {
"command": "node",
"args": [
"/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/mcp-server.cjs"
],
"env": {
"CLAUDE_PLUGIN_ROOT": "/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3"
}
}
}
}
```
**Important for Antigravity (Gemini):** At the start of every session, tell the AI:
> "Call `session_start` with `project_path` set to the current project directory."
Antigravity does not auto-read CLAUDE.md or auto-trigger lifecycle hooks, so `session_start` is how it gets bootstrapped.
---
### Cursor (with Claude Opus 4.6 / thinking models)
Cursor uses the same `.mcp.json` format as Claude Code. You have two options:
**Option A — Project-level** (recommended): Create `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"mcp-multi-agents": {
"command": "node",
"args": ["/home/konsing/mcp-multi-agents/dist/index.js"]
},
"claude-mem": {
"command": "node",
"args": [
"/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/mcp-server.cjs"
],
"env": {
"CLAUDE_PLUGIN_ROOT": "/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3"
}
}
}
}
```
**Option B — Global**: Create `~/.cursor/mcp.json` with the same content to apply to all projects.
**Using Claude Opus 4.6 with thinking in Cursor:** In Cursor's model selector, choose `claude-opus-4-6` (or whichever identifier Cursor uses for it). Extended thinking is enabled per-model in Cursor's settings. The MCP tools work identically regardless of which Claude model or thinking budget is active — the model orchestrates tool calls, the server just handles them.
---
### OpenAI Codex CLI
Codex CLI uses **TOML** format at `~/.codex/config.toml` (global) or `.codex/config.toml` (project-scoped, trusted projects only).
**Add to `~/.codex/config.toml`:**
```toml
[[mcp_servers]]
name = "mcp-multi-agents"
command = "node"
args = ["/home/konsing/mcp-multi-agents/dist/index.js"]
[[mcp_servers]]
name = "claude-mem"
command = "node"
args = ["/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/mcp-server.cjs"]
[mcp_servers.env]
CLAUDE_PLUGIN_ROOT = "/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3"
```
Or use the Codex CLI to add it interactively:
```bash
codex mcp add
```
**Note on claude-mem with Codex:** claude-mem's background worker (`~/.claude-mem/worker.pid`) is only auto-started by Claude Code's `SessionStart` hook. When using Codex CLI without Claude Code running, the worker may not be active. The `mcp-multi-agents` server handles this gracefully — `session_start` will still return handoffs, tasks, and CLAUDE.md content; only the recent observations section will be skipped. To manually start the worker:
```bash
node ~/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/bun-runner.js \
~/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/worker-service.cjs start
```
---
## Typical Session Workflow
### Switching from VS Code → Antigravity
**In VS Code (before closing):**
```
You: "Save a handoff — I'm switching to Antigravity."
Claude: [calls handoff_save with current task, files, decisions, next steps]
```
**In Antigravity (after opening):**
```
You: "Call session_start for /home/konsing/my-project"
Gemini: [calls session_start, returns full context snapshot]
→ Shows: last handoff, recent memory, active tasks, CLAUDE.md
```
You're immediately up to speed — no re-explaining.
---
### Starting Fresh in Any IDE
```
You: "Call session_start for this project before we begin."
AI: [returns full context]
You: "Now let's continue where we left off."
```
---
### Managing Tasks Across Sessions
```
# Create a task in VS Code
You: "Create a task: implement OAuth refresh token rotation"
Claude: [calls create_task]
# See it 2 days later in Cursor
You: "What tasks are active for this project?"
Claude: [calls list_tasks] → shows the task created in VS Code
# Complete it in Antigravity
You: "Mark the OAuth task as complete"
Gemini: [calls update_task with status: "completed"]
```
---
## Storage & Data
| What | Where | Format |
|------|-------|--------|
| Handoff checkpoints | `~/.mcp-agents/handoffs.json` | JSON, last 50 kept |
| Tasks | `~/.mcp-agents/tasks.json` | JSON |
| Memory observations | `~/.claude-mem/claude-mem.db` | SQLite (managed by claude-mem) |
| Vector embeddings | `~/.claude-mem/chroma/` | ChromaDB (managed by claude-mem) |
| Project conventions | `<project>/CLAUDE.md` | Markdown |
| Global conventions | `~/.claude/CLAUDE.md` | Markdown |
All storage is local — nothing leaves your machine.
---
## Troubleshooting
**"No handoff found"** — Either no handoff was saved before the previous session ended, or `project_path` doesn't match exactly (use the absolute path).
**"claude-mem worker not running"** — The worker is started by Claude Code's SessionStart hook. If you're using a non-Claude-Code IDE as your primary, start the worker manually (see Codex CLI section above).
**"MCP server not showing up in IDE"** — Check that `dist/index.js` exists (`npm run build` in project root). Test with:
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' \
| node /home/konsing/mcp-multi-agents/dist/index.js
# Should print a JSON response with serverInfo.name = "mcp-multi-agents"
```
**"Cursor shows the server but tools fail"** — Cursor may need the `type: "stdio"` field explicitly in `.cursor/mcp.json`. Add `"type": "stdio"` to the server config object.
**Rebuilding after changes:**
```bash
cd /home/konsing/mcp-multi-agents
npm run build
```
MCP servers are spawned fresh per session, so no restart is needed after rebuilding — the next IDE session will use the new binary.
---
## Development
```
src/
├── index.ts # Server entry point, tool registration
├── types.ts # Shared TypeScript interfaces
├── tools/
│ ├── session.ts # session_start
│ ├── handoff.ts # handoff_save, handoff_load
│ ├── context.ts # read_project_context
│ └── tasks.ts # list_tasks, create_task, update_task
└── services/
├── claudemem.ts # HTTP client → claude-mem worker (:37777)
├── claudemd.ts # CLAUDE.md filesystem walker
├── handoffstore.ts # Handoff JSON persistence
└── taskstore.ts # Task JSON persistence
```
Adding a new tool: implement it in `src/tools/`, call `registerYourTools(server)` in `src/index.ts`, rebuild.
---
## Compatible IDEs
| IDE | MCP Config File | Transport | Notes |
|-----|----------------|-----------|-------|
| VS Code + Claude Code | `.mcp.json` | stdio | claude-mem auto-active via plugin |
| Antigravity | IDE settings UI | stdio | Add both servers manually |
| Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` | stdio, SSE, HTTP | Supports Claude Opus 4.6 with thinking |
| Codex CLI | `~/.codex/config.toml` or `.codex/config.toml` | stdio only | claude-mem worker needs manual start |
| Any MCP client | — | stdio | Server is standard MCP — works with anything |
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available