MCP Proxy Commands

Flag	Description	Default
`--mcp-host`	Host interface for MCP proxy server to bind to	127.0.0.1
`--mcp-port`	Port for MCP proxy server to listen on	6001
`--mcp-base-url`	Base URL for MCP proxy server (auto-generated if empty)	-

Debugging

Flag	Description	Default
`--debug`	Enable debug mode (sets log level to debug)	false

Environment Variables

The MCP proxy can be configured through command-line flags (shown above) or environment variables. Command-line flags take precedence over environment variables.

The MCP proxy respects these environment variables:

MCP_PROXY_HOST                  # Host to bind the server to
MCP_PROXY_PORT                  # Port to run the MCP proxy server on
MCP_PROXY_BASE_URL              # Base URL for the MCP proxy server
MCP_PROXY_SHUTDOWN_TIMEOUT      # Graceful shutdown timeout

Examples

Basic Usage

Start the MCP proxy with default settings:

compozy mcp-proxy

This starts the proxy on 0.0.0.0:6001.

Custom Port and Host

compozy mcp-proxy --mcp-host localhost --mcp-port 9000

Debug Mode

compozy mcp-proxy --debug

Using Environment Variables

export MCP_PROXY_HOST=localhost
export MCP_PROXY_PORT=9000
export MCP_PROXY_BASE_URL=http://localhost:9000

compozy mcp-proxy

API Endpoints

Once started, the MCP proxy provides these endpoints:

Health monitoring and status endpoints:

GET /healthz             # Health check endpoint

Example response:

{
  "status": "ok"
}

Configuration

The MCP proxy can be configured through:

Command-line flags (highest priority)
Environment variables
Configuration file (specified with --config)

Configuration File Example

# compozy.yaml
mcp_proxy:
  host: "0.0.0.0"
  port: 6001
  base_url: "http://localhost:6001"

Security Considerations

Use a reverse proxy or firewall to restrict access to /admin endpoints.
Terminate TLS at your ingress/proxy.
Apply rate limits and request size limits at your edge.

Monitoring and Logging

Health Monitoring

# Check health status
curl http://localhost:6001/healthz

Log Analysis

# Follow proxy logs (JSON format)
tail -f /var/log/compozy/mcp-proxy.log | jq '.'

# Filter for errors
grep '"level":"error"' /var/log/compozy/mcp-proxy.log | jq '.'

# Monitor request patterns
grep '"path":' /var/log/compozy/mcp-proxy.log | \
  jq -r '.path' | sort | uniq -c | sort -nr

Production Deployment

Docker

FROM ghcr.io/compozy/mcp-proxy:latest
EXPOSE 6001
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:6001/healthz || exit 1
CMD ["compozy", "mcp-proxy"]

Docker Compose

version: '3.8'
services:
  mcp-proxy:
    image: ghcr.io/compozy/mcp-proxy:latest
    command: ["compozy", "mcp-proxy"]
    ports:
      - "6001:6001"
    environment:
      - MCP_PROXY_HOST=0.0.0.0
      - MCP_PROXY_PORT=6001
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:6001/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-proxy
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mcp-proxy
  template:
    metadata:
      labels:
        app: mcp-proxy
    spec:
      containers:
      - name: mcp-proxy
        image: ghcr.io/compozy/mcp-proxy:latest
        command: ["compozy", "mcp-proxy"]
        ports:
        - containerPort: 6001
        env:
        - name: MCP_PROXY_HOST
          value: "0.0.0.0"
        - name: MCP_PROXY_PORT
          value: "6001"
        livenessProbe:
          httpGet:
            path: /healthz
            port: 6001
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /healthz
            port: 6001
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          requests:
            memory: "64Mi"
            cpu: "50m"
          limits:
            memory: "256Mi"
            cpu: "200m"