Skip to content

Docker Deployment

Package and run MCP Mesh agents in containers for consistent, portable deployments

Overview

Docker provides a consistent environment for running MCP Mesh agents across different systems. This section covers building Docker images for your agents, running multi-agent systems with Docker Compose, and preparing for container orchestration platforms.

Whether you're containerizing a single agent or building a complex multi-service mesh, Docker ensures your agents run the same way everywhere - from your laptop to production servers.

What You'll Learn

By the end of this section, you will:

  • ✅ Build optimized Docker images for MCP Mesh agents
  • ✅ Configure multi-agent systems with Docker Compose
  • ✅ Implement service discovery in containerized environments
  • ✅ Manage persistent data and configuration
  • ✅ Set up networking for agent communication
  • ✅ Prepare for Kubernetes deployment

Why Docker for MCP Mesh?

Docker solves several challenges in distributed agent deployment:

  1. Consistency: Same environment everywhere, no "works on my machine"
  2. Isolation: Agents run in separate containers with defined resources
  3. Portability: Move from development to production seamlessly
  4. Scalability: Easy to run multiple instances of agents
  5. Dependency Management: All dependencies packaged with the agent

Docker Architecture for MCP Mesh

┌─────────────────────────────────────────────────────────────┐
│                    Docker Host                               │
│                                                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │  Registry        │  │  Weather Agent   │  │  System     │ │
│  │  Container       │  │  Container       │  │  Agent      │ │
│  │                  │  │                  │  │  Container  │ │
│  │  ┌─────────────┐ │  │  ┌─────────────┐ │  │  ┌────────┐│ │
│  │  │ Go Registry │ │  │  │ Python Agent│ │  │  │ Python ││ │
│  │  │ PostgreSQL  │ │  │  │ MCP Mesh    │ │  │  │ Agent  ││ │
│  │  └─────────────┘ │  │  └─────────────┘ │  │  └────────┘│ │
│  └────────┬─────────┘  └────────┬─────────┘  └──────┬─────┘ │
│           │                      │                    │       │
│  ┌────────┴──────────────────────┴────────────────────┴────┐ │
│  │                   Docker Network (mesh-net)              │ │
│  └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Section Contents

  1. Building Docker Images - Create optimized images for agents
  2. Docker Compose Setup - Orchestrate multi-agent systems
  3. Multi-Agent Deployment - Run complex agent networks
  4. Networking and Service Discovery - Container communication
  5. Persistent Storage - Data persistence strategies

Quick Start Example

Here's a complete Docker Compose setup to get you started:

# docker-compose.yml
version: "3.8"

services:
  registry:
    build:
      context: .
      dockerfile: docker/registry/Dockerfile
    ports:
      - "8000:8000"
    environment:
      MCP_MESH_DB_TYPE: postgresql
      MCP_MESH_DB_HOST: postgres
      MCP_MESH_DB_NAME: mcp_mesh
      MCP_MESH_DB_USER: postgres
      MCP_MESH_DB_PASSWORD: postgres
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: mcp_mesh
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  system-agent:
    build:
      context: .
      dockerfile: docker/agent/Dockerfile
    command: ["./bin/meshctl", "start", "examples/simple/system_agent.py"]
    environment:
      MCP_MESH_REGISTRY_URL: http://registry:8000
    depends_on:
      - registry

  weather-agent:
    build:
      context: .
      dockerfile: docker/agent/Dockerfile
    command: ["./bin/meshctl", "start", "examples/simple/weather_agent.py"]
    environment:
      MCP_MESH_REGISTRY_URL: http://registry:8000
    depends_on:
      - registry
      - system-agent

volumes:
  postgres_data:

networks:
  default:
    name: mesh-net

Run it with:

docker-compose up -d
docker-compose logs -f

Key Concepts for Docker Deployment

1. Image Layers and Caching

Build efficient images with proper layering:

# Good: Layers that change less frequently first
FROM python:3.11-slim
WORKDIR /app

# Install MCP Mesh from source
COPY . .
RUN make install-dev

# Run agent
CMD ["./bin/meshctl", "start", "examples/simple/agent.py"]

2. Environment Configuration

Use environment variables for configuration:

# Development
docker run -e MCP_MESH_LOG_LEVEL=DEBUG my-agent

# Production
docker run -e MCP_MESH_LOG_LEVEL=INFO my-agent

3. Health Checks

Ensure containers are ready before dependent services start:

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:8081/health || exit 1

Development Workflow with Docker

  1. Build Once, Run Anywhere
docker build -t my-agent:latest .
docker run my-agent:latest
  1. Local Development with Bind Mounts
docker run -v $(pwd)/agents:/app/agents my-agent:latest
  1. Multi-Stage Builds for Optimization
FROM python:3.11 AS builder
# Build stage

FROM python:3.11-slim
# Runtime stage

Best Practices

  • 🔒 Security: Never embed secrets in images
  • 📦 Size: Use slim base images and multi-stage builds
  • 🏷️ Tagging: Use semantic versioning for image tags
  • 📝 Documentation: Include README in image with usage instructions
  • 🔄 Updates: Regularly update base images for security patches

Ready to Start?

Begin with Building Docker Images →

🔧 Troubleshooting

Common Docker Issues

  1. Container can't connect to registry

  2. Check network configuration

  3. Verify service names in compose file

  4. Ensure registry is healthy before agents start

  5. Agent exits immediately

  6. Check logs: docker logs <container>

  7. Verify CMD or ENTRYPOINT is correct

  8. Ensure required environment variables are set

  9. Permission denied errors

  10. Run containers as non-root user
  11. Check file permissions in image
  12. Use proper volume mount permissions

For detailed solutions, see our Docker Troubleshooting Guide.

⚠️ Known Limitations

  • Windows Containers: Limited support, use Linux containers
  • ARM Architecture: Some base images may not support ARM
  • File Watching: Hot reload doesn't work well in containers
  • Networking: Container networking adds complexity to debugging

📝 TODO

  • Add Kubernetes deployment examples
  • Create automated image vulnerability scanning
  • Add examples for cloud container registries
  • Document multi-architecture builds
  • Add container security best practices guide

💡 Tip: Use Docker BuildKit for faster builds: DOCKER_BUILDKIT=1 docker build .

📚 Reference: Official Docker Documentation

🎯 Next Step: Ready to containerize your agents? Start with Building Docker Images