Forem: Dhyan Raj

Service Mesh for MCP Agents — Without the Sidecar

Dhyan Raj — Thu, 16 Apr 2026 22:04:17 +0000

Remember the first time you installed Istio?

The pitch was beautiful. mTLS everywhere. Automatic retries. Distributed tracing. Traffic shifting with a YAML file. You ran istioctl install, got a coffee, came back, and discovered every pod had grown a 50MB Envoy companion. Memory usage doubled. Cold starts crawled. Your Helm chart sprouted a proxy.resources.limits block. And every six months, you'd schedule a maintenance window to upgrade the control plane and pray nothing in the data path broke.

Service meshes are extraordinary. They're also expensive — in CPU, in mental load, in operational surface area.

So here's the question we kept asking while building MCP Mesh:

What if you could have everything a service mesh gives you, but built into the agents themselves — no sidecar, no control plane, no CRDs?

Not as a thought experiment. As a thing you can pip install today.

The five jobs of a service mesh

Strip away the marketing and a service mesh does five things:

Discovery — find the right backend without hardcoding hosts.
mTLS — every call mutually authenticated, automatically.
Traffic policy — retries, timeouts, circuit breaking, canaries.
Observability — every hop traced, every error surfaced.
Identity — workloads have provable identity that survives across orgs.

These are real production needs. They didn't go away with AI agents. If anything, they got worse: now you've got Python agents calling TypeScript agents calling Java agents calling Claude. Discovery, mTLS, retries — all the same problems, dressed in fashion.

So why not just wrap MCP agents in Envoy and ship?

You can. People do. And then they're back to two binaries per workload, a control plane to babysit, and the joy of debugging "is the sidecar healthy or is the app healthy?"

Why sidecars exist

Be fair to the sidecar pattern. It exists for one excellent reason: the application doesn't know about the mesh, and you don't want to make it know.

If you have a hundred microservices written by ten teams across five years in three languages, asking each of them to integrate a mesh SDK is a non-starter. The sidecar lets you bolt the mesh on from the outside. It's a retrofit.

But MCP agents are new code. They're being written now, on a protocol designed now, for an ecosystem that's barely two years old. We don't have to retrofit. We can put the mesh inside the agent.

That's what MCP Mesh does.

Registry as facilitator, not proxy

The architecture is one diagram:

┌─────────┐     Heartbeat / Topology     ┌──────────┐
│ Agent A │ ──────────────────────────►  │ Registry │
│         │ ◄──────────────────────────  │          │
└─────────┘                              └──────────┘
     │
     │ Direct MCP call (mTLS)
     ▼
┌─────────┐
│ Agent B │
└─────────┘

Two things to notice.

First: the registry never sits in the data path. Agents heartbeat in every five seconds, get back the topology of who provides what, and then call each other directly. The registry is a phone book, not a telephone exchange.

Second: if the registry dies, your agents keep talking. They've got the topology cached. New agents can't join until it's back, but existing traffic flows uninterrupted. Try that with Pilot down.

This is the move that makes "no sidecar" possible. You don't need a proxy because the destination is already known to the source. The mesh isn't between agents; it is the agents.

Walking the service-mesh feature list

Let's go down the checklist and show what each one looks like in MCP Mesh.

Discovery → declare what you need, get it injected

@mesh.tool(
    capability="plan_trip",
    dependencies=[
        {"capability": "weather", "tags": ["+claude"]},
        {"capability": "hotels"},
        {"capability": "flights"},
    ],
)
async def plan_trip(
    destination, dates,
    weather: mesh.McpMeshTool = None,
    hotels:  mesh.McpMeshTool = None,
    flights: mesh.McpMeshTool = None,
):
    forecast = await weather(destination=destination, dates=dates)
    options  = await hotels(destination=destination, dates=dates)
    routes   = await flights(destination=destination, dates=dates)
    return TripPlan(forecast, options, routes)

No service host. No port. No DNS lookup. You declared what you need; the mesh handed you a callable. The proxy is in the function signature.

When a new weather provider comes online — better, faster, cheaper — your call goes there on the next heartbeat tick. Zero deploy. Zero code change.

mTLS → one flag

meshctl start --registry-only --tls-auto
meshctl start my_agent.py --tls-auto

That generates a mini-CA, issues certs to every agent, and turns on mutual TLS for every call. In production, swap the file provider for SPIRE or Vault:

export MCP_MESH_TLS_PROVIDER=spire
export MCP_MESH_SPIRE_SOCKET=/run/spire/agent/sockets/agent.sock

SPIFFE-aware out of the box. URI SANs, not DNS SANs. Private keys live in /dev/shm so they never touch disk. No Citadel install. No mesh-wide rollout. Each agent picks up its identity at startup and uses its language's native TLS stack — httpx in Python, tls in Node, SSLContext in Java.

The mesh isn't a layer below your app. It's a few lines inside it.

Multi-org trust → entities, not federation

In a real enterprise mesh you've got two orgs that need to talk. Service mesh answer: federation, trust bundles, multi-cluster. MCP Mesh answer:

meshctl entity register "partner-corp" --ca-cert /path/to/ca.pem

Done. Their agents are now trusted peers in your mesh.

Traffic policy → kwargs, not VirtualService

@mesh.tool(
    dependencies=["slow_service"],
    dependency_kwargs={
        "slow_service": {
            "timeout": 60,
            "retry_count": 3,
            "streaming": True,
            "session_required": True,
        }
    },
)
async def my_tool(slow_service: mesh.McpMeshTool = None):
    return await slow_service(payload=...)

That's your DestinationRule. In Python. Type-checkable. Diff-reviewable. Lives next to the code that uses it.

Want canaries? Tags do that:

dependencies=[
    {"capability": "math", "tags": ["addition", ["python", "typescript"]]},
]

Try the Python provider first; if not available, fall back to TypeScript. That's a shadow deploy, a canary, and a fallback policy in one tag expression.

Header propagation → one env var

Auth tokens, tenant IDs, correlation headers — they need to flow end-to-end through the call chain.

export MCP_MESH_PROPAGATE_HEADERS=authorization,x-tenant-id,x-request-id

Set it on every agent. Inbound headers matching the allowlist get captured into request-scoped context (Python uses contextvars for async safety) and re-injected into every downstream call automatically. No middleware. No Envoy filter. No code in your tool functions.

Observability → one flag and a Helm chart

export MCP_MESH_DISTRIBUTED_TRACING_ENABLED=true
helm install mcp-core oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-core --version 1.3.3

That ships you a Tempo backend, a Grafana with dashboards pre-loaded, OTLP wired up between every agent. Then:

$ meshctl trace abc123def456

└─ plan_trip (trip-planner) [245ms] ✓
   ├─ weather (claude-weather) [120ms] ✓
   │  └─ llm:claude (claude-provider) [98ms] ✓
   ├─ hotels (gpt-hotels) [80ms] ✓
   └─ flights (flight-agent) [40ms] ✓

Every hop. Every agent. Every LLM call. From your terminal.

The thing service meshes can't do

Here's where MCP Mesh stops looking like Istio and starts looking like something new.

A service mesh routes traffic. Bytes from one socket to another. Your code still has to know there's an HTTP client in there, construct a URL, parse a response, deserialize JSON, handle the error envelope.

MCP Mesh routes function calls.

forecast = await weather(destination=destination, dates=dates)

That weather is a Python callable. It happens to live in another process, on another machine, written in another language, possibly powered by an LLM. You can't tell from the code. You don't have to. The mesh handed you a function. You called it. The result came back typed.

We call this DDDI — Distributed Dynamic Dependency Injection. Spring gave us DI on a single JVM. Guice gave it to us in fewer lines. MCP Mesh gives it to us across the network, across runtimes, across language boundaries.

The proxy is in your function signature. That's the move.

And it composes:

weather = reasoning_weather if user.wants_explanation else api_weather
forecast = await weather(destination, dates)

That's a routing decision in Python. In an if. Not a VirtualService. Not a percentage split in YAML. The full power of your language, applied to traffic shaping.

"But it only meshes MCP agents…"

That's where the skeptic leans in. Sure, sure, but I've got Postgres, a REST API, a vector DB, and a legacy SOAP service. Your shiny mesh doesn't help me with any of those.

Hold up.

MCP isn't a wire format for AI gimmicks. MCP is a tool protocol with typed schemas, streaming, structured errors, and bidirectional communication built in. Wrap your Postgres in an MCP tool — it's now a mesh participant. Wrap your REST API — same. Your RAG pipeline, your S3 bucket, your billing system — every one of those is one @mesh.tool away from being a first-class member of the mesh, with mTLS, retries, tracing, and discovery, for free.

And here's the kicker: MCP is arguably a better default than REST for new internal services.

Schemas, without dragging OpenAPI tooling along.
Streaming, without SSE plumbing.
Tool discovery, without a Swagger portal.
Bidirectional, without WebSocket gymnastics.

If you're building a new internal API in 2026, you should at least consider exposing it over MCP. The ergonomics are better. The schemas are first-class. The tooling is finally catching up. This isn't AI hype — this is what REST should have evolved into a decade ago.

But say you're not ready to MCP-ify everything. The proxy layer in MCP Mesh — EnhancedUnifiedMCPProxy — already abstracts transport from semantics. Adding a REST adapter is an architectural extension, not a rewrite. gRPC, the same. The mesh isn't tied to MCP. MCP is just the first protocol it speaks. Multi-protocol mesh isn't a roadmap dream — it's an extension point sitting in the codebase right now.

This isn't a narrow tool for a niche protocol. This is a paradigm shift in how distributed systems get composed, and MCP happens to be the protocol that made the shift cheap enough to ship.

So here's the punchline

For the K8s crowd: you can have a mesh without the proxy tax. mTLS, discovery, retries, tracing, identity — all of it — delivered in-process, debuggable in your own language, with no second binary per pod.

For the application developer: you can call a remote agent like a local function, in any of three languages, with the proxy in your function signature.

For the platform team: you get a control plane that fits in one binary, scales to thousands of agents, and stays out of the data path.

For everyone: the mesh isn't bolted on. It is the agents.

If you searched "service mesh for MCP agents" and ended up here — congratulations. You found the only one.

And it doesn't have a sidecar.

npm install -g @mcpmesh/cli
meshctl scaffold

Welcome to the mesh.

Docs · GitHub · Discord · YouTube

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.

Forem: Dhyan Raj

Service Mesh for MCP Agents — Without the Sidecar

The five jobs of a service mesh

Why sidecars exist

Registry as facilitator, not proxy

Walking the service-mesh feature list

Discovery → declare what you need, get it injected

mTLS → one flag

Multi-org trust → entities, not federation

Traffic policy → kwargs, not VirtualService

Header propagation → one env var

Observability → one flag and a Helm chart

The thing service meshes can't do

"But it only meshes MCP agents…"

So here's the punchline

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