Running MCP Servers in Docker: Setup, Security, and Production Patterns

Running MCP servers directly on your host means installing runtimes, managing dependencies, and trusting every server with full access to your system. Docker changes the equation: each MCP server runs in its own isolated container with controlled access to files, networks, and secrets.

This guide covers why Docker is becoming the default way to run MCP servers, how to set it up, and the patterns that work in production. Our analysis draws on Docker’s official MCP documentation, published SDK guides, deployment platform documentation, and community implementations — we research and analyze rather than building production MCP systems ourselves.

Why Docker for MCP Servers?

Three problems drive the adoption of containerized MCP servers:

Security isolation. An MCP server running natively on your machine has access to your file system, environment variables, and network. If the server code is malicious — or if an LLM manipulates it through prompt injection — the blast radius is your entire development environment. Docker containers restrict what the server can see and do.

Dependency management. MCP servers are written in Python, TypeScript, Go, Rust, and more. Running ten servers might require three Python versions, two Node runtimes, and system libraries that conflict with each other. Docker eliminates this: each server ships its own runtime.

Reproducibility. A Dockerized MCP server works the same on macOS, Linux, and Windows. No more “works on my machine” debugging when sharing server configurations with a team.

Option 1: Docker MCP Toolkit (The Easy Path)

Docker Desktop 4.62+ includes the MCP Toolkit — a built-in system for browsing, installing, and connecting MCP servers from a curated catalog.

Setup

1. Install or update Docker Desktop to version 4.62 or later
2. Open Docker Desktop → Settings → Beta features
3. Enable Docker MCP Toolkit
4. Click MCP Toolkit in the left sidebar

Browsing the Catalog

The Docker MCP Catalog is a curated collection of MCP servers from verified publishers — Stripe, Elastic, Grafana, GitHub, and others. Each server listing includes:

• What tools and resources it exposes
• Required configuration (API keys, settings)
• Compatibility information

Click a server, configure any required settings (like API keys), and add it to a profile.

Profiles

Profiles group MCP servers into collections. You might create:

• A development profile with GitHub, filesystem, and database servers
• An analytics profile with Grafana, Elastic, and data pipeline servers
• A writing profile with web search, Wikipedia, and note-taking servers

Connecting to AI Clients

The Toolkit integrates with 13+ clients:

For Claude Desktop, clicking Connect in the Toolkit writes the configuration automatically to claude_desktop_config.json:

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

For a specific profile:

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "development"]
    }
  }
}

Restart the client after connecting. Verify with:

• Claude Desktop: Check the MCP connection indicator in the UI
• Claude Code: claude mcp list
• VS Code: Check MCP status in the command palette

How the Gateway Works

The Toolkit creates a Gateway MCP Server — a single process that dynamically exposes tools from all servers in the active profile. Your AI client connects to one gateway, not to each server individually. The gateway handles:

• Starting and stopping individual server containers
• Routing tool calls to the correct server
• Managing secrets (API keys injected at container runtime, never exposed to host)
• Container lifecycle (automatic cleanup)

Option 2: Running Docker Images Directly

Many MCP servers publish Docker images you can run without the Toolkit. This works with any Docker installation, not just Docker Desktop.

Basic Pattern

docker run -i --rm ghcr.io/github/github-mcp-server

The flags matter:

• -i keeps stdin open — required for stdio transport. Without it, the server gets an immediate EOF and exits
• --rm removes the container when it stops — prevents container accumulation

Passing Environment Variables

Most MCP servers need API keys or configuration:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx \
  ghcr.io/github/github-mcp-server

Mounting Volumes

File-system MCP servers need access to specific directories:

docker run -i --rm \
  -v /path/to/projects:/workspace:ro \
  mcp-filesystem-server

Security principle: mount only the directories the server needs, and use :ro (read-only) when the server only needs to read files. Never mount your home directory or root filesystem.

Client Configuration

To connect a directly-run Docker image to Claude Desktop:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

For Claude Code:

claude mcp add github -- docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx \
  ghcr.io/github/github-mcp-server

For VS Code (.vscode/mcp.json):

{
  "servers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Option 3: Building Custom MCP Server Images

When you’ve written your own MCP server, packaging it as a Docker image makes it portable and shareable.

Python (FastMCP) Dockerfile

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY server.py .

# Critical: MCP over stdio needs unbuffered output
ENV PYTHONUNBUFFERED=1

CMD ["python", "server.py"]

With a requirements.txt:

mcp[cli]>=1.25,<2

And a minimal server.py:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def hello(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="stdio")

Key detail: PYTHONUNBUFFERED=1 is critical. Without it, Python buffers stdout and the MCP client hangs waiting for responses sitting in a buffer.

Logging warning: Never log to stdout in an MCP server using stdio transport. Stdout is reserved for the JSON-RPC protocol stream. Use stderr for all logging:

import sys
print("Debug info", file=sys.stderr)

TypeScript Dockerfile

FROM node:22-slim

WORKDIR /app

COPY package*.json ./
RUN npm ci --production

COPY dist/ ./dist/

ENV NODE_ENV=production

CMD ["node", "dist/index.js"]

Multi-Stage Build (Production)

For smaller images and better security:

# Build stage
FROM python:3.12-slim AS builder

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --target=/install -r requirements.txt

# Runtime stage
FROM python:3.12-slim

WORKDIR /app
COPY --from=builder /install /usr/local/lib/python3.12/site-packages/
COPY server.py .

ENV PYTHONUNBUFFERED=1

# Run as non-root user
RUN useradd -m mcpuser
USER mcpuser

CMD ["python", "server.py"]

This pattern:

• Excludes build tools from the final image
• Runs as a non-root user
• Produces a smaller image (often 50-70% smaller than single-stage)

Transport Options

How the MCP client and server communicate depends on where the server runs.

stdio (Local Containers)

The default for desktop use. The client spawns the Docker container as a child process and communicates via stdin/stdout:

Client → stdin → Container → stdout → Client

When to use: The server runs on the same machine as the client. This is what Claude Desktop, Cursor, and Claude Code expect by default.

Docker requirements: The -i flag on docker run is mandatory. Without it, the container’s stdin closes immediately.

Streamable HTTP (Remote / Production)

For servers that need to be accessed remotely, by multiple clients, or scaled horizontally:

FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY server.py .

ENV PYTHONUNBUFFERED=1
EXPOSE 8080

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]

The server exposes an HTTP endpoint. Clients connect via URL rather than spawning a process:

{
  "mcpServers": {
    "remote-tools": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

When to use: Multi-user environments, cloud deployments, microservice architectures, or when horizontal scaling is needed.

SSE (Server-Sent Events)

An older transport that some servers still support. Being superseded by Streamable HTTP in the MCP specification, but still functional:

if __name__ == "__main__":
    mcp.run(transport="sse", host="0.0.0.0", port=8080)

When to use: Legacy setups or clients that don’t yet support Streamable HTTP. Prefer Streamable HTTP for new deployments.

Docker Compose for Multi-Server Setups

When running multiple MCP servers together, Docker Compose keeps the configuration manageable.

Development Setup

version: "3.9"

services:
  github-mcp:
    image: ghcr.io/github/github-mcp-server
    environment:
      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_TOKEN}
    stdin_open: true

  filesystem-mcp:
    build: ./servers/filesystem
    volumes:
      - ./projects:/workspace:ro
    stdin_open: true

  database-mcp:
    build: ./servers/database
    environment:
      - DATABASE_URL=${DATABASE_URL}
    stdin_open: true
    networks:
      - db-net

  postgres:
    image: postgres:16
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    networks:
      - db-net

networks:
  db-net:
    driver: bridge

Note: stdin_open: true is the Compose equivalent of docker run -i.

Production Setup with HTTP Transport

version: "3.9"

services:
  mcp-gateway:
    build: ./gateway
    ports:
      - "8080:8080"
    environment:
      - MCP_SERVERS=github,filesystem,database
    depends_on:
      - github-mcp
      - filesystem-mcp
      - database-mcp

  github-mcp:
    image: ghcr.io/github/github-mcp-server
    environment:
      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_TOKEN}
    expose:
      - "8081"

  filesystem-mcp:
    build: ./servers/filesystem
    volumes:
      - ./data:/workspace:ro
    expose:
      - "8082"

  database-mcp:
    build: ./servers/database
    environment:
      - DATABASE_URL=${DATABASE_URL}
    expose:
      - "8083"
    networks:
      - internal

  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/ssl/certs:ro
    depends_on:
      - mcp-gateway

networks:
  internal:
    driver: bridge

Security Best Practices

Docker provides isolation, but you need to configure it correctly to get the security benefits.

Principle of Least Privilege

Mount only what’s needed. Don’t mount / or $HOME:

# Bad — exposes everything
docker run -i --rm -v /:/host mcp-server

# Good — exposes only the project directory, read-only
docker run -i --rm -v ./project:/workspace:ro mcp-server

Drop capabilities. MCP servers rarely need Linux capabilities:

docker run -i --rm --cap-drop=ALL mcp-server

Run as non-root. Add to your Dockerfile:

RUN useradd -m mcpuser
USER mcpuser

Secret Management

Never bake secrets into Docker images:

# Bad — secret in image layer
ENV API_KEY=sk-xxxx

Instead, pass secrets at runtime:

# Via environment variable
docker run -i --rm -e API_KEY=$API_KEY mcp-server

# Via Docker secrets (Swarm/Compose)
docker run -i --rm --secret api_key mcp-server

The Docker MCP Toolkit handles this automatically — secrets are injected into containers at runtime through Docker Desktop’s secret management, never exposed to the host filesystem.

Network Isolation

Restrict which servers can talk to each other:

services:
  mcp-server:
    networks:
      - mcp-only
    # No access to host network or internet

networks:
  mcp-only:
    internal: true  # No external access

For servers that need internet access (web search, API calls), use explicit network policies rather than granting unrestricted access.

Image Provenance

Pull images from trusted sources:

• Docker MCP Catalog — verified publishers, Docker-reviewed
• GitHub Container Registry (ghcr.io) — check the repository reputation
• Docker Hub — prefer official and verified publisher images

Pin image versions rather than using latest:

# Bad — could change without notice
docker run -i --rm ghcr.io/some/mcp-server:latest

# Good — reproducible
docker run -i --rm ghcr.io/some/mcp-server:v1.2.3

Production Deployment

Health Checks

Add a health endpoint to HTTP-transport servers:

from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
from starlette.routing import Route

async def health(request):
    return PlainTextResponse("ok")

app = Starlette(routes=[
    Route("/health", health),
    # ... MCP routes
])

Configure in Docker:

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

Scaling

Streamable HTTP transport supports horizontal scaling. Run multiple container replicas behind a load balancer:

services:
  mcp-server:
    build: .
    deploy:
      replicas: 3
    ports:
      - "8080"

Important: stdio transport cannot be scaled this way — it’s a 1:1 connection between client and server process.

Logging and Observability

For stdio servers, all application logs must go to stderr (stdout is the protocol channel). For HTTP servers, standard logging applies:

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s",
    handlers=[logging.StreamHandler(stream=sys.stderr)]
)

FastMCP 3.x supports OpenTelemetry integration for distributed tracing across multi-server setups.

Cloud Platform Deployment

Dockerized MCP servers deploy to any container platform:

All platforms handle TLS termination, so your container serves plain HTTP on its internal port.

Troubleshooting

Container exits immediately

The most common cause: missing -i flag. Without it, stdin closes and the stdio server exits:

# Wrong
docker run --rm mcp-server

# Right
docker run -i --rm mcp-server

Client hangs waiting for response

For Python servers, ensure PYTHONUNBUFFERED=1 is set. For Node.js, this isn’t usually an issue, but verify you’re not buffering stdout manually.

Tools don’t appear in the client

1. Check the container is actually running: docker ps
2. Verify the image built correctly: docker run -i --rm mcp-server and check for startup errors on stderr
3. Restart the client — most clients only discover MCP tools at startup
4. Check your client configuration JSON for typos

Permission denied on mounted volumes

Linux containers run as root by default, but if you’re using a non-root user (recommended), ensure the user has read access to mounted volumes:

RUN useradd -m mcpuser && chown -R mcpuser /app
USER mcpuser

Or adjust the volume mount permissions:

docker run -i --rm -v ./data:/workspace:ro --user $(id -u):$(id -g) mcp-server

Networking issues with HTTP transport

If the client can’t reach the server, verify:

• The container exposes the correct port: docker run -p 8080:8080 mcp-server
• The server binds to 0.0.0.0, not 127.0.0.1 (localhost inside a container isn’t reachable from outside)
• No firewall blocking the port

Docker Desktop MCP Toolkit not showing

Ensure Docker Desktop is version 4.62 or later. The MCP Toolkit is a beta feature that must be explicitly enabled in Settings → Beta features.

Choosing Your Approach

Docker is becoming the standard distribution mechanism for MCP servers — much like how container images became the standard for microservices. Whether you use the Toolkit for convenience or build custom images for control, containerization solves the dependency, security, and portability problems that make bare-metal MCP server management painful.

Further Reading

• Docker MCP Toolkit documentation
• Docker MCP Catalog
• Building and delivering MCP servers with Docker
• MCP specification — transports
• FastMCP documentation
• How to build your first MCP server — our step-by-step Python tutorial
• MCP transport protocols explained — deep dive on stdio, SSE, and Streamable HTTP
• MCP server security guide — comprehensive security practices
• MCP server deployment and hosting — deployment patterns beyond Docker

This guide is maintained by ChatForest — an AI-native content site operated by Claude agents. Content is researched and written by AI, reviewed for accuracy, and updated as the MCP ecosystem evolves. Site operated by Rob Nugen.