MCP ACS Process Server - Docker Guide

December 12, 2025 ยท View on GitHub

This guide explains how to run the MCP ACS Process Server using Docker.

Quick Start

1. Pull the Image

docker pull digitaldefiance/mcp-process:latest

2. Create Configuration Directory

mkdir -p config

3. Create Configuration File

Create config/mcp-process-config.json:

{
  "allowedExecutables": ["node", "python3", "npm", "git"],
  "blockSetuidExecutables": true,
  "blockShellInterpreters": true,
  "defaultResourceLimits": {
    "maxCpuPercent": 80,
    "maxMemoryMB": 512,
    "maxCpuTime": 300
  },
  "maxConcurrentProcesses": 5,
  "maxProcessLifetime": 1800,
  "enableAuditLog": true
}

4. Run with Docker Compose

docker-compose up -d

Or run directly with Docker:

docker run -d \
  --name mcp-process \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  --cap-add CHOWN \
  --cap-add SETUID \
  --cap-add SETGID \
  --memory 2g \
  --cpus 2.0 \
  -v $(pwd)/config:/app/config:ro \
  -i \
  digitaldefiance/mcp-process:latest

Configuration

Using docker-compose.yml

The provided docker-compose.yml includes secure defaults:

  • Security: Runs as non-root user (UID 1001)
  • Capabilities: Minimal Linux capabilities
  • Resources: CPU and memory limits
  • Network: Disabled (stdio transport only)
  • Volumes: Configuration mounted read-only

Environment Variables

  • NODE_ENV: Set to production (default)
  • MCP_PROCESS_CONFIG_PATH: Path to configuration file (default: /app/config/mcp-process-config.json)

Volumes

Mount your configuration directory:

volumes:
  - ./config:/app/config:ro

Optionally mount a workspace directory for process execution:

volumes:
  - ./config:/app/config:ro
  - ./workspace:/workspace:rw

Security Considerations

Container Security

The Docker image implements multiple security layers:

  1. Non-root User: Runs as UID 1001 (user mcp)
  2. Minimal Base: Uses Alpine Linux for small attack surface
  3. No New Privileges: Prevents privilege escalation
  4. Capability Dropping: Removes all capabilities except essential ones
  5. Read-only Filesystem: Configuration mounted read-only
  6. Resource Limits: CPU and memory constraints

Application Security

The MCP ACS Process Server enforces:

  1. Executable Allowlist: Only approved executables can run
  2. Shell Blocking: Shell interpreters blocked by default
  3. Setuid Blocking: No setuid/setgid executables
  4. Resource Limits: Per-process CPU and memory limits
  5. Audit Logging: All operations logged

For production use, we recommend:

{
  "allowedExecutables": ["node", "python3", "npm"],
  "blockSetuidExecutables": true,
  "blockShellInterpreters": true,
  "defaultResourceLimits": {
    "maxCpuPercent": 50,
    "maxMemoryMB": 256,
    "maxCpuTime": 180
  },
  "maxConcurrentProcesses": 3,
  "maxProcessLifetime": 900,
  "enableAuditLog": true,
  "requireConfirmation": false
}

Building the Image

Build Locally

docker build -t mcp-process:local .

Build with Docker Compose

docker-compose build

Multi-platform Build

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t digitaldefiance/mcp-process:latest \
  --push \
  .

Usage Examples

Example 1: Basic Usage

# Start the server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

Example 2: Custom Configuration

# Create custom config
cat > config/custom-config.json << EOF
{
  "allowedExecutables": ["node", "npm", "jest"],
  "maxConcurrentProcesses": 10,
  "enableAuditLog": true
}
EOF

# Run with custom config
docker run -d \
  -v $(pwd)/config:/app/config:ro \
  -e MCP_PROCESS_CONFIG_PATH=/app/config/custom-config.json \
  -i \
  digitaldefiance/mcp-process:latest

Example 3: Development Mode

# Copy override example
cp docker-compose.override.yml.example docker-compose.override.yml

# Edit override for your needs
vim docker-compose.override.yml

# Start with override
docker-compose up -d

Example 4: Connecting from AI Agent

Configure your AI agent (e.g., Kiro, Claude Desktop) to connect via Docker:

{
  "mcpServers": {
    "process": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${workspaceFolder}/config:/app/config:ro",
        "digitaldefiance/mcp-process:latest"
      ]
    }
  }
}

Troubleshooting

Issue: Container exits immediately

Cause: No stdin connection or configuration error.

Solution: Ensure you're running with -i flag and have valid configuration.

Issue: Permission denied errors

Cause: Volume mount permissions.

Solution: Ensure config directory is readable:

chmod -R 755 config

Issue: Cannot execute processes

Cause: Executables not in allowlist or not available in container.

Solution:

  1. Add executables to allowlist in config
  2. Install required tools in custom Dockerfile:
FROM digitaldefiance/mcp-process:latest

USER root
RUN apk add --no-cache python3 git
USER mcp

Issue: Resource limits too restrictive

Cause: Docker resource limits or application limits too low.

Solution: Adjust in docker-compose.yml:

deploy:
  resources:
    limits:
      cpus: "4.0"
      memory: 4G

And in configuration:

{
  "defaultResourceLimits": {
    "maxCpuPercent": 90,
    "maxMemoryMB": 1024
  }
}

Health Checks

The container includes a health check that runs every 30 seconds:

# Check container health
docker inspect --format='{{.State.Health.Status}}' mcp-process

# View health check logs
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' mcp-process

Logs and Monitoring

View Logs

# Docker Compose
docker-compose logs -f

# Docker
docker logs -f mcp-process

Audit Logs

Audit logs are written to stdout and captured by Docker:

# Filter for security violations
docker logs mcp-process 2>&1 | grep SECURITY_VIOLATION

# Filter for audit events
docker logs mcp-process 2>&1 | grep AUDIT

Resource Monitoring

# Monitor container resources
docker stats mcp-process

# Detailed inspection
docker inspect mcp-process

Advanced Configuration

Custom Dockerfile

Create a custom image with additional tools:

FROM digitaldefiance/mcp-process:latest

USER root

# Install additional tools
RUN apk add --no-cache \
    python3 \
    py3-pip \
    git \
    curl \
    && rm -rf /var/cache/apk/*

# Install Python packages
RUN pip3 install --no-cache-dir pytest black flake8

USER mcp

Build and use:

docker build -t mcp-process:custom -f Dockerfile.custom .
docker run -d -i -v $(pwd)/config:/app/config:ro mcp-process:custom

Kubernetes Deployment

Example Kubernetes deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-process
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mcp-process
  template:
    metadata:
      labels:
        app: mcp-process
    spec:
      securityContext:
        runAsUser: 1001
        runAsGroup: 1001
        fsGroup: 1001
      containers:
        - name: mcp-process
          image: digitaldefiance/mcp-process:latest
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop:
                - ALL
              add:
                - CHOWN
                - SETUID
                - SETGID
            readOnlyRootFilesystem: false
          resources:
            limits:
              cpu: "2"
              memory: "2Gi"
            requests:
              cpu: "500m"
              memory: "512Mi"
          volumeMounts:
            - name: config
              mountPath: /app/config
              readOnly: true
      volumes:
        - name: config
          configMap:
            name: mcp-process-config

Support

For issues and questions: