Skip to content

Deployment

Choose the right deployment method for your environment

Overview

MCP Mesh supports multiple deployment options to fit your infrastructure needs. Whether you're developing locally or deploying to production Kubernetes clusters, MCP Mesh has you covered.

Deployment Options

Docker

Best for: Local development, testing, simple deployments

  • Quick setup with Docker Compose
  • Pre-built images available
  • Auto-generated compose files with meshctl scaffold
  • Great for development and testing
# Quick start
meshctl scaffold --name my-agent --compose
docker-compose up

Docker Guide

Kubernetes

Best for: Production deployments (Recommended)

  • Helm charts
  • Horizontal pod autoscaling
  • Built-in observability (Grafana, Tempo)
  • Multi-environment support
# Quick start (OCI registry - no helm repo add needed)
helm install mcp-registry oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-registry \
  --version 3.7.1 -n mcp-mesh --create-namespace

Kubernetes Guide

Quick Comparison

Feature Docker Kubernetes
Setup Complexity Easy Medium
Production Ready Limited Yes
Scaling Manual Automatic (HPA)
Observability Built-in (opt-in) Built-in (opt-in)
Best Use Case Development Production

Which Should I Choose?

Use Docker if you want to:

  • Get started quickly with minimal setup
  • Develop and test locally
  • Run a simple proof-of-concept
  • Use Docker Compose for orchestration

Use Kubernetes if you want to:

  • Deploy to production
  • Scale agents independently
  • Use enterprise features (monitoring, tracing)
  • Follow GitOps practices

Recommendation

For production deployments, we strongly recommend Kubernetes with Helm charts. They include tested configurations, built-in observability, and follow Kubernetes best practices.

Deployment Path

graph LR
    A[Start] --> B{Environment?}
    B -->|Local Dev| C[Docker]
    B -->|Production| D[Kubernetes]
    C -->|Scale Up| D

Security & Governance

MCP Mesh provides built-in security features for production deployments.

TLS Encryption

Enable mutual TLS between agents and the registry:

# Local development with auto-generated certificates
meshctl start --registry-only --tls-auto -d
meshctl start my_agent.py

For Kubernetes, configure TLS via Helm values:

helm install mcp-registry oci://ghcr.io/dhyansraj/mcp-mesh/mcp-mesh-registry \
  --version 3.7.1 -n mcp-mesh --create-namespace \
  --set registry.security.tls.mode=strict \
  --set registry.security.trust.backend=k8s-secrets

Entity Trust

Control which organizations' agents can join the mesh using entity CA certificates:

meshctl entity register "partner-corp" --ca-cert /path/to/partner-ca.pem
meshctl entity list
meshctl entity revoke "partner-corp" --force
meshctl entity rotate  # Trigger re-verification

Certificate Rotation

Rotate certificates without downtime — agents re-register on their next heartbeat:

meshctl entity rotate                    # All agents re-register
meshctl entity rotate "partner-corp"     # Specific entity only

Agents with revoked certificates are automatically evicted in strict TLS mode.

Admin Port

Serve the admin APIs on their own port so they can be restricted separately at the network layer:

# Registry listens on 8000 (agents) and 8001 (admin only)
MCP_MESH_ADMIN_PORT=8001 mcp-mesh-registry

By default the admin listener is plain http:// and applies no client-certificate check, whatever MCP_MESH_TLS_MODE is set to, so front it with a NetworkPolicy or equivalent — a separate port is not a security boundary on its own. Set MCP_MESH_ADMIN_TLS=true to give it the registry's certificate and client-certificate policy; run meshctl man security first, since that switches the port to https:// and meshctl cannot present a client certificate.

CLI Reference — Run meshctl man cli for the full command reference.

Next Steps