Why MCP Mesh?¶

The problem isn't building an agent. It's everything that happens when agents need each other.¶

Every framework helps you build an agent. Then the real work starts: that agent needs another — and in production the other one moves, dies, gets a new version, scales to ten copies, runs an LLM, holds state, or is written in another language. Most frameworks hand you a pile of separate problems — service discovery here, a retry library there, a job queue, a config system, a deployment story — and say "that's your problem," five times over.

Mesh has one answer to all of them, and it's a single idea: Distributed Dynamic Dependency Injection (DDDI). You declare what a piece of your system needs — a capability — and the mesh finds it, types it, health-routes it, and hot-swaps it at runtime, across machines and languages. That's the whole primitive. Everything else in mesh is a consequence of it — which is why mesh is large in features but small in ideas.

Because a dependency is a live, resolved capability, problems that are normally entire subsystems just fall out:

• An LLM is a dependency → "prefer Claude, fall back to Gemini," model routing, and provider failover become declarations, not integrations.
• A long-running job is a dependency that outlives the call → durable jobs, resume, and cancel come for free — same primitive, longer lifetime.
• A group of capabilities is a dependency you bundle → a typed service view, functions from many agents behind one interface each resolving on its own, is just DDDI applied N times.
• A dependency that moved, died, or upgraded re-wires itself → the running consumer never restarts; a better provider appears and it rebinds live.
• A Python capability consumed by Java is still just a dependency → polyglot, typed, identical semantics, because the mesh owns the contract, not the language.
• Local and Kubernetes are the same declaration → same code, different transport; there's no second mental model between "build" and "deploy."

None of those is a bolt-on you integrate. They're the same idea from different angles. The traditionally-hard parts of a distributed AI system don't get solved in mesh so much as they stop being separate problems.

So the "why" isn't "mesh has a feature for that." It's: learn one idea — DDDI — and a platform's worth of hard problems quietly disappears. You describe what your agents need; the mesh makes it true, keeps it true, and rearranges the world underneath them without asking.

And yes — it also deploys to Kubernetes, scales each agent independently, and traces every call. But that's the reassurance, not the reason.

MCP Mesh: Build AND Deploy¶

MCP Mesh is a complete platform for building and deploying AI agents. You don't need LangGraph, CrewAI, or AutoGen.

What MCP Mesh Provides¶

Simple Example¶

import mesh
from fastmcp import FastMCP

app = FastMCP("My Agent")

# Define a tool with automatic dependency injection
@app.tool()
@mesh.tool(capability="greeting", dependencies=["time_service"])
async def greet(name: str, time_service: mesh.McpMeshTool = None):
    current_time = await time_service() if time_service else "unknown"
    return f"Hello {name}! The time is {current_time}"

# Register as an agent
@mesh.agent(name="greeting-agent", port=8080)
class GreetingAgent:
    pass

That's a complete agent with:

• Tool that other agents can call
• Automatic registration with the mesh
• Dependency injection from other agents

Framework Comparison¶

Key Insight¶

• LangGraph/CrewAI/AutoGen = Agent building frameworks (no deployment)
• MCP Mesh = Agent building + deployment + scaling + observability

What Makes MCP Mesh Different¶

1. True DDDI (Distributed Dynamic Dependency Injection)¶

DDDI is the one idea everything above rests on — no other framework has it. If you skipped the opener: dependencies are discovered, typed, health-routed, and hot-swapped at runtime across machines and languages, with no config files and no restarts. What is DDDI? →

2. Decorators That Do Everything¶

@mesh.agent(name="my-agent", port=8080)                      # Register with mesh
@mesh.tool(capability="process")                              # Expose as callable tool
@mesh.llm(provider={"capability": "llm", "tags": ["+claude"]}) # Add LLM capabilities
@mesh.route("/api/endpoint")                                  # REST API endpoint

3. Automatic Dependency Injection¶

@mesh.tool(
    capability="analyze_data",
    dependencies=["db_service", "ml_service"]
)
async def analyze(data, db_service: mesh.McpMeshTool = None, ml_service: mesh.McpMeshTool = None):
    # db_service and ml_service are automatically injected
    # MCP Mesh finds them, connects them, handles failures
    records = await db_service(query=data) if db_service else {}
    return await ml_service(data=records) if ml_service else {}

4. One Command to Production¶

# Generate Docker Compose with observability
meshctl scaffold --compose --observability

# Or deploy to Kubernetes (OCI registry)
helm install my-mesh oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-core \
  --version 3.7.1 -n mcp-mesh --create-namespace

5. Built-in Observability¶

• Grafana dashboards - Pre-configured for agent metrics
• Distributed tracing - See request flow across agents
• Health monitoring - Automatic health checks and alerting

When to Use MCP Mesh¶

Use MCP Mesh When:¶

• Building multi-agent AI systems
• Deploying agents to Kubernetes or Docker
• Agents need to discover and call each other
• You want independent scaling per agent
• You need production observability

Maybe Skip MCP Mesh When:¶

• Single agent running locally only
• Pure prototyping with no deployment plans

Quick Comparison: Deploying 5 Agents¶

Without MCP Mesh¶

├── agent-1/
│   ├── Dockerfile
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
├── agent-2/
│   └── ... (repeat)
├── service-discovery/
│   └── (build your own)
└── monitoring/
    └── (set up yourself)

Result: 50+ files, weeks of work

With MCP Mesh¶

# 5 Python files with @mesh.agent decorators

meshctl scaffold --compose --observability
docker-compose up

Result: 5 files + 1 command

Already Using Another Framework?¶

If you're already invested in LangGraph, CrewAI, or AutoGen, MCP Mesh can help you deploy them to production:

• Wrap your existing agents with @mesh.agent
• Get automatic K8s deployment via Helm
• Add observability without code changes
• Scale agents independently

MCP Mesh doesn't replace your agent logic - it handles the infrastructure so you don't have to.

15 Requirements, 14 Lines of Code¶

Here's a real-world agent spec: a portfolio analyzer that needs provider failover, multi-tool discovery, structured output, context-aware prompts, and mesh registration. That's 15 requirements — and each one maps to a single line or decorator parameter.

The Requirements¶

The Implementation¶

@mesh.llm(
    provider={"capability": "llm", "tags": [
        ["+anthropic", "+sonnet"],  # Primary (score 2)
        ["+gemini"],                # Secondary (score 1)
    ]},
    filter=[{"tags": ["financial"]}, {"tags": ["data"]}],
    system_prompt="file://prompts/analyst.jinja2",
    context_param="ctx",
    max_iterations=5,
)
@mesh.tool(capability="analyze_portfolio")
async def analyze(
    query: str, ctx: AnalysisContext, llm: mesh.MeshLlmAgent = None
) -> PortfolioAnalysis:
    return await llm(query)

agent.addLlmTool({
  name: "analyze",
  provider: { capability: "llm", tags: [
    ["+anthropic", "+sonnet"],  // Primary (score 2)
    ["+gemini"],                // Secondary (score 1)
  ]},
  filter: [{ tags: ["financial"] }, { tags: ["data"] }],
  systemPrompt: "file://prompts/analyst.jinja2",
  contextParam: "ctx",
  maxIterations: 5,
  capability: "analyze_portfolio",
  returns: PortfolioAnalysisSchema,
  execute: async ({ query, ctx }, { llm }) => {
    return await llm(query);
  },
});

@MeshLlm(
    providerSelector = @Selector(
        capability = "llm",
        filter = {
            @Tags({"+anthropic", "+sonnet"}),  // Primary (score 2)
            @Tags({"+gemini"})                 // Secondary (score 1)
        }
    ),
    filter = @Selector(tags = {"financial", "data"}),
    systemPrompt = "classpath:prompts/analyst.ftl",
)
@MeshTool(capability = "analyze_portfolio")
public PortfolioAnalysis analyze(String query, MeshLlmAgent llm) {
    return llm.request().user(query).generate(PortfolioAnalysis.class);
}

Every requirement is handled. The provider selector has two tag groups — Claude matches both +anthropic and +sonnet (score 2), while Gemini matches only +gemini (score 1). The mesh deterministically selects the highest-scoring provider and falls back automatically. Filter tags (financial, data) are hard requirements — only tools with those capabilities are wired in. No HTTP clients, no retry logic, no service discovery code. The mesh does it all.

Key Features¶

The cards above are a summary; Feature Comparison has the detailed treatment of the same ground, feature by feature.

Who it is for¶

Next Steps¶

Ready to build your first agent?

Get Started in 5 Minutes View Architecture