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
Admin API
Security & Authentication
Production Ready
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
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) | - |
Security and Authentication
Flag | Description | Type |
---|---|---|
--mcp-global-auth-tokens | Global authentication tokens for all MCP clients | strings (comma-separated) |
--mcp-admin-tokens | Admin authentication tokens for MCP proxy | strings (comma-separated) |
--mcp-admin-allow-ips | IP addresses/CIDR blocks allowed for admin access. If empty, allows all IPs | strings (comma-separated) |
--mcp-trusted-proxies | Trusted proxy IP addresses/CIDR blocks | strings (comma-separated) |
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
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:
- 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"
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: