Agent Team MCP Server

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) ```bash 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](#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:

| Platform | Path |
|----------|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

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

| Variable | Default | Description | |----------|---------|-------------| | REDIS_HOST | localhost | Redis server host | | REDIS_PORT | 6379 | Redis server port | | REDIS_PASSWORD | (none) | Redis password if required | | REDIS_DB | 0 | Redis database number | | REDIS_PREFIX | agent-team: | Key prefix for all Redis keys | | DASHBOARD_PORT | 3456 | Web dashboard port |

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

| Agent ID | Role | Responsibilities | |----------|------|------------------| | lead-agent | Team Lead | Task coordination, architecture | | frontend-1, frontend-2 | Frontend Engineer | React/Next.js, UI/UX | | backend-1, backend-2 | Backend Engineer | API, business logic | | devops-1 | DevOps Engineer | CI/CD, deployment | | tester-1, tester-2 | QA Engineer | Testing | | security-1 | Security Engineer | Security audits | | docs-1 | Documentation | API docs, guides | | db-1 | Database Admin | Schema, optimization | | api-1 | API Designer | OpenAPI specs | | ui-1 | UI/UX Designer | Design system | | perf-1 | Performance Engineer | Optimization | | infra-1 | Infrastructure | AWS, scaling |

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