MCP + Docker Deploy — Đóng gói và triển khai MCP Server

Model Context Protocol (MCP) đã mở ra khả năng kết nối Claude với các hệ thống bên ngoài một cách chuẩn hóa. Tuy nhiên, việc phát triển MCP Server trên máy local là một chuyện — triển khai nó lên production để phục vụ nhiều người dùng là chuyện hoàn toàn khác. Bài viết này hướng dẫn bạn cách đóng gói MCP Server bằng Docker và triển khai một cách an toàn, ổn định.

Tại sao cần Docker cho MCP Server?

Khi phát triển MCP Server trên máy local, bạn có thể chạy trực tiếp bằng Node.js hoặc Python. Nhưng khi triển khai production, Docker giải quyết nhiều vấn đề:

• Tính nhất quán: Đảm bảo MCP Server chạy giống nhau trên mọi môi trường (dev, staging, production)
• Cô lập: Mỗi MCP Server chạy trong container riêng, không ảnh hưởng đến các service khác
• Dễ scale: Có thể chạy nhiều instance khi tải tăng
• Quản lý dependency: Tất cả dependencies được đóng gói cùng, không lo xung đột phiên bản
• Rollback nhanh: Quay về phiên bản trước chỉ trong vài giây

Cấu trúc dự án MCP Server

Trước khi Docker hóa, hãy đảm bảo project MCP Server của bạn có cấu trúc rõ ràng. Dưới đây là cấu trúc khuyến nghị cho một MCP Server viết bằng TypeScript:

my-mcp-server/
  src/
    index.ts          # Entry point
    tools/            # Định nghĩa các MCP tools
      search.ts
      analyze.ts
    resources/        # Định nghĩa các MCP resources
      documents.ts
    prompts/          # Định nghĩa các MCP prompts
      templates.ts
    utils/            # Utility functions
      database.ts
      auth.ts
  tests/
    tools.test.ts
    resources.test.ts
  Dockerfile
  docker-compose.yml
  .dockerignore
  .env.example
  package.json
  tsconfig.json

Viết Dockerfile cho MCP Server

Dockerfile là bản thiết kế để Docker xây dựng container image. Dưới đây là Dockerfile tối ưu cho MCP Server TypeScript:

# Stage 1: Build
FROM node:20-alpine AS builder
WORKDIR /app

# Copy package files trước để tận dụng Docker layer caching
COPY package.json package-lock.json ./
RUN npm ci --production=false

# Copy source code và build
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

# Stage 2: Production
FROM node:20-alpine AS production
WORKDIR /app

# Tạo non-root user cho bảo mật
RUN addgroup -g 1001 -S mcpuser &&     adduser -S mcpuser -u 1001 -G mcpuser

# Copy chỉ những gì cần thiết từ build stage
COPY --from=builder /app/package.json /app/package-lock.json ./
RUN npm ci --production && npm cache clean --force
COPY --from=builder /app/dist/ ./dist/

# Chuyển sang non-root user
USER mcpuser

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3   CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"

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

Giải thích các điểm quan trọng:

• Multi-stage build: Giảm kích thước image cuối cùng bằng cách chỉ copy artifacts từ build stage
• Layer caching: Copy package.json trước, cài dependencies, sau đó mới copy source code — giúp Docker cache layer dependencies khi chỉ code thay đổi
• Non-root user: Chạy ứng dụng bằng user không có quyền root, tăng bảo mật
• Health check: Cho phép Docker và orchestrator biết container có đang hoạt động bình thường không

Cấu hình Docker Compose

Docker Compose giúp quản lý multi-container setup, đặc biệt khi MCP Server cần kết nối đến database hoặc các service khác:

# docker-compose.yml
version: '3.8'

services:
  mcp-server:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://user:pass@postgres:5432/mcpdb
      - REDIS_URL=redis://redis:6379
      - LOG_LEVEL=info
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'

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

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

Quản lý biến môi trường

Biến môi trường là cách chuẩn để cấu hình MCP Server trong Docker. Các nguyên tắc quan trọng:

• Không bao giờ hardcode secrets trong Dockerfile hoặc source code
• Sử dụng file .env cho local development, Docker secrets hoặc vault cho production
• Tạo file .env.example với tất cả biến cần thiết nhưng không có giá trị thật
• Validate tất cả biến môi trường khi server khởi động

# .env.example — Template cho team
NODE_ENV=production
PORT=3000

# Database
DATABASE_URL=postgresql://user:password@host:5432/dbname

# Redis (caching)
REDIS_URL=redis://host:6379

# API Keys
ANTHROPIC_API_KEY=sk-ant-...
EXTERNAL_API_KEY=

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

# Security
CORS_ORIGINS=https://yourdomain.com
RATE_LIMIT_RPM=60

Thiết lập health check và monitoring

Trong production, bạn cần biết MCP Server có đang hoạt động bình thường không. Thiết lập health check endpoint:

// src/health.ts — Health check endpoint cho MCP Server
import http from 'http';

interface HealthStatus {
  status: 'healthy' | 'degraded' | 'unhealthy';
  uptime: number;
  checks: {
    database: boolean;
    redis: boolean;
    memory: {
      used: number;
      total: number;
      percentage: number;
    };
  };
}

export function startHealthServer(port: number = 3000) {
  const server = http.createServer(async (req, res) => {
    if (req.url === '/health') {
      const health: HealthStatus = {
        status: 'healthy',
        uptime: process.uptime(),
        checks: {
          database: await checkDatabase(),
          redis: await checkRedis(),
          memory: getMemoryUsage()
        }
      };

      // Degraded nếu một service phụ không hoạt động
      if (!health.checks.redis) health.status = 'degraded';
      // Unhealthy nếu database không hoạt động
      if (!health.checks.database) health.status = 'unhealthy';

      const statusCode = health.status === 'unhealthy' ? 503 : 200;
      res.writeHead(statusCode, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify(health));
    }
  });
  server.listen(port);
}

Triển khai lên VPS hoặc Cloud

Triển khai trên VPS (Ubuntu)

Quy trình triển khai MCP Server lên VPS chạy Ubuntu:

# 1. SSH vào server
ssh user@your-server-ip

# 2. Cài Docker và Docker Compose (nếu chưa có)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 3. Clone repository
git clone https://github.com/your-org/mcp-server.git
cd mcp-server

# 4. Tạo file .env từ template
cp .env.example .env
# Chỉnh sửa .env với giá trị production

# 5. Build và chạy
docker compose up -d --build

# 6. Kiểm tra logs
docker compose logs -f mcp-server

# 7. Kiểm tra health
curl http://localhost:3000/health

Triển khai trên Cloud (DigitalOcean / AWS)

Đối với cloud deployment, bạn có thể sử dụng container registry để lưu trữ Docker image và deploy từ đó:

# Build và push image
docker build -t registry.digitalocean.com/myorg/mcp-server:v1.0 .
docker push registry.digitalocean.com/myorg/mcp-server:v1.0

# Deploy trên cloud (ví dụ DigitalOcean App Platform)
doctl apps create --spec app-spec.yml

Cấu hình Reverse Proxy với Nginx

Trong production, MCP Server nên nằm sau reverse proxy để có SSL, load balancing và bảo mật:

# nginx.conf cho MCP Server
server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeout cho long-running MCP operations
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }

    # Rate limiting
    limit_req zone=mcp_limit burst=20 nodelay;
}

CI/CD Pipeline cho MCP Server

Tự động hóa quy trình build, test và deploy bằng GitHub Actions:

# .github/workflows/deploy.yml
name: Deploy MCP Server
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

  build-and-deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build Docker image
        run: docker build -t mcp-server:${{ github.sha }} .
      - name: Deploy to server
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd /opt/mcp-server
            git pull origin main
            docker compose up -d --build
            docker compose logs --tail=50 mcp-server

Bảo mật MCP Server trong production

Bảo mật là yếu tố quan trọng nhất khi triển khai MCP Server. Các lớp bảo mật cần thiết:

Authentication và Authorization

Mỗi request đến MCP Server cần được xác thực. Sử dụng API key hoặc JWT token để kiểm soát truy cập. Đảm bảo mỗi client có API key riêng và thiết lập rate limiting phù hợp.

Network Security

• Chỉ expose port cần thiết (thường chỉ 443 qua Nginx)
• Sử dụng firewall (ufw trên Ubuntu) để chặn truy cập không cần thiết
• Đặt MCP Server trong private network nếu chỉ internal access
• Luôn sử dụng HTTPS/TLS cho mọi kết nối

Container Security

• Sử dụng minimal base image (Alpine Linux)
• Chạy container với non-root user
• Scan image cho vulnerabilities trước khi deploy
• Cập nhật base image định kỳ

Monitoring và Logging

Sau khi deploy, bạn cần theo dõi MCP Server liên tục:

• Structured logging: Log ở dạng JSON để dễ parse và tìm kiếm. Bao gồm request ID, timestamp, tool name, execution time, và error details.
• Metrics: Theo dõi số lượng requests, response time trung bình, error rate, memory usage và CPU usage.
• Alerting: Thiết lập cảnh báo khi error rate vượt ngưỡng, response time quá chậm, hoặc container restart bất thường.

Xử lý sự cố thường gặp

Một số vấn đề phổ biến khi triển khai MCP Server bằng Docker và cách xử lý:

• Container liên tục restart: Kiểm tra logs bằng docker compose logs, thường do thiếu biến môi trường hoặc lỗi kết nối database
• Out of memory: Tăng memory limit trong docker-compose.yml hoặc tối ưu code để giảm memory usage
• Connection refused: Kiểm tra network configuration, đảm bảo các service có thể giao tiếp trong cùng Docker network
• Slow response: Kiểm tra database queries, thêm caching layer (Redis), hoặc tối ưu tool implementation

Bước tiếp theo

Bạn đã nắm được cách đóng gói và triển khai MCP Server bằng Docker. Bước tiếp theo là khám phá hệ sinh thái MCP Server có sẵn để tìm và tích hợp những server phù hợp với nhu cầu của bạn. Tham khảo thêm tại Thư viện Ứng dụng.