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 1.0.0-beta.3 -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 0.9.9 -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 Isolation

Separate admin APIs from the agent-facing port for defense in depth:

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

Security Guide — Run meshctl man security for the full security reference.

Next Steps