Windows (Recommended - Installer):

Download the latest Windows installer for your architecture:

• x64 (64-bit): Download Installer → mcpproxy-setup-*-amd64.exe
• ARM64: Download Installer → mcpproxy-setup-*-arm64.exe

The installer automatically:

• Installs both mcpproxy.exe (core server) and mcpproxy-tray.exe (system tray app) to Program Files
• Adds MCPProxy to your system PATH for command-line access
• Creates Start Menu shortcuts
• Supports silent installation: .\mcpproxy-setup.exe /VERYSILENT

Alternative install methods:

macOS (Homebrew):

brew install smart-mcp-proxy/mcpproxy/mcpproxy

Manual download (all platforms):

• Linux: AMD64 | ARM64
• Windows: AMD64 | ARM64

Prerelease Builds (Latest Features):

Want to try the newest features? Download prerelease builds from the next branch:

1. Go to GitHub Actions
2. Click the latest successful "Prerelease" workflow run
3. Download from Artifacts:
   • dmg-darwin-arm64 (Apple Silicon Macs)
   • dmg-darwin-amd64 (Intel Macs)
   • versioned-linux-amd64, versioned-windows-amd64 (other platforms)

Note: Prerelease builds are signed and notarized for macOS but contain cutting-edge features that may be unstable.

• macOS: Intel | Apple Silicon

Anywhere with Go 1.22+:

go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest

2. Run

mcpproxy serve          # starts HTTP server on :8080 and shows tray

3. Add servers

Edit mcp_config.json (see below). Or ask LLM to add servers (see doc).

4. Connect to your IDE/AI tool

📖 Complete Setup Guide - Detailed instructions for Cursor, VS Code, Claude Desktop, and Goose

Add proxy to Cursor

One-click install into Cursor IDE

Manual install

1. Open Cursor Settings
2. Click "Tools & Integrations"
3. Add MCP server

    "MCPProxy": {
      "type": "http",
      "url": "http://localhost:8080/mcp/"
    }

Minimal configuration (~/.mcpproxy/mcp_config.json)

{
  "listen": "127.0.0.1:8080",   // Localhost-only by default for security
  "data_dir": "~/.mcpproxy",
  "enable_tray": true,

  // Search & tool limits
  "top_k": 5,
  "tools_limit": 15,
  "tool_response_limit": 20000,

  // Optional HTTPS configuration (disabled by default)
  "tls": {
    "enabled": false,          // Set to true to enable HTTPS
    "require_client_cert": false,
    "hsts": true
  },

  "mcpServers": [
    { "name": "local-python", "command": "python", "args": ["-m", "my_server"], "protocol": "stdio", "enabled": true },
    { "name": "remote-http", "url": "http://localhost:3001", "protocol": "http", "enabled": true }
  ]
}

Key parameters

| Field | Description | Default | |-------|-------------|---------| | listen | Address the proxy listens on | 127.0.0.1:8080 | | data_dir | Folder for config, DB & logs | ~/.mcpproxy | | enable_tray | Show native system-tray UI | true | | top_k | Tools returned by retrieve_tools | 5 | | tools_limit | Max tools returned to client | 15 | | tool_response_limit | Auto-truncate responses above N chars (0 disables) | 20000 | | tls.enabled | Enable HTTPS with local CA certificates | false | | tls.require_client_cert | Enable mutual TLS (mTLS) for client authentication | false | | tls.certs_dir | Custom directory for TLS certificates | {data_dir}/certs | | tls.hsts | Send HTTP Strict Transport Security headers | true | | docker_isolation | Docker security isolation settings (see below) | enabled: false |

CLI Commands

Main Commands:

mcpproxy serve                      # Start proxy server with system tray
mcpproxy tools list --server=NAME  # Debug tool discovery for specific server
mcpproxy trust-cert                 # Install CA certificate as trusted (for HTTPS)

Management Commands:

# Single-server operations
mcpproxy upstream list              # List all servers with status
mcpproxy upstream restart <name>    # Restart specific server
mcpproxy upstream enable <name>     # Enable specific server
mcpproxy upstream disable <name>    # Disable specific server
mcpproxy upstream logs <name>       # View server logs (--tail, --follow)

# Bulk operations (multiple servers)
mcpproxy upstream restart --all     # Restart all configured servers
mcpproxy upstream enable --all      # Enable all servers
mcpproxy upstream disable --all     # Disable all servers

# Health diagnostics
mcpproxy doctor                     # Run comprehensive health checks

Management Service Architecture:

All management operations (CLI, REST API, and MCP protocol) share a unified service layer that provides:

• Configuration gates: Respects disable_management and read_only_mode settings
• Event integration: Real-time updates to system tray and web UI
• Bulk operations: Efficient multi-server management with partial failure handling
• Consistent behavior: Same validation and error handling across all interfaces

Serve Command Flags:

mcpproxy serve --help
  -c, --config <file>              path to mcp_config.json
  -l, --listen <addr>              listen address for HTTP mode
  -d, --data-dir <dir>             custom data directory
      --log-level <level>          trace|debug|info|warn|error
      --log-to-file                enable logging to file in standard OS location
      --read-only                  enable read-only mode
      --disable-management         disable management features
      --allow-server-add           allow adding new servers (default true)
      --allow-server-remove        allow removing existing servers (default true)
      --enable-prompts             enable prompts for user input (default true)
      --tool-response-limit <num>  tool response limit in characters (0 = disabled)

Tools Command Flags:

mcpproxy tools list --help
  -s, --server <name>          upstream server name (required)
  -l, --log-level <level>      trace|debug|info|warn|error (default: info)
  -t, --timeout <duration>     connection timeout (default: 30s)
  -o, --output <format>        output format: table|json|yaml (default: table)
  -c, --config <file>          path to mcp_config.json

Debug Examples:

# List tools with trace logging to see all JSON-RPC frames
mcpproxy tools list --server=github-server --log-level=trace

# List tools with custom timeout for slow servers
mcpproxy tools list --server=slow-server --timeout=60s

# Output tools in JSON format for scripting
mcpproxy tools list --server=weather-api --output=json

🔐 Secrets Management

MCPProxy p