MCP Mesh

The future of AI is not one large model, but many specialized agents working together.

📚 Documentation · 🚀 Quick Start · 🎬 YouTube · 💬 Discord

⚡ Getting Started

# Install the CLI
npm install -g @mcpmesh/cli

# Explore commands
meshctl --help

# Built-in documentation
meshctl man

Python Quick Start → | Java Quick Start → | TypeScript Quick Start →

🎯 Why MCP Mesh?

You write the agent logic. The mesh discovers, connects, heals, and traces — across languages, machines, and clouds.

For Developers 👩‍💻

Stop fighting infrastructure. Start building intelligence.

Zero Boilerplate: Simple decorators/functions replace hundreds of lines of networking code
Python, Java & TypeScript: Write MCP servers as simple functions in your preferred language - no manual client/server setup
Web Framework Integration: Inject MCP agents directly into FastAPI (Python), Spring Boot (Java), or Express (TypeScript) APIs seamlessly
LLM as Dependencies: Inject LLMs just like MCP agents - dynamic prompts with Jinja2 (Python), FreeMarker (Java), or Handlebars (TypeScript)
Seamless Development Flow: Code locally, test with Docker Compose, deploy to Kubernetes - same code, zero changes
kubectl-like Management: meshctl - a familiar command-line tool to run, monitor, and manage your entire agent network

# MCP Agent
@app.tool()
@mesh.tool(capability="plan_trip", dependencies=["weather_service"])
def plan_trip(weather_service=None):
    # Just write business logic - mesh handles the rest

# FastAPI Route with MCP DI
@api.post("/trip-planning")
@mesh.route(dependencies=["plan_trip"])
async def create_trip(trip_data: dict, plan_trip=None):
    # Use MCP agents directly in your web API
    return plan_trip(trip_data)

For Solution Architects 🏗️

Design intelligent systems, not complex integrations.

Agent-Centric Architecture: Design specialized agents with clear capabilities and dependencies, not monolithic systems
Dynamic Intelligence: Agents get smarter automatically when new capabilities come online - no reconfiguration needed
Domain-Driven Design: Solve business problems with ecosystems of focused agents that can be designed and developed independently
Composable Solutions: Mix and match agents to create new business capabilities without custom integration code

Example: Deploy a financial analysis agent that automatically discovers and uses risk assessment, market data, and compliance agents as they become available.

For DevOps & Platform Teams ⚙️

AI infrastructure out of the box.

Kubernetes-Native: Deploy with Helm charts - horizontal scaling, health checks, and service discovery included
Enterprise Observability: Built-in Grafana dashboards, distributed tracing, and centralized logging for complete system visibility
Zero-Touch Operations: Agents self-register, auto-discover dependencies, and gracefully handle failures without network restarts
Standards-Based: Leverage existing Kubernetes patterns - RBAC, network policies, service mesh integration, and security policies

Scale from 2 agents to 200+ with the same operational complexity.

For Support & Operations 🛠️

Complete visibility and zero-downtime operations.

Real-Time Network Monitoring: See every agent, dependency, and health status in live dashboards
Intelligent Scaling: Agents scale independently based on demand - no cascading performance issues
Graceful Failure Handling: Agents degrade gracefully when dependencies are unavailable, automatically reconnect when services return
One-Click Diagnostics: meshctl status provides instant network health assessment with actionable insights

For Engineering Leadership 📈

Transform AI experiments into production revenue.

Accelerated Time-to-Market: Move from PoC to production deployment in weeks, not months
Cross-Team Collaboration: Enable different departments to build agents that automatically enhance each other's capabilities
Risk Mitigation: Proven patterns help ensure reliable AI deployments that scale with your business
Future-Proof Architecture: Add new AI capabilities without disrupting existing systems

Turn your AI strategy from "promising experiments" to "competitive advantage in production."

Architecture Overview

MCP Mesh Architecture

MCP Mesh handles the complexity so you don't have to:

Zero Boilerplate: Just add @mesh.tool() - networking handled automatically
Dynamic Everything: Add/remove/upgrade services without touching other code
Complex Apps Made Simple: Financial services example shows 6+ interconnected agents
Production Ready: Built-in resilience, distributed observability, and scaling

The Magic: Write simple functions in Python, Java, or TypeScript, get distributed systems.

Key Features

Distributed Dynamic Dependency Injection (DDDI)

Distributed — dependencies span machines, clouds, and runtimes (Python/TypeScript/Java)
Dynamic — services discovered and injected at runtime, not compile time
Hot-swappable — dependencies update without restarts via heartbeat-driven re-resolution
Pull-based discovery with runtime function injection — no networking code required
Smart resolution with version constraints, capability matching, and tag scoring
LLM as a dependency — treat LLMs as first-class injectable services with automatic tool discovery

Resilience

Registry as facilitator - agents communicate directly with fault tolerance
Self-healing architecture - automatic reconnection when services return
Graceful degradation - agents work standalone when dependencies unavailable
Background orchestration - mesh coordinates without blocking business logic

Observability

Complete observability stack - Grafana dashboards, Tempo tracing, Redis session management
Distributed tracing with OTLP export and cross-agent context propagation
Real-time trace streaming for multi-agent workflow monitoring
Advanced session management with Redis-backed stickiness across pod replicas

Developer Experience & Operations

Near-complete MCP protocol support for distributed networks
Enhanced proxy system with kwargs-driven auto-configuration for timeouts, retries, streaming
meshctl CLI for lifecycle management and network insights
Kubernetes native with scaling, health checks, and comprehensive observability

MCP Mesh vs Other AI Agent Frameworks

Feature	Other Frameworks	MCP Mesh
Zero-config Dependency Injection	❌	✅
Dynamic Agent Discovery & Hot Join/Leave	❌	✅
Cross-language Support	❌	✅ Python + Java + TypeScript
Same Code: Local → Docker → K8s	❌ Rewrite needed	✅
Developer CLI (scaffold, trace, status)	❌	✅ `meshctl`
Kubernetes-native (Helm)	❌ DIY	✅
Distributed Tracing (OpenTelemetry)	❌ DIY	✅ Grafana/Tempo
Auto-failover & Graceful Degradation	❌	✅
LLM as Dependency (Discovery + Failover)	❌	✅
Zero-config Testing (Topology Mocking)	❌	✅
Standard Protocol	❌ Custom	✅ MCP
Framework Lock-in	High (classes)	Low (decorators)
Lines of Code per Agent	~50+	~10

See full comparison →

Contributing

We welcome contributions from the community! MCP Mesh is designed to be a collaborative effort to advance the state of distributed MCP applications.

How to Contribute

Check the Issues - Find good first issues or suggest new features
Join Discussions - Share ideas and get help from the community
Submit Pull Requests - Contribute code, documentation, or examples
Follow our development guidelines - See project structure and coding standards below

Community & Support

Discord - Real-time help and discussions
GitHub Discussions - Share ideas and ask questions
Issues - Report bugs or request features
Examples - Working code examples and deployment patterns

License

This project is open source. License details will be provided in the LICENSE file.

Acknowledgments

Anthropic for creating the MCP protocol that inspired this project
FastMCP for providing excellent MCP server foundations
Kubernetes community for building the infrastructure platform that makes this possible
All the contributors who help make MCP Mesh better

📚 Learn More

📚 Full Documentation - Complete guides and reference
⚡ Quick Tutorial - Build your first distributed MCP agent
💬 Join Discord - Connect with the community
🔧 Contribute - Help build the future of AI orchestration

Star the repo if MCP Mesh helps you build better AI systems! ⭐

mcp-mesh