Agent Communication MCP Server

Make AI agents work together seamlessly. This Model Context Protocol (MCP) server enables Claude Code to coordinate multiple specialized agents, track their progress in real-time, and understand exactly how they approach and solve complex tasks.

Author: Jeremy Fowler

📦 Current Version

Latest Release: See releases for version history and changes.

What This Does

Think of this as a mission control for AI agents. Instead of trying to do everything yourself, you can delegate specific tasks to specialized agents (like a frontend engineer, backend engineer, or QA tester) and monitor their complete thought process from start to finish.

Why You'd Want This

🎯

🔍

📊

🛡️

🔄

⚡

Latest Features (v0.10.0)

🎯 : Get consistent, parallel-first instructions every time you delegate tasks. No more guessing how to coordinate multiple agents—the system tells you exactly how to run them together efficiently.

⚙️ : New protocol_config tool lets you customize how tasks are created and plans are structured. Want different templates for different types of work? Now you can set that up easily.

⚡ : Plan validation is now lightning fast thanks to smart caching with the new stepCount parameter. What used to take 100ms now takes less than 10ms. Your agents get feedback faster, work flows smoother.

How to Use: Add stepCount to your submit_plan calls:

Benefits: Creates PLAN.metadata.json for caching, dramatically speeds up report_progress and track_task_progress operations.

🔍 : The system automatically finds and validates agents, making setup more reliable. Less trial-and-error, more "it just works."

📊 : Better reporting and context sharing means you always know what your agents are thinking and doing. No more black boxes—complete transparency into their work process.

Quick Start

Installation

Choose the method that works best for your setup:

Setup with Claude

Quick Setup:

Manual Setup: Add this to your Claude configuration file (.mcp.json or claude_desktop_config.json):

🔒 Security Note: Never commit API keys to git. The .mcp.json file is gitignored to protect sensitive credentials. Use .mcp.json.example as a template and npm run setup for easy configuration.

Optional: TodoWrite Hook Integration

Want your Claude Code todos to automatically sync with agent task checkboxes? This optional hook makes it seamless.

What it does: When you update todos with TodoWrite, the hook reminds you to sync those changes to your active agent task's PLAN.md checkboxes. No more manual checkbox updates!

Quick Setup (3 steps):

1. Copy the hook file to your Claude Code hooks directory:

2. Make it executable:

3. Test it works:

Need help? Run our verification script to check everything:

That's it! Now when you use TodoWrite, you'll get helpful reminders to sync your todo changes to agent task checkboxes using the sync_todo_checkboxes tool.

Skip this if: You don't use TodoWrite or prefer manual checkbox management. The agent communication works perfectly without this hook.

Try It Out

Here are some conversational prompts you can use with Claude right away:

Delegate a task:

Check on progress:

Get the full story:

Clean up when done:

How It Works

The Agent Task Lifecycle

Every task goes through a clear, trackable lifecycle:

This gives you complete visibility into:

• What the agent understood from your request

• How they planned to approach the work

• What they actually did step by step

• What the final outcome was (success or failure)

Two Ways to Work

Context-Based (Recommended - Simple): Agents get clean task descriptions automatically. You never deal with file paths or technical details. Just create tasks and monitor progress.

Traditional (Advanced - Full Control): Direct access to all task files and management. Perfect if you need granular control over the process.

How the Smart Response System Works (NEW)

The Smart Response System learns from your agent interactions to provide progressively better guidance over time. It automatically detects common patterns and helps agents complete tasks more effectively.

What it does for you:

1. Detects Incomplete Delegations: When you create a task for another agent, the system notices if you forget to follow up and provides the exact command to check on it.

2. Progressive Guidance: As agents work together more, the system learns their patterns and provides increasingly specific help:

   • New agents get friendly reminders about the workflow

   • Experienced agents get concise, targeted guidance

   • Struggling agents receive more detailed assistance

3. Automatic Compliance Tracking: The system quietly tracks how well agents follow the task workflow and adjusts its guidance accordingly—no manual intervention needed.

4. Parallel Execution Optimization: Automatically detects opportunities to run multiple agents in parallel and generates the specific Task() commands for you. The parallel execution feature analyzes task dependencies and suggests concurrent execution patterns to maximize throughput.

5. Escalating Urgency Levels: Provides gentle reminders for compliant agents, firm warnings for those falling behind, and critical alerts when immediate action is required.

Example: Before and After

Before Smart Response System:

After Smart Response System:

Parallel Execution Example:

When the system detects multiple independent tasks, it automatically suggests parallel execution patterns. This parallel execution capability dramatically reduces overall completion time by utilizing all available agents concurrently.

The parallel execution optimizer considers task dependencies, agent availability, and workload distribution to generate optimal execution strategies.

The system is completely automatic—it's enabled by default and works silently in the background. You'll only notice it when it helps you avoid mistakes or complete tasks more efficiently.

What's in the Complete Protocol Guide

The complete PROTOCOL.md documentation covers everything in detail. Here's what you'll find:

📚 Core Concepts

• Task Lifecycle: Complete breakdown of how tasks flow from creation to completion

• Agent Communication Patterns: Context-based vs traditional workflows

• Task Organization: How files and data are structured behind the scenes

🛠️ Complete Tool Reference (18 Tools Total)

Traditional Task Management (7 tools):

• Create and manage tasks with full control

• Read and write task files directly

• List agents and their current workload

• Archive and restore completed work

Context-Based Tools (5 tools):

• Get clean task context without file paths

• Submit implementation plans with automatic validation

• Report progress updates in real-time

• Complete tasks with intelligent reconciliation

• Batch cleanup operations

• NEW: Optional taskId parameter support for targeting specific tasks

Diagnostic Tools (2 tools):

• Get complete lifecycle visibility for any task

• Track real-time progress with detailed percentages

Utility Tools (4 tools):

• Server health checks and status

• Comprehensive server information and capabilities

• TodoWrite integration for checkbox synchronization

• Protocol configuration management for custom templates

🔄 Workflow Patterns

• Context-Based Workflow: The recommended simple approach

• Diagnostic Monitoring: How to track multiple agents non-blocking

• Traditional Workflow: Full control for advanced users

🚀 Advanced Features

TodoWrite Integration: Seamless synchronization between Claude Code's TodoWrite system and agent PLAN.md checkboxes. The integration includes a PostToolUse hook that automatically detects todo changes and reminds you to sync with the MCP server. See docs/TODOWRITE-INTEGRATION.md for complete setup and usage guide.

Intelligent Reconciliation: Handle real-world scenarios where agents optimize their approach or encounter blockers. Four reconciliation modes help you complete tasks even when the original plan changes.

Archive and Restore: Keep your workspace clean with smart archiving that lets you restore previous work when needed.

⚙️ Configuration Reference

• Environment Variables: Complete list with defaults and examples

• MCP Client Setup: Configuration for Claude Desktop, VSCode, and other clients

• Agent Instructions: Ready-to-use templates for your agent descriptions

🔧 Error Handling & Troubleshooting

• Common Error Patterns: What goes wrong and how to fix it

• Best Practices: Proven approaches for reliable agent coordination

• Performance Tips: Keep everything running smoothly

📊 API Version & Compatibility

• Current version information

• MCP compatibility details

• Node.js requirements and testing info

Real-World Usage Examples

Parallel Development Team

Large Feature Implementation

Code Review and Quality

Why This Architecture

Non-Blocking by Design: You can launch multiple agents and they'll work simultaneously while you stay productive. No waiting around for sequential completion.

Complete Transparency: Instead of wondering "what is that agent doing?", you get full insight into their thinking process, planning, and execution.

File System Abstraction: Agents never see file paths or directory structures. They get clean task context and produce clean results. No more path-related bugs or setup complexity.

Real-World Flexibility: The reconciliation system handles when agents find better approaches or encounter unexpected issues. Tasks can still complete successfully even when the original plan changes.

Production Ready: Full TypeScript implementation with comprehensive testing, error handling, and logging. Built for reliability in real development workflows.

Environment Options

The server is configurable via environment variables:

For most users, the defaults work perfectly. The system creates directories automatically as needed.

Filesystem Architecture

The server implements a robust dual-layer filesystem architecture designed for reliable file operations with comprehensive error handling and cross-platform compatibility.

Architecture Overview

Layer Responsibilities

🎯 High-Level Layer (

• Task-focused operations with domain validation

• Automatic directory creation for write operations

• Meaningful error messages with context (FileNotFoundError, InvalidTaskError)

• Task metadata parsing and validation utilities

• Agent Communication Server specific functionality

⚙️ Low-Level Layer (

• Direct filesystem operations with Node.js built-in fallbacks

• Handles fs-extra import issues and module resolution conflicts

• Diagnostic capabilities and performance monitoring

• Cross-platform reliability with multiple import strategies

• Basic operations: pathExists, readdir, writeFile, readFile, stat, remove, ensureDir

Usage Guidelines

Use High-Level Layer when:

• Creating or managing agent tasks

• Need validation (task names, agent names)

• Want automatic directory creation

• Need domain-specific error handling

Use Low-Level Layer when:

• Need direct filesystem control

• Bulk operations like directory scanning

• Require specific fs-extra features

• Building custom filesystem utilities

Key Benefits

🛡️ Reliability: Multi-strategy imports with Node.js fallbacks ensure operations work regardless of fs-extra installation status

🔒 Validation: Comprehensive input validation prevents path traversal attacks and invalid task creation

🚀 Performance: Optimized imports and caching reduce overhead while maintaining flexibility

🔧 Maintainability: Clear separation of concerns makes the codebase easier to understand and extend

🌐 Cross-Platform: Consistent behavior across Windows, macOS, and Linux environments

This architecture ensures reliable filesystem operations while providing the flexibility needed for both simple task management and complex agent coordination workflows.

Development & Building

The project uses build-time version injection - version info is automatically pulled from package.json and compiled into the server, so there's no runtime file access needed.

Get Started Today

1. Install: npm install -g @jerfowler/agent-comm-mcp-server

2. Configure: Add the MCP server to your Claude configuration

3. Try it: Ask Claude to "create a task for senior-frontend-engineer using agent-comm tools"

4. Explore: Check out the complete PROTOCOL.md documentation for everything else

Contributing & Git Workflow

This project uses a Git Feature Branch Workflow with branch protection on main:

Quick Contribution Guide

Branch Protection

• ✅ No direct commits to main - all changes via PRs

• ✅ Required reviews - at least 1 approval needed

• ✅ All tests must pass - comprehensive CI pipeline

• ✅ Up-to-date branches - must be current with main

See CONTRIBUTING.md and BRANCHING.md for complete workflow details.

GitHub CLI Aliases

Pre-configured aliases for streamlined workflow:

• gh pr-create - Create PR with auto-fill and self-assignment

• gh pr-checks - Check PR status and CI results

• gh pr-merge - Squash merge with branch cleanup

• gh feature - Create branch from GitHub issue

Support

Questions? Check the issues tab or create a new issue with:

• What you were trying to do

• What happened instead

• Your configuration and environment details

Agent Communication MCP Server - Making AI agent coordination simple, transparent, and powerful.