MCP Agentic Framework

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.

Overview

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.

Comparison with Claude Code Sub-agents

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

Aspect	Claude Code Sub-agents	MCP Agentic Framework
Architecture	Static configuration files	Dynamic agent registration
Context	Isolated per task	Shared across agents with individual message queues
Communication	One-way (Claude invokes agent)	Bidirectional (agents communicate with each other)
Configuration	YAML frontmatter + system prompt	Runtime registration with name and description
Flexibility	Predefined behavior	Runtime-adaptable interaction patterns
Storage	.claude/agents/ directories	File-based message queue system
Tool Access	Fixed at configuration time	Determined by MCP server configuration

When to Use Each Approach

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.

Kubernetes Deployment

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

Prerequisites

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

Quick Start

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"
}

Managing the Deployment

# 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

Features

• 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)

Architecture

The Kubernetes deployment includes:

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

Kubernetes Manifests

Located in k8s/ directory:

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

Architecture

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

Installation

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

Usage with Claude Desktop or Claude Code

Using HTTP Transport

{
  "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)

HTTP Endpoints

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"
  }
  

Available Tools

register-agent

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"
}

unregister-agent

Remove an agent from the system.

Parameters:

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

discover-agents

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-message

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

check-for-messages

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-agent-status

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-broadcast

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
}

get-pending-notifications

Retrieve pending notifications for an agent.

Parameters:

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

Example Use Cases

Multi-Agent Collaboration

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"

Using Broadcasts

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..."

Development

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Storage

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)

Security Considerations

• 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

API Reference

Agent Object

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
}

Message Object

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
}

Practical Use Cases

1. Orchestrated Task Processing

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

2. Distributed Code Review

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

3. Emergency Coordination

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

Troubleshooting

Common Issues

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

License

MIT License