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.
• SSRF guard — the hub refuses private, loopback, and link-local destinations by default, at registration, at call time, and on every redirect hop, so an agent cannot point it at cloud instance metadata.
• Self-check — claude-team-mcp doctor reports SDK versions, path writability, vault permissions, and guard settings, each with the fix attached.

Requirements

• Python 3.10+
• mcp and filelock
• At least one MCP-compatible client (Claude Code, Cursor, Codex CLI, Gemini CLI, …)

pip install -r requirements.txt

Both mcp SDK lines are supported: 1.x exposes the server class as FastMCP, 2.x renamed it to MCPServer, and the server imports whichever is installed. Run claude-team-mcp doctor to see which one is in use.

Installation

Option A — install as a package (recommended)

Install straight from GitHub; this pulls in the dependencies and gives you a claude-team-mcp command you can register with any client:

pip install git+https://github.com/shalinda-j/Claude-Team-MCP.git
claude-team-mcp   # starts the MCP server on stdio

Then register the command with your client, e.g. for Claude Code:

claude mcp add team -s user -- env TEAM_STATE_FILE=~/mcp/shared_state.json claude-team-mcp

Option B — run from a copy of the file

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

Diagnostics

doctor

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.

Variable	Default	Purpose
TEAM_STATE_FILE	D:/mcp/shared_state.json (Windows) / ~/.claude_team_state.json	Shared state path. Use the same value for every client.
BRAIN_DIR	D:/mcp/second_brain (Windows) / ~/.claude_team_brain	Where the second brain is stored.
MAX_AGENTS	6	Auto-spawn safety limit.
AGENT_STALE_SECONDS	300	Idle time before an agent is marked offline.
MSG_ROTATE_LIMIT	2000	Channel size before old messages are archived out.
LOG_ROTATE_LIMIT	2000	Activity-log size cap.
GATEWAY_FILE	<state dir>/gateway.json	Hub registry/routes/audit (kept out of team state and resets).
GATEWAY_VAULT_FILE	<state dir>/gateway_vault.json	Secret vault (written chmod 600).
ADAPTER_DIR	<state dir>/adapters	Where gateway_generate_adapter writes generated servers.
GATEWAY_RATE_PER_MIN	60	Default per-agent, per-target call limit.
GATEWAY_AUDIT_LIMIT	2000	Gateway audit-trail size cap.
GATEWAY_CALL_TIMEOUT	30	Timeout (s) for proxied REST calls.
GATEWAY_MAX_OPS	150	Max operations generated from one OpenAPI spec.
GATEWAY_ALLOW_PRIVATE	unset	Set to 1 to let the hub reach private/loopback/link-local addresses (see SSRF guard).
GATEWAY_ALLOWED_HOSTS	unset	Comma-separated allowlist; when set, the hub reaches only these hosts and their subdomains.
TEAM_OPERATOR_TOKEN	unset	Required to register targets or write vault keys (see operator gate).
DASHBOARD_TOKEN	random per run	Token the dashboard requires; set it to keep one URL across restarts.

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.

Troubleshooting

Run the self-check before anything else:

claude-team-mcp doctor          # installed as a package
python team_coordinator.py doctor   # running from a file copy

It reports the Python and mcp SDK versions (and which API the server bound to), whether filelock is present, whether every path it writes to is writable, the vault's file permissions, and the SSRF guard's current mode — each with the fix attached. It exits non-zero if anything is broken, so it can be dropped into a setup script. doctor is also available as an MCP tool, so an agent can diagnose its own environment.

Dashboard access

Breaking in v8.6. The dashboard now requires a token. Open the whole URL that start_dashboard prints — it carries ?t=<token>.

The dashboard serves the full channel, the task board, security findings, and the gateway's vault key names. It used to serve all of that to anyone who could reach the port, and answered the JSON endpoints with Access-Control-Allow-Origin: * — so binding to 127.0.0.1 bought nothing: any page open in your browser could fetch('http://127.0.0.1:8765/api/state') cross-origin and read the lot.

start_dashboard now mints a random token per run and returns it in the URL:

Dashboard live at http://localhost:8765/?t=Xk3f… — open that whole URL

The token can also be sent as an X-Dashboard-Token header. Set DASHBOARD_TOKEN in the environment to keep one URL across restarts. The wildcard CORS header is gone, responses carry no-store, nosniff, X-Frame-Options: DENY and a CSP whose connect-src 'self' means an injected payload has nowhere to send what it reads, and unknown paths 404 instead of returning the dashboard.

Output escaping was tightened at the same time: role, assignee, and judge_role reached innerHTML unescaped, and esc() did not escape quotes, so any escaped value sitting in an attribute was still injectable. Both are fixed, and the tests render the page's real expressions to check the produced markup rather than trusting that the template says esc().

Binding to 0.0.0.0 still works for LAN viewing, but it is plain HTTP — the token crosses the network in the clear, so only do it on a network you trust.

Operator gate and credential binding

Breaking in v8.5. Registering targets and writing vault keys now need an operator token. If you use the hub, set TEAM_OPERATOR_TOKEN before upgrading.

The vault's promise is that agents never see the keys. Two things broke it.

gateway_register_mcp takes a command and arguments and the hub spawns them, so any agent that could call it could run anything as the hub user. And a credential was usable by whatever target named it — so an agent could register a target pointing at a host it controlled, reference a key it had no business touching, and read the secret straight out of the response.

The attacker to picture here is not a rogue operator. It is text: an agent summarising a web page, reading an issue, or following a spec, steered into calling a tool you never asked for. So the boundary is between you did this and the agent decided to.

Operator token. Set it in the server's environment:

claude mcp add team -s user -- env TEAM_STATE_FILE=~/mcp/shared_state.json \
  TEAM_OPERATOR_TOKEN='a secret you choose' claude-team-mcp

These tools then require operator_token: gateway_register_rest, gateway_register_mcp, gateway_unregister, gateway_toggle, gateway_set_credential, gateway_delete_credential, gateway_generate_adapter. Everything else — chat, board, debate, memory, and calling targets that already exist — is unchanged and needs nothing.

You hand the token over for the turn in which you want a registration to happen. Injected text cannot supply a token it has never seen. Honest limit: once you paste it, that agent has it for the rest of the session and could reuse it. This bounds spontaneous and injected action, not a fully compromised agent — rotate the token if you think one has been.

With no token set, the gated tools stay closed and say how to open them.

Credential binding. A key declares which targets may use it:

gateway_set_credential(key="stripe_key", value="sk_live_...",
                       targets="stripe,billing", operator_token="...")

A target not on the list is refused at call time, and the refusal is audited. targets="*" restores the old any-target behaviour, and has to be said out loud. Keys stored before this existed keep working; doctor lists them so you can bind them deliberately rather than leaving them open by accident.

gateway_generate_adapter also writes only inside ADAPTER_DIR now — out_path was unconstrained, and the file's contents come from a spec that is usually fetched over the network.

SSRF guard

The hub fetches URLs that agents supply, from the hub's own network position and with the hub's stored credentials available for injection. Left open, an agent that registered http://169.254.169.254/ would turn the gateway into a proxy for cloud instance metadata.

So private, loopback, and link-local destinations are refused by default, at target registration, at call time (which also covers targets registered by an older version), when the adapter generator fetches a spec by URL, and on every redirect hop — a public URL that 302s to an internal address is refused too. Hostnames are checked against every address they resolve to, so a name with one public and one internal record does not slip through.

Two escape hatches, for when reaching an internal service is the actual intent:

GATEWAY_ALLOW_PRIVATE=1                              # allow private/loopback again
GATEWAY_ALLOWED_HOSTS=api.stripe.com,internal.corp   # or pin to an explicit allowlist

GATEWAY_ALLOWED_HOSTS matches a host exactly or as a subdomain, permits the hosts it names even when they are internal, and refuses everything else.

Because the check resolves DNS to judge a destination, a name that changes between the check and the connection (DNS rebinding) is not fully covered; closing that would mean pinning the resolved address into the socket.

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 96 tools, incl. the hub/gateway)
├── pyproject.toml          # packaging: pip install => `claude-team-mcp` command
├── requirements.txt
├── tests/                  # pytest suite (state, team, tasks, debate, gateway, …)
├── .github/workflows/
│   ├── ci.yml              # CI: Linux + Windows, Python 3.10–3.13, both mcp SDK lines
│   └── mirror-gitlab.yml   # optional: auto-mirror main to GitLab
├── .gitlab-ci.yml          # GitLab CI/CD: same tests + package build
├── examples/               # ready-to-copy client configs + gateway quick-start
│   ├── claude_code.md
│   ├── cursor_mcp.json
│   ├── codex_config.toml
│   ├── gemini_settings.json
│   ├── gateway_quickstart.md
│   ├── gitlab_setup.md
│   └── petstore_openapi.json
├── CHANGELOG.md
├── FEATURES_GUIDE.md
├── LICENSE
└── README.md

Development & testing

git clone https://github.com/shalinda-j/Claude-Team-MCP.git
cd Claude-Team-MCP
pip install -e .[dev]
pytest

The suite (161 tests) covers the state layer (atomic writes, rotation, backups), team coordination, the task board and workflows, project memory and the second brain, structured debate, security findings, the intelligence layer, the MCP hub/gateway (targets, vault, routing, rate limits, adapter generator), the SSRF guard, the doctor self-check, and concurrent multi-writer safety. Tests run against per-test temp directories and never touch your real state files, and make no network or DNS calls.

CI runs the suite on every push and pull request across Python 3.10–3.13 on Linux plus a Windows leg, on a weekly schedule, and against both mcp SDK lines pinned explicitly — so a dependency release that breaks the server is caught here rather than by the next person to run pip install.

GitLab CI/CD

A GitLab pipeline ships too (.gitlab-ci.yml): the full test matrix on Python 3.10–3.13 plus a package-build job with wheel artifacts. The two mcp SDK compatibility legs and the doctor smoke step are GitHub-only for now, so GitLab covers the suite but not the dependency matrix. It works on gitlab.com or any self-hosted instance with Docker runners — push the repo to a GitLab project and the pipeline runs with zero configuration. To keep GitLab in sync with GitHub automatically, enable the bundled mirror-gitlab.yml workflow (set one variable + one token). Full walkthrough: examples/gitlab_setup.md.

Contributing

Issues and pull requests are welcome. Please keep changes backwards-compatible with existing state files where possible, run pytest before submitting, 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.