A Model Context Protocol (MCP) based communication framework that enables multiple AI agents to collaborate through asynchronous messaging. Built with Test-Driven Development (TDD) and functional programming principles.

This framework provides a standardized way for multiple Claude agents (or other MCP-compatible agents) to:

• Register themselves with unique identities
• Discover other registered agents
• Exchange messages asynchronously
• Send broadcasts to all agents
• Work together on complex tasks

The framework uses file-based storage for simplicity and portability, making it easy to run without external dependencies.

This framework provides a different approach to multi-agent collaboration compared to Claude Code's sub-agents feature.

Use Claude Code Sub-agents when:

• Tasks are well-defined and repetitive (code review, debugging, testing)
• Consistent, predictable behavior is required
• Working independently on specific problems
• Need to preserve main conversation context

Use MCP Agentic Framework when:

• Real-time collaboration between multiple agents is needed
• Tasks require discussion, negotiation, or consensus
• Problem-solving benefits from diverse perspectives
• Building distributed workflows with agent coordination

Both systems can be complementary: MCP agents can collaborate to design and refine sub-agent configurations, while sub-agents can handle routine tasks identified by MCP agent discussions.

The MCP Agentic Framework can be deployed on Kubernetes for production use with high availability and easy management.

• Kubernetes cluster with MetalLB LoadBalancer (or similar)
• Docker Hub account (or other container registry)
• just command runner installed (cargo install just)

1. Clone and navigate to the framework:

cd /home/decoder/dev/mcp-agentic-framework

2. Deploy with the Justfile:

# First time: Update the docker_user in Justfile
vim Justfile  # Change docker_user to your Docker Hub username

# Deploy (builds, pushes, and deploys to Kubernetes)
just update

3. Get the LoadBalancer IP:

just status
# Or manually:
kubectl get svc mcp-agentic-framework-lb

4. Update Claude configuration (~/.claude.json):

"agentic-framework": {
  "type": "http",
  "url": "http://YOUR_LOADBALANCER_IP:3113/mcp"
}

# View all available commands
just

# Deploy updates (bumps version, builds, pushes, deploys)
just update          # Patch version bump (1.0.0 -> 1.0.1)
just update-minor    # Minor version bump (1.0.0 -> 1.1.0)
just update-major    # Major version bump (1.0.0 -> 2.0.0)

# Monitor deployment
just status          # Check deployment status
just logs            # Stream logs
just test-health     # Test health endpoint

# Operations
just restart         # Restart the deployment
just rollback        # Rollback to previous version

• Zero-downtime deployments with rolling updates
• Automatic version management with semantic versioning
• Health checks with automatic restarts
• Persistent LoadBalancer IP via MetalLB
• Web UI for monitoring agent communications (auto-opens on first agent)

The Kubernetes deployment includes:

• Deployment: Single replica with health/readiness probes
• LoadBalancer Service: Stable external IP for Claude access
• ClusterIP Service: Internal cluster communication

Located in k8s/ directory:

• deployment.yaml - Main application deployment
• loadbalancer-service.yaml - External access via MetalLB

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Developer Agent │     │  Tester Agent   │     │ Architect Agent │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         └───────────────────────┴───────────────────────┘
                                 │
                      ┌──────────┴──────────┐
                      │   MCP Server        │
                      │  ┌──────────────┐   │
                      │  │Agent Registry│   │
                      │  └──────────────┘   │
                      │  ┌──────────────┐   │
                      │  │ Message Store│   │
                      │  └──────────────┘   │
                      └─────────────────────┘
                                 │
                      ┌──────────┴──────────┐
                      │ File Storage        │
                      │/tmp/mcp-agentic-    │
                      │    framework/       │
                      └─────────────────────┘

1. Clone the repository:

git clone https://github.com/Piotr1215/mcp-agentic-framework.git
cd mcp-agentic-framework

2. Install dependencies:

npm install

3. Run tests to verify installation:

npm test

{
  "mcpServers": {
    "agentic-framework": {
      "type": "http",
      "url": "http://127.0.0.1:3113/mcp"
    }
  }
}

To use the HTTP transport:

1. Start the HTTP server: npm run start:http
2. Add the above configuration to your ~/.claude.json
3. Restart Claude Desktop

Note: The HTTP transport supports Server-Sent Events (SSE)

When running with npm run start:http, the following endpoints are available:

• /mcp - Main MCP endpoint for agent communication
• /health - Health check endpoint that returns:

  {
    "status": "ok",
    "name": "mcp-agentic-framework",
    "version": "1.0.0"
  }

Register a new agent in the system.

Parameters:

• name (string, required): Agent's display name
• description (string, required): Agent's role and capabilities
• instanceId (string, optional): Instance identifier for automatic deregistration

Example:

{
  "name": "DeveloperAgent",
  "description": "Responsible for writing code and implementing features"
}

Remove an agent from the system.

Parameters:

• id (string, required): Agent's unique identifier

List all currently registered agents.

Parameters: None

Response Example:

[
  {
    "id": "agent_abc123",
    "name": "DeveloperAgent",
    "description": "Responsible for writing code",
    "status": "online",
    "lastActivityAt": "2024-01-20T10:30:00.000Z"
  }
]

Send a message from one agent to another.

Parameters:

• to (string, required): Recipient agent's ID
• from (string, required): Sender agent's ID
• message (string, required): Message content

Retrieve unread messages for an agent. Messages are automatically deleted after reading.

Parameters:

• agent_id (string, required): Agent's ID to check messages for

Response Example:

{
  "messages": [
    {
      "from": "agent_abc123",
      "fromName": "DeveloperAgent",
      "message": "Task completed",
      "timestamp": "2024-01-20T10:30:00.000Z"
    }
  ]
}

Update an agent's status (online, offline, busy, away).

Parameters:

• agent_id (string, required): Agent's ID
• status (string, required): New status (one of: online, offline, busy, away)

Send a broadcast message to all registered agents (except the sender).

Parameters:

• from (string, required): Sender agent's ID
• message (string, required): Broadcast message content
• priority (string, optional): Priority level (low, normal, high). Defaults to 'normal'

Features:

• Messages are delivered to all agents except the sender
• Works without requiring agents to subscribe
• Returns the number of recipients
• Messages are prefixed with priority level (e.g., "[BROADCAST HIGH]")

Example:

{
  "from": "orchestrator",
  "message": "System maintenance in 10 minutes",
  "priority": "high"
}

Response:

{
  "success": true,
  "recipientCount": 5,
  "errors": []  // Any delivery failures
}

Retrieve pending notifications for an agent.

Parameters:

• agent_id (string, required): Agent's ID

1. Register agents:
   - "Register an orchestrator agent for coordinating tasks"
   - "Register worker1 agent for processing"
   - "Register worker2 agent for analysis"

2. Orchestrator delegates tasks:
   - "Send message from orchestrator to worker1: Process customer data"
   - "Send message from orchestrator to worker2: Analyze market trends"

3. Workers communicate:
   - "Send message from worker1 to worker2: Data ready for analysis"

4. Broadcast updates:
   - "Send broadcast from orchestrator: All tasks completed"

The improved broadcast feature allows efficient communication with all agents:

// Orchestrator sends high-priority announcement
await sendBroadcast(
  orchestratorId,
  "Emergency: System overload detected, pause all operations",
  "high"
);

// All other agents receive: "[BROADCAST HIGH] Emergency: System overload..."

// Regular status update
await sendBroadcast(
  orchestratorId,
  "Daily standup meeting in 5 minutes",
  "normal"
);

// All agents receive: "[BROADCAST NORMAL] Daily standup meeting..."

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

The framework stores data in /tmp/mcp-agentic-framework/:

• agents.json: Registered agents with status and activity tracking
• messages/*.json: Individual message files (one per message)

• Input validation on all tool parameters
• File-based locking prevents race conditions
• No path traversal vulnerabilities
• Messages are stored locally only
• No external network calls

interface Agent {
  id: string;             // Unique identifier
  name: string;           // Display name
  description: string;    // Role description
  status: string;         // online|offline|busy|away
  registeredAt: string;   // ISO timestamp
  lastActivityAt: string; // ISO timestamp
}

interface Message {
  id: string;          // Message ID
  from: string;        // Sender agent ID
  to: string;          // Recipient agent ID
  message: string;     // Content
  timestamp: string;   // ISO timestamp
  read: boolean;       // Read status
}

Orchestrator → assigns tasks → Worker agents
Worker agents → process in parallel → report back
Orchestrator → broadcasts completion → all agents notified

Developer → sends code → multiple Reviewers
Reviewers → work independently → send feedback
Developer → broadcasts updates → all reviewers see changes

Monitor agent → detects issue → broadcasts alert
All agents → receive alert → adjust behavior
Coordinator → broadcasts all-clear → normal operations resume

1. Broadcasts not received

   • Ensure sender agent is registered
   • Check recipient agents are registered
   • Remember sender doesn't receive own broadcasts

2. "Agent not found" errors

   • Verify agent registration
   • Use discover-agents to list all agents
   • Check agent IDs are correct

3. Messages not received

   • Messages are deleted after reading
   • Each message can only be read once
   • Check correct agent ID

MIT License