# How to Deploy Containerized MCP Servers

Containerized MCP servers package tools for scalable, portable AI agent integrations. This guide walks through Docker deployment, Kubernetes orchestration, and scaling for multi-agent systems. According to the CNCF Annual Survey 2023, 92% of organizations use containers in production or evaluation, making Docker and Kubernetes the standard for MCP servers.

Source: https://fast.io/resources/containerized-mcp-servers/
Last reviewed: 2026-02-19

## What Are Containerized MCP Servers?

MCP (Model Context Protocol) servers let AI agents connect to external data sources and tools through a standard interface. Containerizing them with Docker packages the server, dependencies, and config into a portable unit.

This approach solves common issues like environment mismatches and manual setup. Containers run consistently from laptop to production cluster. Kubernetes then orchestrates multiple instances for high availability and scaling.

For AI agents, containerized MCP servers handle concurrent tool calls from multiple LLMs without downtime. Fastio provides a hosted MCP server at mcp.fast.io with multiple tools, but self-hosting gives custom control.

Helpful references: [Fastio Workspaces](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/).

## Prerequisites for Deployment

Before starting, install these tools:

1. Docker Desktop or Docker Engine
2. kubectl and Helm (for Kubernetes)
3. A Kubernetes cluster (Minikube for local, EKS/GKE/AKS for prod)
4. Your MCP server code (Node.js, Python, Go examples available)

Basic MCP server knowledge from modelcontextprotocol.io. Test locally first.

Ensure ports multiple (HTTP) and multiple (TLS) are open. Use secrets for API keys and DB creds.

## Step 1: Create a Dockerfile for Your MCP Server

Start with a minimal Dockerfile. Here's a Node.js example for a basic MCP server:

```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./
EXPOSE 8080
CMD ["npm", "start"]
```

Build and test:

```
docker build -t mcp-server .
docker run -p 8080:8080 mcp-server
```

Verify with curl /health or MCP client.

## Step 2: Local Testing with Docker Compose

Use Docker Compose for multi-container setups (MCP + DB + Redis):

```yaml
version: '3.8'
services:
  mcp:
    image: mcp-server
    ports:
      - "8080:8080"
    environment:
      - DB_URL=postgres://user:pass@db:5432/mcp
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: mcp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
```

Run `docker compose up`. Access at localhost:multiple.

## Docker vs Kubernetes for MCP Deployment

Choose based on scale:

| Feature | Docker | Kubernetes |
|---------|--------|------------|
| Setup | Simple, local | Complex, cluster |
| Scaling | Manual | Auto-scaling |
| Orchestration | Basic | Full HPA, rolling updates |
| Best for | Dev/test | Production agents |

Docker suits prototyping. Kubernetes for prod MCP serving 100s of agents.

## Step 3: Kubernetes Deployment and Scaling

Create Deployment and Service:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp
  template:
    metadata:
      labels:
        app: mcp
    spec:
      containers:
      - name: mcp
        image: your-repo/mcp-server:latest
        ports:
        - containerPort: 8080
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-service
spec:
  selector:
    app: mcp
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer
```

Apply: `kubectl apply -f mcp-k8s.yaml`

Scale: `kubectl scale deployment mcp-server --replicas=5`

Use Horizontal Pod Autoscaler for agent load.

## Scaling MCP for Agent Workspaces with Fastio

For production, self-hosted MCP pairs with Fastio workspaces. Store agent artifacts in Fastio workspaces, use your MCP for custom tools.

Example: K8s MCP cluster reads/writes to Fastio via API. Scale MCP pods based on agent requests, use Fastio RAG for file queries.

The remote Fastio MCP server at https://mcp.fast.io/mcp offers a consolidated toolset, no infra needed. Hybrid: self-host custom, use hosted for storage.

Troubleshoot: Monitor logs with Prometheus, secure with Istio, persist state in PVCs.

Define clear tool contracts and fallback behavior so agents fail safely when dependencies are unavailable. This improves reliability in production workflows.

## Frequently asked questions

### How to containerize MCP servers?

Create a Dockerfile copying your MCP code, install deps, expose your server's port. Build, run with docker run -p <host-port>:<container-port> image. Use multi-stage for smaller images.

### Docker vs Kubernetes for MCP?

Docker for simple/local deploys. Kubernetes for prod scaling, rolling updates, HPA. Start Docker, migrate to K8s as agents grow.

### What ports does MCP server use?

Typically multiple for HTTP, multiple for TLS. Configure via env vars. Expose Streamable HTTP /mcp and SSE /sse endpoints.

### How to scale MCP servers?

Use K8s HPA on CPU/memory. Add Redis for sessions, Postgres for state. Monitor with Prometheus/Grafana.

### Integrate self-hosted MCP with Fastio?

Use Fastio API/MCP for storage/RAG. Self-host custom tools, point agents to both endpoints.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.