Getting Started with MCP Mesh¶

From zero to distributed MCP services in 10 minutes

Overview¶

MCP Mesh makes building distributed MCP services as easy as writing Python functions. Add decorators to your classes and functions, and they automatically discover and use other services across your network.

What is MCP Mesh?¶

MCP Mesh is a distributed service mesh framework that enhances FastMCP with automatic discovery and dependency injection:

🔌 Dual decorators: Combine familiar @app.tool (FastMCP) with @mesh.tool (orchestration)
🔍 All MCP decorators: Support for @app.tool, @app.prompt, @app.resource from FastMCP
💉 Smart dependency injection: Use remote functions with type safety (mesh.McpMeshAgent)
🏷️ Tag-based resolution: Smart capability matching using tags and metadata
🚀 Zero boilerplate: Mesh discovers your FastMCP app and handles everything
📦 Production ready: Go registry + Python agents + Kubernetes support

The Simplest Example¶

import mesh
from fastmcp import FastMCP

# Single FastMCP server instance
app = FastMCP("Hello World Service")

# 1. Add a simple tool with dual decorators
@app.tool()  # ← FastMCP decorator (familiar MCP development)
@mesh.tool(capability="greeting")  # ← Mesh decorator (adds orchestration)
def greet(name: str = "World") -> str:
    return f"Hello, {name}!"

# 2. Add a tool with dependency injection
@app.tool()  # ← FastMCP handles MCP protocol
@mesh.tool(
    capability="advanced_greeting",
    dependencies=["date_service"]  # ← Mesh handles service discovery
)
async def greet_with_date(name: str = "World", date_service: mesh.McpMeshAgent = None) -> str:
    if date_service:
        current_date = await date_service()  # Calls remote system agent
        return f"Hello, {name}! Today is {current_date}"
    return f"Hello, {name}! (Date service not available)"

# 3. Configure the agent
@mesh.agent(
    name="hello-world",
    http_port=9090,
    auto_run=True  # Mesh handles server startup automatically
)
class HelloWorldAgent:
    pass

# No main method needed! Mesh discovers 'app' and handles everything.

That's it! The dual decorator pattern gives you:

FastMCP decorators (@app.tool) for familiar MCP development
Mesh decorators (@mesh.tool) for dependency injection and orchestration
Automatic discovery - Mesh finds your FastMCP app and handles server startup
Zero boilerplate - No main methods or manual server management needed

Prerequisites¶

Before you begin, ensure you have the required tools installed.

Required¶

Python 3.11+¶

# Check version
python --version  # Should show 3.11 or higher

# Install if needed
# macOS
brew install python@3.11

# Ubuntu/Debian
sudo apt install python3.11

# Windows - download from https://python.org

Virtual Environment¶

MCP Mesh expects a .venv directory in your project root:

# Create virtual environment
python -m venv .venv

# Activate it
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate      # Windows

# Install MCP Mesh SDK
pip install "mcp-mesh>=0.7,<0.8"

Why .venv?

meshctl start automatically detects and uses .venv if present. This keeps your project dependencies isolated and consistent.

Docker & Docker Compose¶

Required for the Docker quick start and production deployments:

# Check installation
docker --version
docker compose version

# Install if needed
# macOS
brew install --cask docker  # Installs Docker Desktop

# Ubuntu
sudo apt install docker.io docker-compose-v2

# Windows - download Docker Desktop from https://docker.com

meshctl CLI¶

The meshctl command-line tool manages agents, registry, and scaffolding:

# Install via npm (recommended)
npm install -g @mcpmesh/cli

Alternative: Homebrew (macOS)

brew tap dhyansraj/mcp-mesh
brew install mcp-mesh

Alternative: Install Script (Linux/macOS)

curl -sSL https://raw.githubusercontent.com/dhyansraj/mcp-mesh/main/install.sh | bash

Alternative: Build from Source

git clone https://github.com/dhyansraj/mcp-mesh.git
cd mcp-mesh
make install-dev
# Binary available at ./bin/meshctl

Verify installation:

meshctl version

Optional (for Kubernetes)¶

Helm¶

Required for deploying to Kubernetes:

# macOS
brew install helm

# Linux
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Verify
helm version

Minikube (Local Kubernetes)¶

For local Kubernetes development:

# macOS
brew install minikube

# Linux
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# Windows
choco install minikube

# Start cluster
minikube start --cpus=4 --memory=8192

Quick Check¶

Run this to verify your setup:

echo "=== MCP Mesh Prerequisites Check ==="
echo -n "Python: "; python --version 2>/dev/null || echo "❌ Not found"
echo -n "pip: "; pip --version 2>/dev/null | head -c 20 || echo "❌ Not found"
echo -n "Docker: "; docker --version 2>/dev/null | head -c 25 || echo "❌ Not found"
echo -n "meshctl: "; meshctl version 2>/dev/null || echo "❌ Not found (optional for Docker quick start)"
echo -n "Helm: "; helm version --short 2>/dev/null || echo "⚠️ Not found (optional)"
echo -n "Minikube: "; minikube version --short 2>/dev/null || echo "⚠️ Not found (optional)"

Quick Start (Docker - 2 Minutes)¶

Easiest way to get started:

# 1. Clone the repository (for agent code)
git clone https://github.com/dhyansraj/mcp-mesh.git
cd mcp-mesh/examples/docker-examples

# 2. Start everything (uses published Docker images)
docker-compose up

# 3. Test it (in another terminal)
meshctl call hello_mesh_simple --agent-url http://localhost:8081

Expected response:

{
  "content": [
    {
      "type": "text",
      "text": "👋 Hello from MCP Mesh! Today is December 11, 2025 at 03:30 PM"
    }
  ],
  "isError": false
}

That's it! You now have a working distributed MCP service mesh! 🎉

Quick Start with meshctl (2 Minutes)¶

The simplest way to run agents locally:

# 1. Install MCP Mesh
pip install "mcp-mesh>=0.7,<0.8"

# 2. Clone examples
git clone https://github.com/dhyansraj/mcp-mesh.git
cd mcp-mesh/examples/simple

# 3. Start agents (registry starts automatically!)
meshctl start system_agent.py     # Terminal 1
meshctl start hello_world.py      # Terminal 2

# 4. Test it
meshctl call hello_mesh_simple

Auto-Registry

meshctl start automatically starts the registry if one isn't running. No need to manage it separately!

Alternative Installation Methods¶

Homebrew (macOS)

# Install CLI tools via Homebrew
brew tap dhyansraj/mcp-mesh
brew install mcp-mesh

# Then follow the Quick Start above
pip install "mcp-mesh>=0.7,<0.8"

Install Script (Linux/macOS)

# Install meshctl binary
curl -sSL https://raw.githubusercontent.com/dhyansraj/mcp-mesh/main/install.sh | bash

# Then follow the Quick Start above
pip install "mcp-mesh>=0.7,<0.8"

Build from Source

**For contributors:**

# Build everything
make install-dev

# Start agents
./bin/meshctl start examples/simple/system_agent.py   # Terminal 1
./bin/meshctl start examples/simple/hello_world.py    # Terminal 2

# Check status
./bin/meshctl status

Learning Paths¶

Choose your journey based on your goals:

🚀 I want to see it working (5 minutes)¶

Docker Quick Start - Complete environment
Test the examples - See dependency injection in action
Explore with meshctl - Understand the architecture

🔧 I want to develop agents (15 minutes)¶

Local Development Setup - Set up your environment
Run examples locally - Direct binary execution
Modify an agent - Make your first change
Create new tools - Add your own functionality

🏭 I want production deployment (30 minutes)¶

Kubernetes Guide - Production-ready setup
Deploy to cluster - Scale and monitor
Test resilience - Failure scenarios
Monitor with meshctl - Operational insights

📚 I want to understand everything (60 minutes)¶

Start with Docker to see the big picture
Try local development to understand internals
Deploy to Kubernetes for production patterns
Read the architecture docs for deep understanding

How MCP Mesh Works¶

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Registry      │    │  Hello World     │    │  System Agent  │
│   (Go + DB)     │    │  Agent (Python)  │    │  (Python)       │
│   Port: 8000    │◄──►│  Port: 8081      │◄──►│  Port: 8082     │
│   [Discovery]   │    │  [Capabilities]  │    │  [Services]     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
        ▲                         ▲                       ▲
        │               ┌─────────┴────────┐              │
        └───────────────│  meshctl Client  │──────────────┘
                        │  (CLI/Dashboard) │
                        └──────────────────┘

Your Code                    MCP Mesh Runtime               Automatic
┌─────────────────┐         ┌────────────────────┐        ┌──────────────┐
│ @mesh.agent     │────────▶│ • HTTP Wrapper     │◄──────│ • Registry   │
│ @mesh.tool      │         │ • Dependency Graph │       │ • Discovery  │
│ def my_func():  │◄────────│ • JSON-RPC/MCP     │       │ • Health     │
└─────────────────┘         └────────────────────┘        └──────────────┘
   You write this             Handles complexity            Runs for you

Key Concepts in 30 Seconds¶

Agents: Python classes decorated with @mesh.agent that group related tools
Tools: Functions decorated with @mesh.tool that provide specific capabilities
Registry: Go service that tracks all agents and handles service discovery
Capabilities: What each tool provides (e.g., "date_service", "weather", "database")
Dependencies: What capabilities a tool needs from other agents
Injection: Remote functions automatically injected as function parameters
meshctl: CLI tool for managing, monitoring, and debugging the mesh

Why Developers Love MCP Mesh¶

Zero boilerplate: Just add decorators to existing functions
Graceful degradation: Agents work standalone, enhance when connected
MCP protocol: Full compatibility with existing MCP tools and clients
Local to production: Same code runs locally, in Docker, and Kubernetes
Real-time updates: Hot dependency injection without restarts
Operational visibility: Built-in monitoring and debugging tools

Ready to Start?¶

Choose your path:

🚀 Quick Demo: Try the Docker deployment
🔧 Local Development: Follow the local development guide
🏭 Production Setup: Deploy with Helm to Kubernetes
📚 Deep Dive: Read the architecture and design

💡 Tip: Start with Docker for the complete experience, then try local development for faster iteration.

📚 Note: All examples use the same core agents, so you can easily switch between deployment methods.

🔧 Troubleshooting¶

Common issues when getting started:

Docker Issues:

Port conflicts: Change ports in .env.local file
Build failures: Try docker-compose build --no-cache
Registry connection: Check docker-compose logs registry

Local Development Issues:

Build errors: Ensure Go 1.21+ and Python 3.11+ are installed
Registry not starting: Check if port 8000 is available
Agent connection failures: Verify registry is running first
Import errors: Run make install-dev to install dependencies

Testing Issues:

Tool calls fail: Use /mcp endpoint, not /tools/call
No dependency injection: Wait 30-60 seconds for full mesh setup
JSON errors: Ensure proper JSON-RPC format in curl commands

For detailed solutions, see the troubleshooting sections in each example README.

⚠️ Known Limitations¶

Windows Support: Native Windows support is experimental; WSL2 or Docker recommended
Python 3.10 and below: Not supported; requires Python 3.11+
Network Policies: Strict firewall/network policies may block agent communication

🎯 What's Next?¶

After getting started:

Explore the Examples¶

Modify existing agents to understand the patterns
Add new tools to see dependency injection in action
Test resilience by stopping and starting agents

Build Your Own Agent¶

# Generate a new agent with meshctl scaffold
meshctl scaffold --name my-agent --capability my_tool

# Or generate with Docker Compose
meshctl scaffold --name my-agent --compose

Customize the generated agent code
Add your own capabilities and dependencies
Test integration with existing agents

Scale to Production¶

Deploy to Kubernetes for production workloads
Set up monitoring and alerting
Configure security and access controls

Advanced Features¶

Tag-based dependency resolution
Multi-replica agent deployments
Cross-namespace service discovery
Custom capability development

📚 Additional Resources¶

Local Development - Set up your development environment
Docker Deployment - Deploy agents with Docker Compose
Kubernetes Deployment - Production deployment with Helm
meshctl CLI Reference - Command reference for meshctl