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

Related MCP server: MCP Agentic Framework

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