MCP Proxy Commands

Manage Model Context Protocol (MCP) servers and proxy operations with the `compozy mcp-proxy` binary. The MCP proxy server enables HTTP-based access to MCP servers, providing seamless integration between AI agents and external tools.

Overview

compozy mcp-proxy [flags]

HTTP Proxy Server

Provides HTTP endpoints for MCP server communication with authentication and security controls

Admin API

Comprehensive server management interface with authentication and monitoring capabilities

Security & Authentication

Global auth tokens, admin access controls, and IP-based restrictions for secure operations

Production Ready

Built-in health checks, monitoring, logging, and deployment configurations for production use

mcp-proxy

Start the MCP proxy server to provide HTTP access to MCP servers.

Usage

compozy mcp-proxy [flags]

Description

The MCP proxy server enables HTTP-based access to MCP servers, providing:

  • HTTP endpoints for MCP server communication
  • Admin API for server management
  • Authentication and security controls
  • Request logging and monitoring

Flags

MCP Proxy Configuration

FlagDescriptionDefault
--mcp-hostHost interface for MCP proxy server to bind to127.0.0.1
--mcp-portPort for MCP proxy server to listen on6001
--mcp-base-urlBase URL for MCP proxy server (auto-generated if empty)-

Security and Authentication

FlagDescriptionType
--mcp-global-auth-tokensGlobal authentication tokens for all MCP clientsstrings (comma-separated)
--mcp-admin-tokensAdmin authentication tokens for MCP proxystrings (comma-separated)
--mcp-admin-allow-ipsIP addresses/CIDR blocks allowed for admin access. If empty, allows all IPsstrings (comma-separated)
--mcp-trusted-proxiesTrusted proxy IP addresses/CIDR blocksstrings (comma-separated)

Debugging

FlagDescriptionDefault
--debugEnable 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
MCP_PROXY_ADMIN_TOKENS          # Admin API authentication tokens (comma-separated)
MCP_PROXY_ADMIN_ALLOW_IPS       # Admin API allowed IP addresses (comma-separated)
MCP_PROXY_TRUSTED_PROXIES       # Trusted proxy IP addresses (comma-separated)
MCP_PROXY_GLOBAL_AUTH_TOKENS    # Global authentication tokens (comma-separated)

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

With Authentication

compozy mcp-proxy \
  --mcp-global-auth-tokens "token1,token2" \
  --mcp-admin-tokens "admin-secret" \
  --mcp-admin-allow-ips "192.168.1.0/24,10.0.0.0/8"

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

Mixed Configuration (Flags + Environment Variables)

export MCP_PROXY_GLOBAL_AUTH_TOKENS="token1,token2"
export MCP_PROXY_ADMIN_TOKENS="admin-secret"

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

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:

  1. Command-line flags (highest priority)
  2. Environment variables
  3. Configuration file (specified with --config)

Configuration File Example

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

  auth:
    global_tokens:
      - "your-auth-token"
    admin_tokens:
      - "admin-secret"
    admin_allow_ips:
      - "192.168.1.0/24"
      - "127.0.0.1"

  security:
    trusted_proxies:
      - "10.0.0.0/8"
      - "172.16.0.0/12"
      - "192.168.0.0/16"

  logging:
    level: "info"
    format: "json"

Security Considerations

Authentication Tokens

  • Global auth tokens: Required for all MCP client requests
  • Admin tokens: Required for admin API access
  • Use strong, randomly generated tokens
  • Rotate tokens regularly

IP Restrictions

  • Admin IP allowlist: Restrict admin API access by IP
  • Trusted proxies: Configure known proxy IPs for proper client IP detection
  • Use CIDR notation for IP ranges

Network Security

  • Run behind a reverse proxy in production
  • Use HTTPS termination at the proxy level
  • Implement rate limiting and request size limits

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"

Next Steps

Explore these related topics to get the most out of MCP proxy operations:

Learn the Fundamentals

Production & Operations