Claude Team MCP

A Model Context Protocol (MCP) server that turns multiple AI coding agents — across Claude Code, Cursor, Codex CLI, Gemini CLI, or any MCP-compatible client — into a coordinated team that chats, debates, remembers, audits security, and works in parallel on the same project.

Overview

Most AI coding assistants work one terminal at a time. Claude Team MCP lets several agents run side by side and behave like a real software team: a Project Manager hands out tasks, a Backend and Frontend engineer build in parallel, a QA agent reviews — and they talk to each other through a shared channel while it happens.

Beyond simple messaging, agents can debate a decision (propose → critique → revise → a judge decides), share a persistent project memory, spawn and close their own terminal windows, and maintain a self-contained "second brain" knowledge graph on disk.

Everything is coordinated through a single shared state file, so any number of clients — even different CLIs — that point at the same file join the same world.

It also ships with a built-in MCP Hub / Gateway: one server that acts as a router/proxy for other tools. Register downstream MCP servers and REST APIs as "targets", and any agent connects once to the hub to reach all of them — with credentials held centrally (agents never see the keys), unified tool discovery, per-agent rate limits, a central audit trail, and routing rules. An Auto-Adapter Generator turns any OpenAPI/Swagger spec into a ready-to-run MCP server, so wrapping a new API takes seconds instead of hand-writing an adapter.

Why it exists

A single agent has one perspective and one context window. Real engineering work benefits from division of labor, review, and disagreement. This project provides the missing coordination layer so independent agents can:

• divide work and track it on a shared board,

• communicate in real time without manual copy-paste,

• argue toward the right solution instead of accepting the first idea,

• preserve decisions and knowledge across sessions (saving tokens), and

• scale up or down by opening/closing agent terminals on demand.

Features

• Team coordination — a shared chat channel and task board every agent can see.

• Live conversation — wait_for_message blocks until a new message arrives, so agents converse in real time instead of polling.

• Structured debate — agents submit proposals, critique each other with explicit agree/disagree + reasoning, revise only on sound arguments, and a judge issues the final verdict (research-backed propose → critique → revise → judge pattern).

• Project memory — notes, key-value facts, progress summaries, and a timestamped activity log that persist across sessions.

• Token optimization — save a compact summary, clear context, and reload just the summary instead of the full history.

• Auto-spawn terminals (Windows) — an agent can open new agent windows and close them when work is done, with a configurable safety limit.

• Agent availability — finished agents flip to idle automatically and can be re-assigned new work.

• Second brain — a self-contained knowledge graph (notes, links, backlinks, categories, tags, daily journal) stored on disk.

• Concurrency-safe — file locking + atomic writes mean multiple clients can write at once without corrupting or losing data (verified with 200 concurrent writes).

• Multi-CLI — Claude Code, Cursor, Codex CLI, and Gemini CLI all interoperate when pointed at the same state file.

• Reliability — read receipts, health-check pings, automatic state backups + restore, and crash recovery that releases a downed agent's tasks back to the board.

• Workflow engine — task dependencies (auto-blocking), sub-tasks, priorities, skill-based auto-assignment, and reusable workflow templates.

• Live dashboard — a zero-dependency web dashboard showing the board, channel, agents, debate, and timeline, auto-refreshing in your browser.

• Intelligence — meaning-based search across memory, smart task routing, conflict detection, debate scoring, and token-saving context checkpoints.

• Integration — Obsidian export, git branch/commit linking, worktree suggestions, and Slack/Discord/Teams webhooks.

• Security audit — security-role agents can find, triage, fix, and verify vulnerabilities in your own project and produce a report.

• MCP Hub / Gateway — register downstream MCP servers and REST APIs as targets; one hub connection fans out to all of them, with tool discovery (gateway_capabilities), routing rules, and a /gateway dashboard view.

• Unified auth — secrets live in a separate, owner-only (chmod 600) vault; the hub injects them at call time so agents never handle API keys.

• Rate-limiting + audit — per-agent, per-target call limits and a central audit trail (who called what, when, status, latency) — useful for governance and security review.

• Auto-Adapter Generator — point gateway_generate_adapter at an OpenAPI/Swagger spec (inline, file, or URL) and it writes a complete, runnable MCP server and auto-registers it as a hub target.

Requirements

• Python 3.8+

• mcp and filelock

• At least one MCP-compatible client (Claude Code, Cursor, Codex CLI, Gemini CLI, …)

pip install -r requirements.txt

Installation

1. Place team_coordinator.py somewhere stable, e.g. D:\mcp\team_coordinator.py (Windows) or ~/mcp/team_coordinator.py.

2. Install dependencies: pip install mcp filelock.

3. Register the server with your client (see below). For multi-client setups, point every client at the same TEAM_STATE_FILE.

Claude Code

claude mcp add team -s user -- env TEAM_STATE_FILE=D:\mcp\shared_state.json python D:\mcp\team_coordinator.py
claude mcp list

Cursor

mcp.json:

{
  "mcpServers": {
    "team": {
      "command": "python",
      "args": ["D:\\mcp\\team_coordinator.py"],
      "env": { "TEAM_STATE_FILE": "D:\\mcp\\shared_state.json" }
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.team]
command = "python"
args = ["D:\\mcp\\team_coordinator.py"]
env = { TEAM_STATE_FILE = "D:\\mcp\\shared_state.json" }

Gemini CLI

~/.gemini/settings.json (reduce wait_for_message timeout if the client has a short tool timeout):

{
  "mcpServers": {
    "team": {
      "command": "python",
      "args": ["D:\\mcp\\team_coordinator.py"],
      "env": { "TEAM_STATE_FILE": "D:\\mcp\\shared_state.json" }
    }
  }
}

Ready-to-copy versions of these live in the examples/ folder.

Quick start

Open a few terminals in your project and start your agent client in each. Give each one a role:

Terminal 1 — PM

Join the team as role "PM". Add tasks to the board, assign them to Backend and Frontend, then post a message telling everyone to start and wait for replies.

Terminal 2 — Backend

Join as role "Backend". Wait for instructions, do your task, post updates, and mark it done when finished.

Terminal 3 — Frontend

Join as role "Frontend". Wait until the backend API is ready, then build the UI and update your task.

The agents now coordinate through the shared channel and board.

Running a debate

PM: Start a debate on "which database should we use", with Backend and Frontend as debaters and you as judge.

Backend / Frontend: Submit a proposal with reasoning, read the debate, and critique the other proposals — agree or disagree with solid arguments. Revise only if convinced.

PM: Weigh the arguments and call the verdict. The decision becomes a task and is saved to memory.

Tools

The server exposes 94 tools, grouped by purpose.

Team coordination

join_team, post_message, read_channel, wait_for_message, add_task, update_task, view_board

Agent availability

set_status, who_is_free, assign_work

Structured debate

start_debate, submit_proposal, submit_critique, revise_proposal, next_round, get_debate, judge_debate, cast_vote, vote_tally, score_debate

Project memory

save_note, search_notes, set_fact, get_facts, save_summary, load_summary, project_log

Auto-spawn terminals (Windows)

spawn_agent, list_running_agents, close_agent

Second brain

brain_add, brain_search, brain_get, brain_link, brain_backlinks, brain_daily, brain_list

Reliability

acknowledge, read_receipts, ping, backup_now, list_backups, restore_backup, recover_tasks, safe_call

Workflow

set_skills, auto_assign, save_template, list_templates, run_template

Observability

start_dashboard, stop_dashboard, metrics, timeline, export_report

Intelligence

smart_search, suggest_route, check_conflicts, context_checkpoint

Integration

network_info, obsidian_sync, git_link, suggest_worktrees, webhook_notify

Security audit

report_finding, list_findings, get_finding, triage_finding, assign_fix, verify_fix, security_report, start_security_audit

MCP Hub / Gateway

Registry & discovery: gateway_register_rest, gateway_register_mcp, gateway_unregister, gateway_toggle, gateway_list_targets, gateway_describe, gateway_discover, gateway_capabilities Unified auth: gateway_set_credential, gateway_list_credentials, gateway_delete_credential Routing: gateway_add_route, gateway_remove_route, gateway_list_routes, gateway_route Limits & audit: gateway_set_limit, gateway_audit, gateway_usage Proxy & generator: gateway_call_rest, gateway_call_tool, gateway_generate_adapter

Reset

reset_team

Security audit workflow

Beyond building software, the team can audit its own project for vulnerabilities. Spin up security-role agents (SAST auditor, secret hunter, dependency scanner, config auditor), and they record findings on a shared board with severity levels, debate whether each is real, triage them, assign fixes to developer agents, verify the fixes actually hold, and produce a Markdown security report. This is purely defensive — it helps a team find and fix weaknesses in their own codebase.

Security-Lead: start a security audit for this project.
Auditors: scan and report_finding for each issue (with severity + location).
Team: debate which findings are real vs false positives.
Security-Lead: triage, then assign_fix to a developer agent.
Auditor: verify_fix after the fix, then security_report.

MCP Hub / Gateway

Instead of registering a separate MCP server for every technology, register the hub once in your client and let it route to everything else. Other MCP servers and REST APIs become targets; agents reach them all through the hub.

# 1. Store a secret in the vault (agents never see it again)
PM: gateway_set_credential("weather_key", "<your-api-key>")

# 2a. Register a REST API as a target...
PM: gateway_register_rest("weather", "https://api.example.com/v1",
       auth_type="query", auth_name="appid", credential_key="weather_key",
       tags="weather,forecast")

# 2b. ...or register another MCP server as a target
PM: gateway_register_mcp("github", "npx", args="-y @modelcontextprotocol/server-github",
       env='{"GITHUB_TOKEN":"vault:gh_token"}', tags="git,issues")
PM: gateway_discover("github")          # cache its tool list

# 3. Any agent asks the hub what it can do, then calls through it
Backend: gateway_capabilities("weather")
Backend: gateway_call_rest("weather", path="/forecast", query="city=London", agent="Backend")
Backend: gateway_call_tool("github", "create_issue", arguments='{"title":"Bug"}', agent="Backend")

The hub injects the stored credential at call time, enforces a per-agent rate limit, and records every call to a central audit trail (gateway_audit, gateway_usage, and the /gateway dashboard view).

Auto-Adapter Generator

Point it at an OpenAPI/Swagger spec and it writes a complete MCP server — one tool per operation — and registers it as a hub target automatically:

PM: gateway_generate_adapter("https://petstore3.swagger.io/api/v3/openapi.json",
       name="petstore", credential_key="petstore_key")
# -> Generated MCP adapter 'petstore' with N tools -> .../adapters/petstore.py
#    Registered REST target 'petstore'.

The spec argument accepts an inline JSON string, a local file path, or a URL (JSON specs work out of the box; YAML needs PyYAML). See examples/petstore_openapi.json and the gateway quick-start.

Configuration

All settings are environment variables, set when you register the server.

How it works

The server keeps all team state in a single JSON file. Every read is direct; every write happens under a file lock and is written atomically (temp file + rename), so concurrent agents — even in different CLIs — never clobber each other. The second brain lives in its own locked file on disk and is never touched by team resets.

wait_for_message implements lightweight long-polling with adaptive back-off: an agent calling it blocks until a new message appears, giving real-time conversation without busy-waiting.

The hub/gateway keeps its registry, routes, and audit trail in their own locked file (GATEWAY_FILE), separate from team state so it survives reset_team. Secrets live in a separate chmod 600 vault and are referenced by key — they are masked in every tool response and on the dashboard, and injected only at call time. To proxy a downstream MCP server the hub acts as an MCP client: it spawns the server with the resolved credentials, performs the handshake, forwards the call, and logs the result. REST proxying and the adapter generator use only the standard library, so they work even where the MCP client extras are unavailable.

Safety notes

• Auto-spawned agents each consume tokens independently. The MAX_AGENTS limit guards against runaway spawning; raise it deliberately.

• Auto-spawning launches clients with permission prompts skipped so agents can run unattended — only use this in trusted projects.

• To avoid edit conflicts when several agents work in one repository, give each agent its own git worktree; use the MCP board for coordination and worktrees for file isolation.

• Restart your client after changing the server file so new tools load.

Project structure

claude-team-mcp/
├── team_coordinator.py     # the MCP server (all 94 tools, incl. the hub/gateway)
├── requirements.txt
├── examples/               # ready-to-copy client configs + gateway quick-start
│   ├── claude_code.md
│   ├── cursor_mcp.json
│   ├── codex_config.toml
│   ├── gemini_settings.json
│   ├── gateway_quickstart.md
│   └── petstore_openapi.json
├── CHANGELOG.md
├── FEATURES_GUIDE.md
├── LICENSE
└── README.md

Contributing

Issues and pull requests are welcome. Please keep changes backwards-compatible with existing state files where possible, and include a note in CHANGELOG.md.

License

Released under the MIT License.

Author

Shalinda Jayasinghe GitHub: @shalinda-jayasinghe

Note: replace shalinda-jayasinghe above and in the clone URL with your actual GitHub username if it differs.