DEV Community: Dhyan Raj

MCP Mesh: 5 Ways It Simplifies Multi-Agent AI Deployment on Kubernetes

Dhyan Raj — Sat, 03 Jan 2026 21:20:55 +0000

TL;DR: MCP Mesh is distributed infrastructure that feels like writing regular Python functions. No YAML. No config drift. Same code runs local, Docker, and Kubernetes.

Deploying multi-agent AI systems on Kubernetes shouldn't require a PhD in YAML. Yet here we are - drowning in Deployments, Services, ConfigMaps, Ingresses, and Service Meshes just to get agents talking to each other.

What if deploying AI agents to Kubernetes was as simple as:

meshctl scaffold --name my-agent --agent-type tool
helm install my-agent oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-agent

MCP Mesh transforms the Model Context Protocol (MCP) into an enterprise-grade distributed system. Here are 5 ways it simplifies multi-agent AI deployment.

1. Decorators Replace YAML - Configure in Code, Not Files

The Problem

Traditional Kubernetes deployments require extensive YAML:

# kubernetes deployment.yaml (abbreviated - real one is 50+ lines)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: datetime-service
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: datetime
        image: datetime-service:v1
        ports:
        - containerPort: 9000
---
apiVersion: v1
kind: Service
metadata:
  name: datetime-service
spec:
  ports:
  - port: 9000

The MCP Mesh Way

Configuration lives in decorators, right next to your code:

from datetime import datetime
import mesh
from fastmcp import FastMCP

app = FastMCP("DateTime Service")

@app.tool()
@mesh.tool(capability="get_datetime", tags=["datetime", "tools"])
def get_datetime() -> str:
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

@mesh.agent(name="datetime-agent", http_port=9000)
class DateTimeAgent:
    pass

# No main(). No server setup. No registration code.

That's a complete, production-ready distributed agent. Deploy it:

meshctl scaffold --name datetime-agent --agent-type tool
helm install datetime-agent oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-agent

Why this matters:

Configuration lives with the code it describes
No drift between code and config
IDE autocomplete and type checking
Refactoring tools work

2. Same Code Runs Locally, in Docker, and on Kubernetes

The Problem

Most frameworks force a one-way street: local → Docker → Kubernetes. Going back to debug locally means recreating your entire stack.

The MCP Mesh Way

The same code runs everywhere - without modification:

┌──────────────────────────────────────────────────────┐
│                    Your Agent Code                   │
│                                                      │
│  @mesh.tool(capability="payment", tags=["tools"])    │
│  def process_payment(amount: float) -> str:          │
│      ...                                             │
└──────────────────────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
     ┌────────┐     ┌──────────┐    ┌─────────┐
     │ Local  │     │  Docker  │    │   K8s   │
     │        │     │ Compose  │    │         │
     └────────┘     └──────────┘    └─────────┘

     meshctl       docker          helm install
     start         compose up

But it goes further - it's bidirectional:

Most frameworks force you forward (local → Docker → K8s). Going back is painful.

MCP Mesh allows movement in any direction:

Local ↔ Docker ↔ K8s

Real scenario: You have 5 agents running in Docker Compose. You want to debug one:

# Stop just that agent in compose
docker compose stop payment-agent

# Run it locally with debugger attached
meshctl start payment-agent/main.py --debug

# It joins the same mesh, works with Docker agents
# Fix the bug, test it live, then promote back to compose

No config changes. The mesh doesn't care where agents run.

"But what about hardcoded ports?"

You might see a decorator like this and wonder:

@mesh.agent(name="payment-agent", http_port=9000)  # Hardcoded port?

Don't I need different ports in different environments? Doesn't this require code changes?

No. MCP Mesh decorators define defaults. Environment variables override them:

# In Kubernetes, the Helm chart sets:
MCP_MESH_HTTP_PORT=8080  # Overrides the decorator's http_port=9000

The code stays the same. The environment controls runtime behavior. Run meshctl man env to see all overridable settings - your decorators are sensible defaults, not hardcoded constraints.

3. Dynamic Dependency Injection Across the Network

The Problem

Spring revolutionized Java with dependency injection - but it's static and limited to a single JVM:

@Autowired
@Qualifier("stripe")
PaymentService payment;  // Wired at startup, fixed forever

MCP Mesh takes DI further - distributed and dynamic:

@mesh.llm(
    filter=[{"capability": "payment", "tags": ["+stripe"]}],
    provider={"capability": "llm"}
)
def checkout(ctx, llm=None):  # Discovered at runtime
    return llm(ctx.input)      # Can change if topology changes

Aspect	Spring DI	MCP Mesh DI
Scope	Single JVM	Distributed network
When	Startup	Runtime (continuous)
Wiring	Static	Dynamic, adapts to topology
Missing dependency	App fails to start	Graceful degradation
Hot swap	Needs restart	Automatic via heartbeat

MCP Mesh is essentially:

Spring DI (dependency injection)
Eureka (service discovery)
Ribbon (load balancing)
Hystrix (circuit breaker)
Config Server (configuration)

...collapsed into simple decorators.

4. Mock Services Without Config Changes

The Problem

Traditional microservices testing requires mocking infrastructure:

# WireMock config, environment variables, test profiles...
payment.service.url=${PAYMENT_URL:http://localhost:8080}

The MCP Mesh Way

MCP Mesh uses tags for environment switching:

# Production agent
@mesh.tool(capability="payment", tags=["payment", "production"])
def real_payment(amount: float) -> str:
    return stripe.charge(amount)

# Local fake (different agent, same capability)
@mesh.tool(capability="payment", tags=["payment"])  # No production
def fake_payment(amount: float) -> str:
    return "FAKE_TXN_123"  # Always succeeds

# Consumer code - never changes
@mesh.llm(filter=[{"tags": ["payment", "+production"]}])
def checkout(ctx, llm=None):
    ...

Environment	What Gets Discovered
Local (dev alone)	Local fake (only one with "payment" tag)
Dev (team)	Real dev service (has production)
Production	Production service (has production)

Same consumer code. Zero configuration changes. Tags control wiring.

Team Development Without Blocking

Traditional microservices:

Developer A (order-service):
  - Needs payment-service (Developer B is building it)
  - Options:
    1. Wait for B → blocked
    2. Mock with WireMock → maintain mock config
    3. Use shared dev env → "who broke dev?"

MCP Mesh:

Developer A:
  - Creates fake payment tool locally (5 lines of Python)
  - Works on order-service against fake
  - When B's real service is ready, A's code automatically uses it
  - No changes to A's code, no coordination needed

The mesh becomes a dependency injection container at runtime - capabilities are interfaces, agents are implementations.

5. Observability From Day One - Including Local Dev

The Problem

Production observability is solved - deploy Grafana, Jaeger, configure exporters. But what about local development? When you're debugging 5 agents on your laptop, you're flying blind. Traditional frameworks offer no tracing until you deploy to an environment with observability infrastructure.

The MCP Mesh Way

MCP Mesh brings distributed tracing to local development - the same meshctl commands work everywhere:

meshctl call assistant --trace '{"input": "What time is it and when is the next daylight savings change?"}'

# Output:
Trace ID: 46d869487656fc6eb7f2e1d10e8ce307

meshctl trace 46d869487656fc6eb7f2e1d10e8ce307

# Output:
├─ assistant (assistant) [2ms]
├─ openai_provider (openai-provider) [1573ms]
├─ get_datetime (datetime-agent) [0ms]
├─ web_search (search-agent) [1669ms]
└─ openai_provider (openai-provider) [4104ms]

Summary: 5 spans across 4 agents | 7.75s

Works everywhere: Local dev, Docker Compose, or production Kubernetes - same commands, same output. Point meshctl at your K8s cluster and trace production requests with the same workflow.

In production, MCP Mesh exports to Grafana/Jaeger like any other system. The difference? You get the same observability on day one of development, not after deploying infrastructure.

Graceful Degradation

What happens when the registry crashes?

Kubernetes + Istio: Service discovery fails, cascading failures, pages at 3am.

MCP Mesh: Agents continue working with cached topology. They keep trying to reconnect, but don't fail. When registry comes back, they sync.

The registry is a coordination point, not a single point of failure.

KISS Score: 8.5/10

For a distributed system framework with:

Service discovery
Dependency injection
Load balancing
Circuit breakers
Distributed tracing
Graceful degradation

...that you can learn in an afternoon, that's remarkable.

Getting Started

# Install
npm install -g @mcpmesh/cli 

# Scaffold an agent
meshctl scaffold --name my-agent --agent-type tool

# Run it
meshctl start my-agent/main.py

# Generate Docker Compose for all agents
meshctl scaffold --compose --observability

# Deploy to Kubernetes
helm install my-agent oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-agent

Conclusion

MCP Mesh proves that distributed systems don't have to feel distributed. These 5 design choices make the difference:

Decorators over YAML - Configuration lives with your code
Same code everywhere - Bidirectional portability across environments
Dynamic DI - Spring-style dependency injection for distributed systems
Tags for switching - Mock services without config changes
Observability from day one - Distributed tracing in local dev, not just production

The result? A framework where the common case is trivial and the hard case is possible.

The best infrastructure is the infrastructure you don't notice. MCP Mesh gets out of your way and lets you build.

MCP Mesh is open source: github.com/dhyansraj/mcp-mesh

How Our AI Hiring Platform Gets Smarter Without Code Changes

Dhyan Raj — Thu, 25 Dec 2025 03:38:37 +0000

Introduction

Last month, our AI hiring platform could only process PDF resumes.

This week, it handles PDFs, Word documents, and scanned images with OCR.

We didn't change a single line of code in our resume processing agent. We just deployed new extractors to the cluster — and the LLM-powered agent started using them automatically.

This is what building on MCP Mesh feels like.

The Platform

We built a multi-agent hiring platform on Kubernetes:

┌─────────────────────────────────────────────────────────────────────────┐
│                         MCP Mesh Registry                               │
│                  (Discovery + Topology + Health)                        │
└─────────────────────────────────────────────────────────────────────────┘
       ▲              ▲                ▲              ▲              ▲
       │              │                │              │              │
  ┌────┴────┐   ┌─────┴─────┐   ┌──────┴──────┐  ┌────┴────┐   ┌─────┴─────┐
  │  Resume │   │    Job    │   │  Interview  │  │ Scoring │   │    LLM    │
  │  Agent  │   │  Matcher  │   │    Agent    │  │  Agent  │   │ Providers │
  │ (LLM)   │   │           │   │   (LLM)     │  │  (LLM)  │   │           │
  └────┬────┘   └───────────┘   └─────────────┘  └─────────┘   └───────────┘
       │
       │ dynamically discovers extractors
       ▼
  ┌───────────────────────────────────────────────────────────────────┐
  │                   Extractor Tools                                 │
  │  ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐            │
  │  │   PDF   │   │   DOC   │   │  Image  │   │ Future  │            │
  │  │Extractor│   │Extractor│   │  (OCR)  │   │   ...   │            │
  │  └─────────┘   └─────────┘   └─────────┘   └─────────┘            │
  │       tags: [extractor, pdf]  [extractor, doc]  [extractor, ocr]  │
  └───────────────────────────────────────────────────────────────────┘

The key insight: agents powered by @mesh.llm don't have hardcoded dependencies. They discover tools at runtime — and intelligently choose which ones to use.

The Resume Agent

Here's the core of our resume processing:

@mesh.llm(
    provider={"capability": "llm", "tags": ["+claude"]},
    filter=[{"tags": ["extractor"]}],  # Discover all extractors
    system_prompt="""You process uploaded resumes.

    Available tools let you extract text from different file formats.
    Choose the appropriate extractor based on the file type.
    Then analyze the extracted text and return structured candidate data.""",
    max_iterations=3,
)
@mesh.tool(
    capability="process_resume",
    tags=["resume", "ai"],
)
async def process_resume(
    file_path: str,
    file_type: str,
    llm: MeshLlmAgent = None
) -> CandidateProfile:
    return await llm(f"Process this {file_type} resume: {file_path}")

The magic is in filter=[{"tags": ["extractor"]}]. The LLM sees every tool tagged with "extractor" — and decides which one to call based on the file type.

Day 1: PDF Only

When we launched, we had one extractor:

# pdf_extractor.py
@mesh.tool(
    capability="extract_pdf",
    tags=["extractor", "pdf"],
    description="Extract text content from PDF files"
)
async def extract_pdf(file_path: str) -> ExtractedText:
    # PDF extraction logic
    return ExtractedText(content=text, metadata={...})

The Resume Agent's LLM sees: Available tools: [extract_pdf]

User uploads resume.pdf → LLM reasons: "This is a PDF, I'll use extract_pdf" → Extracts text → Returns structured profile.

Day 30: Adding Word Support

Product wants Word document support. We write a new extractor:

# doc_extractor.py
@mesh.tool(
    capability="extract_doc",
    tags=["extractor", "doc", "docx"],
    description="Extract text content from Word documents (.doc, .docx)"
)
async def extract_doc(file_path: str) -> ExtractedText:
    # Word extraction logic
    return ExtractedText(content=text, metadata={...})

Deploy to Kubernetes:

helm install doc-extractor oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-agent \
  --version 0.7.12 \
  -n mcp-mesh \
  -f doc-extractor/helm-values.yaml

Within 10 seconds, the Resume Agent's LLM sees: Available tools: [extract_pdf, extract_doc]

User uploads resume.docx → LLM reasons: "This is a Word document, I'll use extract_doc" → Works.

No code change to the Resume Agent. No restart. No config update.

Day 60: Image OCR for Scanned Resumes

HR reports that some candidates upload scanned PDFs or photos of their resumes. We add OCR:

# image_extractor.py
@mesh.tool(
    capability="extract_image_ocr",
    tags=["extractor", "image", "ocr", "scan"],
    description="Extract text from images or scanned documents using OCR"
)
async def extract_image_ocr(file_path: str) -> ExtractedText:
    # OCR logic (Tesseract, Cloud Vision, etc.)
    return ExtractedText(content=text, confidence=0.92, metadata={...})

helm install image-extractor oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-agent \
  --version 0.7.12 \
  -n mcp-mesh \
  -f image-extractor/helm-values.yaml

The Resume Agent's LLM now sees: Available tools: [extract_pdf, extract_doc, extract_image_ocr]

User uploads resume_scan.jpg → LLM reasons: "This is an image, I'll use extract_image_ocr" → Works.

But here's where it gets interesting. User uploads a PDF that's actually a scanned image (no selectable text). The LLM:

Tries extract_pdf → Gets empty/garbled text
Reasons: "The PDF extraction returned garbage. This might be a scanned document."
Calls extract_image_ocr on the same file → Gets clean text
Returns structured profile

The agent got smarter. It learned a new recovery strategy without anyone writing that logic.

We didn't tell the Resume Agent about OCR. We didn't update its prompts. We just deployed an extractor with good tags and a clear description — and the LLM figured out when to use it.

Why This Works

Traditional microservices require explicit wiring:

# Traditional approach - hardcoded routing
def process_resume(file_path: str, file_type: str):
    if file_type == "pdf":
        text = call_pdf_service(file_path)
    elif file_type in ["doc", "docx"]:
        text = call_doc_service(file_path)
    elif file_type in ["jpg", "png"]:
        text = call_ocr_service(file_path)
    else:
        raise UnsupportedFormatError(file_type)
    # ...

Every new format requires code changes, redeployment, and testing.

MCP Mesh with @mesh.llm inverts this:

Tools self-describe — Each extractor has tags and descriptions
LLM discovers tools — filter=[{"tags": ["extractor"]}] broadcasts intent
LLM reasons about tools — Chooses based on context, not hardcoded rules
Mesh handles routing — Tool calls go to the right agent automatically

The Resume Agent's code stays frozen. The platform's capabilities expand with each helm install.

The Enterprise Reality

This isn't a toy demo. It's running in production:

Aspect	Traditional	MCP Mesh
Adding new file format	Code change + deploy + test	helm install
Config files for routing	Per-service	0
Recovery logic for edge cases	Manual if/else	LLM figures it out
Time to add capability	Hours/days	Minutes

Infrastructure

# One-time cluster setup
helm install mcp-core oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-core \
  --version 0.7.12 \
  -n mcp-mesh --create-namespace

# Deploys: Registry + PostgreSQL + Redis + Tempo + Grafana

Same agent code runs locally (meshctl start), in Docker Compose, and in Kubernetes. Only the infrastructure changes.

What the LLM Sees

When the Resume Agent's LLM runs, it receives a tool list like:

{
  "tools": [
    {
      "name": "extract_pdf",
      "description": "Extract text content from PDF files",
      "tags": ["extractor", "pdf"],
      "input_schema": {"file_path": "string"}
    },
    {
      "name": "extract_doc",
      "description": "Extract text content from Word documents (.doc, .docx)",
      "tags": ["extractor", "doc", "docx"],
      "input_schema": {"file_path": "string"}
    },
    {
      "name": "extract_image_ocr",
      "description": "Extract text from images or scanned documents using OCR",
      "tags": ["extractor", "image", "ocr", "scan"],
      "input_schema": {"file_path": "string"}
    }
  ]
}

The LLM reads descriptions, understands capabilities, and makes intelligent choices. Add a new tool? It appears in this list within seconds.

LLM Failover (Bonus)

We run two LLM providers:

helm install claude-provider oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-agent \
  -f claude-provider/helm-values.yaml -n mcp-mesh

helm install openai-provider oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-agent \
  -f openai-provider/helm-values.yaml -n mcp-mesh

The Resume Agent's provider={"capability": "llm", "tags": ["+claude"]} prefers Claude.

When Claude's API goes down:

Mesh detects unhealthy (missed heartbeats)
Topology updates
Next request routes to OpenAI
When Claude recovers, traffic returns

Zero failover code. It's how the mesh works.

What's Next

This article showed what we built — an AI platform that genuinely gets smarter as you add capabilities.

The next article explains why we chose MCP over REST as the foundation — and why that choice matters more than you might think.

👉 [Next: MCP vs REST — Why MCP is the better microservice protocol]

Resources

MCP Mesh: A Distributed Runtime for AI Agents with Auto-Discovery

Dhyan Raj — Tue, 23 Dec 2025 17:23:08 +0000

I've been building MCP Mesh for the past 5 months — a distributed-first runtime for AI agents built on MCP protocol.

The Problem

Most agent frameworks assume monolithic deployment and manual wiring. You define agents, manually connect them, and hope it scales.

MCP Mesh takes a different approach.

What Makes It Different

Distributed from day one — Agents are microservices, not threads in a monolith
Auto-discovery — Agents register with a mesh registry and find each other by capability tags
Dependency injection — Declare what your agent needs, the mesh provides it at runtime
Deterministic behavior — Despite being distributed, agent interactions are predictable
LLM failover — Switch providers without code changes, just registry config
Native MCP — Built on the protocol, not wrapped around it

Observability is built in (Grafana + Tempo), and it's Kubernetes-ready with Helm charts.

DEV Community: Dhyan Raj

MCP Mesh: 5 Ways It Simplifies Multi-Agent AI Deployment on Kubernetes

1. Decorators Replace YAML - Configure in Code, Not Files

The Problem

The MCP Mesh Way

2. Same Code Runs Locally, in Docker, and on Kubernetes

The Problem

The MCP Mesh Way

3. Dynamic Dependency Injection Across the Network

The Problem

4. Mock Services Without Config Changes

The Problem

The MCP Mesh Way

Team Development Without Blocking

5. Observability From Day One - Including Local Dev

The Problem

The MCP Mesh Way

Graceful Degradation

KISS Score: 8.5/10

Getting Started

Conclusion

How Our AI Hiring Platform Gets Smarter Without Code Changes

Introduction

The Platform

The Resume Agent

Day 1: PDF Only

Day 30: Adding Word Support

Day 60: Image OCR for Scanned Resumes

Why This Works

The Enterprise Reality

What the LLM Sees

LLM Failover (Bonus)

What's Next

Resources

MCP Mesh: A Distributed Runtime for AI Agents with Auto-Discovery

The Problem

What Makes It Different

Links