TeamMCP

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
node server/index.mjs
# Server running on http://localhost:3100

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. 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.