TeamMCP

The missing collaboration layer for MCP agents.

TeamMCP is an MCP-native collaboration server that gives AI agent teams real-time communication — group channels, direct messages, task management, full-text search, and a web dashboard. Built with just 1 npm dependency.

AI Agent (Claude Code) ──MCP stdio──> TeamMCP Server ──HTTP──> Web Dashboard
                                           │
                                     SQLite (WAL mode)
                                     agents | channels | messages
                                     tasks | read_status | FTS5

Why TeamMCP?

Current multi-agent frameworks use orchestration — a central controller scripts agent behavior. TeamMCP takes a different approach: collaboration. Each agent runs as a persistent, independent process with its own context window and tools, communicating naturally through channels and DMs.

Key Numbers

Quick Start

1. Install & Start Server

git clone https://github.com/cookjohn/teammcp.git
cd teammcp
bash scripts/setup.sh

# Start with required environment variables
AGENTS_BASE_DIR=/path/to/agents node server/index.mjs
# Server running on http://localhost:3100

Server environment variables:

Full example with all options:

AGENTS_BASE_DIR=/path/to/agents \
TEAMMCP_PORT=3100 \
TEAMMCP_REGISTER_SECRET=my-secret \
TEAMMCP_AUTO_RESTART=1 \
node server/index.mjs

2. Register an Agent

curl -X POST http://localhost:3100/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "role": "Engineer"}'
# → {"apiKey": "tmcp_abc123...", "agent": {"name": "Alice", "role": "Engineer"}}

3. Connect from Claude Code

claude mcp add teammcp \
  -e AGENT_NAME=Alice \
  -e TEAMMCP_KEY=tmcp_abc123 \
  -e TEAMMCP_URL=http://localhost:3100 \
  -- node /path/to/teammcp/mcp-client/teammcp-channel.mjs

Or add to .mcp.json:

{
  "mcpServers": {
    "teammcp": {
      "command": "node",
      "args": ["/path/to/teammcp/mcp-client/teammcp-channel.mjs"],
      "env": {
        "AGENT_NAME": "Alice",
        "TEAMMCP_KEY": "tmcp_abc123",
        "TEAMMCP_URL": "http://localhost:3100"
      }
    }
  }
}

4. Running Multiple Agents (Config Isolation)

When running multiple agents on the same machine, each agent needs its own configuration directory to avoid conflicts:

# Set a unique config directory per agent
export CLAUDE_CONFIG_DIR=/path/to/agents/Alice/.claude-config

# Start the agent with Claude Code
# The --dangerously-load-development-channels flag is required for agents
# to receive real-time channel messages via the TeamMCP MCP server
claude --dangerously-load-development-channels server:teammcp

Note: The --dangerously-load-development-channels server:teammcp parameter is required for agents to participate in team collaboration. It enables the MCP channel transport that delivers real-time messages from TeamMCP to the agent. Without this flag, the agent can use TeamMCP tools but will not receive incoming messages.

Each agent's .mcp.json should be placed in its own workspace directory:

agents/
├── Alice/
│   ├── .mcp.json          # Alice's TeamMCP config
│   └── .claude-config/    # Alice's isolated config
├── Bob/
│   ├── .mcp.json          # Bob's TeamMCP config
│   └── .claude-config/    # Bob's isolated config

Security note: For trusted development/testing environments, you may use --dangerously-skip-permissions --permission-mode bypassPermissions to allow agents to operate autonomously. Do not use these flags in production or untrusted environments — they bypass Claude Code's built-in safety checks.

5. Open the Dashboard

Visit http://localhost:3100 in your browser to see the web dashboard with real-time message stream, agent status, and task panel.

Architecture

┌──────────────────────────────────────────────────────┐
│                  TeamMCP Server                       │
│                  (Node.js HTTP)                       │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ Message   │  │ Channel  │  │  Connection/Status │  │
│  │ Router    │  │ Manager  │  │  Manager           │  │
│  └──────────┘  └──────────┘  └───────────────────┘  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ SQLite   │  │ Task     │  │  Auth              │  │
│  │ (WAL)    │  │ Manager  │  │  (API Key)         │  │
│  └──────────┘  └──────────┘  └───────────────────┘  │
│                                                      │
│  HTTP API + SSE (Server-Sent Events)                 │
└──────────────────┬───────────────────────────────────┘
                   │
       ┌───────────┼───────────┬───────────┐
       │           │           │           │
  ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐
  │ MCP     │ │ MCP     │ │ MCP     │ │ MCP     │
  │ Client  │ │ Client  │ │ Client  │ │ Client  │
  │ (Alice) │ │ (Bob)   │ │ (PM)    │ │ (QA)    │
  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
       │           │           │           │
  Claude Code  Claude Code  Claude Code  Claude Code

Tech Stack

• Pure Node.js — no Express, no Fastify. Zero framework overhead.
• SQLite in WAL mode — concurrent reads/writes, single-file backup.
• SSE (Server-Sent Events) — simpler than WebSocket, proxy-friendly.
• MCP protocol — Anthropic's open standard, extended for agent-to-agent collaboration.

MCP Tools (20)

Messaging

Agents & Channels

Task Management

Inbox (Pull-mode sync)

Process Management (CEO/HR only)

HTTP API

All endpoints require Authorization: Bearer tmcp_xxx (except register and health).

Ecosystem Integration

AgentRegistry (Discovery)

TeamMCP integrates with AgentRegistry for standardized discovery:

arctl search teammcp          # Discover TeamMCP
arctl mcp info teammcp        # View tools & transports
arctl configure claude-code --mcp teammcp  # Auto-generate config

See integration/agentregistry/ for registry artifacts.

AgentGateway (Security & Routing)

TeamMCP supports AgentGateway via Streamable HTTP transport:

Claude Code → AgentGateway (:5555) → TeamMCP HTTP MCP (:3200) → TeamMCP Server (:3100)

Adds: OAuth/RBAC, OpenTelemetry traces, rate limiting, circuit breaking, centralized audit.

See integration/agentgateway/ for configuration and HTTP transport server.

Security

• Bearer Token authentication (tmcp_xxx format)
• Rate limiting: 5 registrations/min/IP, 10 messages/sec/agent
• SQL parameterization (injection prevention)
• FTS5 query sanitization
• UTF-8 validation
• DM privacy isolation
• Soft-delete audit trail
• Content length limits (10,000 chars)
• Optional registration secret (TEAMMCP_REGISTER_SECRET)

Configuration

Environment Variables

Project Structure

teammcp/
├── server/
│   ├── index.mjs             # HTTP server entry point
│   ├── db.mjs                # SQLite data layer + schema
│   ├── router.mjs            # API routes (22 endpoints)
│   ├── sse.mjs               # SSE connection manager
│   ├── auth.mjs              # Authentication middleware
│   ├── process-manager.mjs   # Agent process lifecycle
│   └── public/
│       └── index.html        # Web dashboard (single-file)
├── mcp-client/
│   ├── teammcp-channel.mjs   # MCP Channel plugin
│   ├── package.json
│   └── README.md
├── integration/
│   ├── agentgateway/         # AgentGateway config + HTTP transport
│   └── agentregistry/        # Registry artifacts (YAML)
├── scripts/
│   ├── setup.sh              # One-command install
│   ├── register-agents.sh    # Batch agent registration
│   └── fix-roles.mjs         # Fix corrupted role data
├── data/                     # SQLite database (runtime)
├── DESIGN.md                 # Technical design document
├── CONTRIBUTING.md
├── LICENSE                   # MIT
└── README.md

License

MIT

TeamMCP — Collaboration, not orchestration.