Agent Team MCP Server

A Model Context Protocol (MCP) server that enables real-time communication between multiple AI agents. Designed for orchestrating teams of specialized AI agents (frontend, backend, tester, DevOps, etc.) working on shared projects.

Uses Redis for data storage and pub/sub messaging, enabling multi-instance deployments with real-time capabilities.

Includes a real-time web dashboard for full transparency into agent communications, workloads, tasks, and shared artifacts.

Core Features

• Agent Management: Register agents, track presence via heartbeats, see team status
• Direct Messaging: Send messages between agents with priority and threading
• Channel Communication: Pub/sub channels for topic-based communication
• Task Management: Create, assign, and track tasks across the team
• Artifact Sharing: Register and share artifacts (API specs, components, docs)
• Real-time Updates: Redis pub/sub for instant notifications

Dashboard Features ✨

🎯 Team Overview

• Agent Status: Real-time status of all team members (active, busy, idle, offline)
• Presence Tracking: Heartbeat-based agent availability
• Team Statistics: Total agents, breakdown by status

📊 Transparency & Monitoring

• Communication Graph: Visualize who communicates with whom, sorted by message frequency
• Agent Workload: Per-agent task breakdown (pending → in-progress → review → blocked → completed)
• Unread Messages: Track message queue for each agent
• Message Threads: Thread-based message conversations with request-response tracking
• Task Board: Kanban-style task visualization across all status states

📁 Artifact Management

• Artifact Grid: Browse all shared artifacts with owner and type information
• Artifact Modal: Click to view full artifact contents with:
• File metadata (owner, version, creation/update dates)
• Full scrollable content (syntax-highlighted code, configs)
• File size and tags
• Metadata and additional info
• Real-time Sync: Auto-updates as new artifacts are shared

💬 Message Management

• Recent Messages: Latest 20 messages with sender/recipient info
• Message Modal: Click any message to view full details:
• Message metadata (from, to, timestamp, type)
• Complete subject and content
• Optional metadata fields
• Message Types: Request, Response, Notification, Direct
• Thread Detection: Automatically groups RE: messages into conversation threads

📈 Activity Feed

• Unified Activity Log: All team activities in chronological order
• Activity Types: Task updates, messages, artifacts, agent events
• Real-time Updates: Live feed of team progress

Prerequisites

• Node.js 18+ — required to build and run the MCP server
• Redis — for agent state and messaging (see setup options below)

Quick Start

Step 1 — Build the MCP server

git clone https://github.com/your-username/ClaudeAgentMCPServer
cd ClaudeAgentMCPServer
npm install
npm run build

Step 2 — Start Redis + Dashboard

Option A: Docker (recommended)

docker compose up -d
# → Redis at localhost:6379
# → Dashboard at http://localhost:3456

Option B: Without Docker

# Install Redis manually:
#   macOS:   brew install redis && brew services start redis
#   Ubuntu:  sudo apt install redis-server && sudo systemctl start redis
#   Windows: https://github.com/microsoftarchive/redis/releases

# Start the dashboard separately
cd dashboard
npm install
npm start
# → Dashboard at http://localhost:3456

Then wire Claude to the MCP server (see Connecting Claude below).

Why is the MCP server not in Docker? The MCP server communicates over stdio — Claude launches it directly as a child process. It is not an HTTP service and cannot be reached via a network port. Docker handles Redis (shared state) and the dashboard (monitoring UI) only.

Connecting Claude

Option A — Claude Code (automatic, project-level)

A .mcp.json is included in this repo. When you open this folder in Claude Code it will prompt you to enable the agent-team MCP server automatically. Redis must be running first (docker compose up -d).

Option B — Claude Desktop (manual, global)

Edit your Claude Desktop config file:

Add this block (replace the path with your actual clone location):

{
  "mcpServers": {
    "agent-team": {
      "command": "node",
      "args": ["/absolute/path/to/ClaudeAgentMCPServer/dist/index.js"],
      "env": {
        "REDIS_HOST": "localhost",
        "REDIS_PORT": "6379"
      }
    }
  }
}

Restart Claude Desktop after saving.

Configuration

Environment Variables

Tools Available

Agent Management

• agent_register - Register an agent with the team
• agent_heartbeat - Send heartbeat to maintain presence
• agent_deregister - Leave the team
• team_status - Get status of all team members
• agent_status - Get detailed status of specific agent
• list_agents - List all agents with optional filters

Messaging

• send_message - Send direct message to another agent
• get_messages - Get inbox or sent messages
• broadcast_message - Broadcast to all agents or a role group
• get_unread_count - Get unread message count

Channels

• channel_subscribe - Subscribe to a topic channel
• channel_unsubscribe - Unsubscribe from a channel
• channel_publish - Publish message to a channel
• channel_history - Get recent channel messages
• list_channels - List all available channels

Tasks

• task_create - Create a new task
• task_update - Update task status, assignee, add notes
• task_get - Get task details
• task_list - List tasks with filters
• task_history - Get task event history

Artifacts

• artifact_register - Register a shared artifact
• artifact_list - List artifacts with filters
• artifact_get - Get artifact details
• artifact_notify - Notify agents about artifact changes
• artifact_search - Search artifacts by path pattern

Dashboard REST API

The dashboard server exposes the following REST endpoints:

Team & Agents

• GET /api/team-status - Get all agents and their current status

Tasks

• GET /api/tasks - Get all tasks with summary by status

Messages

• GET /api/messages/recent - Get 50 most recent messages

Communication

• GET /api/communication-graph - Get communication patterns (who talks to whom)
• GET /api/agent-workload - Get per-agent workload and task breakdown
• GET /api/message-chains - Get threaded message conversations

Artifacts

• GET /api/artifacts - Get all shared artifacts with full content

Activity

• GET /api/activity - Get activity feed with all team events

WebSocket Real-time Updates

Dashboard connects to server via WebSocket (ws://localhost:3456) for real-time updates:

• Initial data push on connection
• Live updates on agent status changes
• Broadcast events for team-wide notifications
• 10-second automatic refresh cycle for all transparency data

Example Workflow

1. Agent Registration (Each agent on startup)

agent_register({
  agentId: "frontend-1",
  role: "frontend-engineer",
  name: "Frontend Agent 1",
  capabilities: ["react", "typescript", "tailwind"]
})

2. Check Team Status

team_status()

3. Send Request to Backend

send_message({
  from: "frontend-1",
  to: "backend-1",
  type: "request",
  subject: "Need User API",
  content: "Please create GET /api/users/{id} endpoint. Need: id, name, email, avatar",
  priority: "high"
})

4. Create Task

task_create({
  title: "Implement User Profile API",
  description: "Create REST endpoint for user profile data",
  priority: "high",
  assignee: "backend-1",
  reporter: "frontend-1"
})

5. Publish to Channel

channel_publish({
  agentId: "backend-1",
  channel: "api-updates",
  content: "User API v1.0 deployed. GET /api/users/{id} now available."
})

6. Monitor on Dashboard

Open http://localhost:3456 in your browser to see:

• ✅ Team Status: All agents and their current status (active, busy, idle, offline)
• 🔗 Communication Graph: Visual representation of message flow between agents
• 📊 Agent Workload: Tasks breakdown for each agent (pending, in-progress, review, blocked, completed)
• 📁 Shared Artifacts: Browse and click artifacts to view full content (API specs, code, configs)
• 💬 Messages: Recent messages - click any message to view full details in modal
• 🔀 Message Threads: Conversation threads with RE: (response) tracking
• 📈 Activity Feed: Chronological log of all team activities
• ✅ Task Board: Kanban board view of all tasks by status

All dashboard sections update in real-time as agents communicate and work progresses.

Dashboard Interactive Features

Message Modal

Click any message in "Recent Messages" to open a detailed modal showing:

• Message type (request, response, notification, direct)
• From/To agents and timestamp
• Full subject and content
• Optional metadata fields

Artifact Modal

Click any artifact card in "Shared Artifacts" to open a detailed modal showing:

• Full file path and owner information
• File metadata (version, creation date, size)
• Complete scrollable file content (with syntax preservation)
• Tags and additional metadata
• File size calculation (Bytes → KB → MB → GB)

Close Interactions

• Click the ✕ button to close any modal
• Click outside the modal (overlay) to close
• Press ESC key to close

Agent Roles

Development

# Run in development mode
npm run dev

# Build
npm run build

# Start built version
npm start

Troubleshooting

Dashboard shows "No agents yet"

• Ensure MCP server is running and agents have registered
• Run node dashboard/test-data.js to populate test data
• Check Redis connection: redis-cli ping should return PONG

Redis WRONGTYPE Error

• This can occur if keys are stored as different data types
• Solution implemented in code: type checking before reads with redis.type()
• Data is now read as string, list, or hash as needed

Messages/Artifacts not appearing

• Check that Redis is running and accessible
• Verify REDIS_HOST and REDIS_PORT match in MCP server and dashboard
• Dashboard refreshes every 10 seconds; wait a moment for updates

Dashboard not connecting to WebSocket

• Ensure dashboard server is running on port 3456
• Check browser console for WebSocket errors
• Try refreshing the page

Port already in use

• MCP Server: Runs on port 7777 (internal, no external access)
• Dashboard: DASHBOARD_PORT=3457 npm start to use different port
• Check with lsof -i :3456 (macOS/Linux) or netstat -an | findstr :3456 (Windows)

Architecture

Components

1. MCP Server (src/index.ts): Handles agent communication, tasks, artifacts
2. Dashboard Server (dashboard/server.js): Express server + WebSocket for real-time updates
3. Dashboard Frontend (dashboard/public/index.html): Vue-like reactive UI
4. Redis: Shared data store for all components

Data Flow

Agents (Claude Code clients)
    ↓
MCP Server ← → Redis ← → Dashboard Server ← WebSocket ← Dashboard UI

Key Redis Structures

• agents:registry (hash): All registered agents
• tasks:all (set): Task IDs, tasks:{id} (string): Task data
• messages:inbox:{agentId} (list): Messages for agent
• artifacts:all (set): Artifact IDs, artifacts:{id} (string): Artifact data
• {type}:channels:{name} (list): Channel messages

License

MIT