Skip to main content
Glama
Piotr1215

MCP Agentic Framework

by Piotr1215
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

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

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

  1. Get the LoadBalancer IP:

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

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

  1. Install dependencies:

npm install

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Piotr1215/mcp-agentic-framework'

If you have feedback or need assistance with the MCP directory API, please join our Discord server