MCP Proxy Server

The MCP Proxy Server is the central gateway that manages all MCP server connections in Compozy. It acts as a reverse proxy, connection manager, and administration hub for MCP servers, providing a unified HTTP interface for multiple MCP servers.

Central Hub: The MCP Proxy Server eliminates the need for individual MCP client connections by providing a single point of access for all MCP servers.

Architecture Overview

Loading diagram...

Core Components

Key Features

Multi-Transport Support

stdio, SSE, and streamable-http transports for different communication patterns

Dynamic Registration

Hot-add, update, or remove servers via Admin API with zero downtime

Security & Authentication

Token-based auth, IP restrictions, and trusted proxy support

Storage Flexibility

In-memory for development, Redis for production persistence

Transport Support Details

Standard I/O Transport

For local process communication with high performance:

Use Case: Local MCP servers, Docker containers, command-line tools
Performance: Low latency, high throughput
Security: Process-level isolation
Management: Automatic process lifecycle management

Best For: Development environments and local tool integration

Configuration

Server Configuration

Configuration Structure

Configuration Structure

type Config struct {
    Port               string        // TCP port (default: "6001")
    Host               string        // Listen address (default: "0.0.0.0")
    BaseURL            string        // Base URL for generating paths
    ShutdownTimeout    time.Duration // Graceful shutdown timeout
    AdminTokens        []string      // Admin API bearer tokens
    AdminAllowIPs      []string      // Admin API IP allow-list
    TrustedProxies     []string      // Trusted proxy IPs
    GlobalAuthTokens   []string      // Global auth tokens
    StorageType        string        // Storage backend type
    MaxConnections     int           // Maximum concurrent connections
    IdleTimeout        time.Duration // Connection idle timeout
    ReadTimeout        time.Duration // HTTP read timeout
    WriteTimeout       time.Duration // HTTP write timeout
}

Environment Variables

Basic Server Configuration

Basic Environment Variables

# Server configuration
MCP_PROXY_HOST=0.0.0.0
MCP_PROXY_PORT=6001
MCP_PROXY_BASE_URL=http://localhost:6001

# Shutdown timeout
MCP_PROXY_SHUTDOWN_TIMEOUT=30s

Deployment Options

CLI Deployment

Basic Start

Start with default configuration:

compozy mcp-proxy

Custom Configuration

Start with custom settings:

# Basic start without authentication
compozy mcp-proxy \
  --mcp-host 0.0.0.0 \
  --mcp-port 6001

# With authentication enabled
compozy mcp-proxy \
  --host 0.0.0.0 \
  --port 6001 \
  --admin-tokens "secure-admin-token" \
  --admin-allow-ips "10.0.0.0/8,192.168.1.0/24"

Production Configuration

Use environment variables for production:

export MCP_PROXY_ADMIN_TOKEN="$(openssl rand -hex 32)"
export MCP_PROXY_GLOBAL_AUTH_TOKEN="$(openssl rand -hex 32)"
compozy mcp-proxy --mcp-host 0.0.0.0 --mcp-port 6001

Docker Deployment

Simple Docker Container

Dockerfile

FROM ghcr.io/compozy/mcp-proxy:latest

EXPOSE 6001

CMD ["compozy", "mcp-proxy", "--mcp-host", "0.0.0.0", "--mcp-port", "6001"]

Run Container

docker run -p 6001:6001 \
  -e MCP_PROXY_ADMIN_TOKEN=secure-token \
  -e MCP_PROXY_GLOBAL_AUTH_TOKEN=global-token \
  ghcr.io/compozy/mcp-proxy:latest \
  compozy mcp-proxy

API Reference

For detailed API endpoint documentation, see our comprehensive API reference:

Operations API

Health checks, metrics, and system management endpoints

Quick Reference

Health Check: GET /healthz - Monitor server health
Metrics: GET /metrics - Prometheus-compatible metrics
Admin API: Requires Authorization: Bearer <token> header
Server Management: Register, update, and remove MCP servers
Tool Discovery: List all available tools across servers

Health Checks & Monitoring

Health Check Endpoint

# Basic health check
curl http://localhost:6001/healthz

# Response format
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "uptime": "2h30m15s",
  "connections": {
    "active": 25,
    "total": 150
  },
  "storage": {
    "type": "redis",
    "status": "connected"
  }
}

Health Check Features:

Server availability status
Connection pool health
Storage backend connectivity
Uptime information
Resource utilization

Troubleshooting

Connection Issues

Issue	Symptoms	Solution
Connection Refused	`curl: (7) Failed to connect`	Check if proxy is running on correct port
Port Already in Use	`bind: address already in use`	Change port or stop conflicting process
Firewall Blocking	Connections timeout	Configure firewall rules for port 6001
DNS Resolution	`no such host`	Verify hostname/IP configuration

Debug Commands:

# Check if proxy is running
ps aux | grep mcp-proxy

# Verify port is open
netstat -tulpn | grep :6001

# Test connectivity
telnet localhost 6001

Debug Mode

Debug Mode: Enable debug logging for troubleshooting, but avoid in production due to performance impact.

# Enable debug logging
compozy mcp-proxy --debug

# Or with environment variable
MCP_PROXY_LOG_LEVEL=debug compozy mcp-proxy

# Debug with specific components
MCP_PROXY_LOG_LEVEL=debug \
MCP_PROXY_LOG_COMPONENTS=router,auth,transport \
compozy mcp-proxy