Mcpproxy Go MCP Server

🛡️ MCPProxy — Supercharge AI Agents, Safely

One safe endpoint in front of every MCP server.

The demo above shows the embedded web UI. The MCPProxy core is a single binary for macOS, Linux, and Windows — the web UI ships inside it, with no extra service to run. On macOS, an optional menu‑bar app adds one‑click convenience (start/stop, server health, quarantine, logs).

Why MCPProxy?

• Scale beyond API limits – Federate hundreds of MCP servers while bypassing Cursor's 40-tool limit and OpenAI's 128-function cap.
• Save tokens & accelerate responses – Agents load just one retrieve_tools function instead of hundreds of schemas. Research shows ~99 % token reduction with 43 % accuracy improvement.
• Advanced security protection – Automatic quarantine blocks Tool Poisoning Attacks until you manually approve new servers.
• Works offline & cross-platform – A single core binary for macOS (Intel & Apple Silicon), Windows (x64 & ARM64), and Linux (x64 & ARM64), with the web UI embedded. macOS additionally ships an optional menu-bar app.

---

Quick Start

1. Install

macOS (Recommended - DMG Installer):

Download the latest DMG installer for your architecture:

• Apple Silicon (M1/M2): Download DMG → mcpproxy-*-darwin-arm64.dmg
• Intel Mac: Download DMG → mcpproxy-*-darwin-amd64.dmg

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

Linux (Debian/Ubuntu) — apt repository, auto-updates via apt upgrade:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.mcpproxy.app/mcpproxy.gpg \
  | sudo tee /etc/apt/keyrings/mcpproxy.gpg > /dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/mcpproxy.gpg] https://apt.mcpproxy.app stable main" \
  | sudo tee /etc/apt/sources.list.d/mcpproxy.list > /dev/null
sudo apt update && sudo apt install mcpproxy

Linux (Fedora / RHEL / Rocky / AlmaLinux) — dnf repository, auto-updates via dnf upgrade:

sudo dnf config-manager --add-repo https://rpm.mcpproxy.app/mcpproxy.repo
sudo dnf install -y mcpproxy

Arch Linux (AUR): mcpproxy-bin

yay -S mcpproxy-bin
# or
git clone https://aur.archlinux.org/mcpproxy-bin.git && cd mcpproxy-bin && makepkg -si

Both packages ship a hardened systemd unit and start the service automatically. Repository signing key fingerprint: 3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B.

For one-off .deb / .rpm downloads (air-gapped installs), grab them from the latest release.

Manual download (all platforms):

• Linux tarball: 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

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 provides secure secrets management using your operating system's native keyring to store sensitive information like API keys, tokens, and credentials.

✨ Key Features

• OS-native security: Uses macOS Keychain, Linux Secret Service, or Windows Credential Manager
• Placeholder expansion: Automatically resolves ${keyring:secret_name} placeholders in config files
• Global access: Secrets are shared across all MCPProxy configurations and data directories
• CLI management: Full command-line interface for storing, retrieving, and managing secrets

🔧 Managing Secrets

Store a secret:

# Interactive prompt (recommended for sensitive values)
mcpproxy secrets set github_token

# From command line (less secure - visible in shell history)
mcpproxy secrets set github_token "ghp_abcd1234..."

# From environment variable
mcpproxy secrets set github_token --from-env GITHUB_TOKEN

List all secrets:

mcpproxy secrets list
# Output: Found 3 secrets in keyring:
#   github_token
#   openai_api_key
#   database_password

Retrieve a secret:

mcpproxy secrets get github_token

Delete a secret:

mcpproxy secrets delete github_token

📝 Using Placeholders in Configuration

Use ${keyring:secret_name} placeholders in your mcp_config.json:

{
  "mcpServers": [
    {
      "name": "github-mcp",
      "command": "uvx",
      "args": ["mcp-server-github"],
      "protocol": "stdio",
      "env": {
        "GITHUB_TOKEN": "${keyring:github_token}",
        "OPENAI_API_KEY": "${keyring:openai_api_key}"
      },
      "enabled": true
    },
    {
      "name": "database-server",
      "command": "python",
      "args": ["-m", "my_db_server", "--password", "${keyring:database_password}"],
      "protocol": "stdio",
      "enabled": true
    }
  ]
}

Placeholder expansion works in:

• ✅ Environment variables (env field)
• ✅ Command arguments (args field)
• ❌ Server names, commands, URLs (static fields)

🏗️ Secret Storage Architecture

Storage Location:

• macOS: Keychain Access (/Applications/Utilities/Keychain Access.app)
• Linux: Secret Service (GNOME Keyring, KDE Wallet, etc.)
• Windows: Windows Credential Manager

Service Name: All secrets are stored under the service name "mcpproxy"

Global Scope:

• ✅ Secrets are shared across all MCPProxy instances regardless of:
  • Configuration file location (--config flag)
  • Data directory (--data-dir flag)
  • Working directory
• ✅ Same secrets work across different projects and setups
• ⚠️ No isolation - all MCPProxy instances access the same keyring

🎯 Best Practices for Multiple Projects

If you use MCPProxy with multiple projects or environments, use descriptive secret names:

# Environment-specific secrets
mcpproxy secrets set prod_database_url
mcpproxy secrets set dev_database_url
mcpproxy secrets set staging_api_key

# Project-specific secrets
mcpproxy secrets set work_github_token
mcpproxy secrets set personal_github_token
mcpproxy secrets set client_a_api_key

Then reference them in your configs:

{
  "mcpServers": [
    {
      "name": "work-github",
      "env": {
        "GITHUB_TOKEN": "${keyring:work_github_token}"
      }
    },
    {
      "name": "personal-github",
      "env": {
        "GITHUB_TOKEN": "${keyring:personal_github_token}"
      }
    }
  ]
}

🔍 Security Considerations

• Encrypted storage: Secrets are encrypted by the OS keyring
• Process isolation: Other applications cannot access MCPProxy secrets without appropriate permissions
• No file storage: Secrets are never written to config files or logs
• Audit trail: OS keyring may provide access logs (varies by platform)

🐛 Troubleshooting

Secret not found:

# Verify secret exists
mcpproxy secrets list

# Check the exact secret name (case-sensitive)
mcpproxy secrets get your_secret_name

Keyring access denied:

• macOS: Grant MCPProxy access in System Preferences > Security & Privacy > Privacy > Accessibility
• Linux: Ensure your desktop session has an active keyring service
• Windows: Run MCPProxy with appropriate user permissions

Placeholder not resolving:

# Test secret resolution
mcpproxy secrets get your_secret_name

# Check logs for secret resolution errors
mcpproxy serve --log-level=debug

---

🐳 Docker Security Isolation

MCPProxy provides Docker isolation for stdio MCP servers to enhance security by running each server in its own isolated container:

✨ Key Security Benefits

• Process Isolation: Each MCP server runs in a separate Docker container
• File System Isolation: Servers cannot access host file system outside their container
• Network Isolation: Configurable network modes for additional security
• Resource Limits: Memory and CPU limits prevent resource exhaustion
• Automatic Runtime Detection: Detects Python, Node.js, Go, Rust environments automatically

🔧 How It Works

1. Runtime Detection: Automatically detects server type (uvx→Python, npx→Node.js, etc.)
2. Container Selection: Maps to appropriate Docker images with required tools
3. Environment Passing: Passes API keys and config via secure environment variables
4. Git Support: Uses full Docker images with Git for package installations from repositories

📝 Docker Isolation Configuration

Add to your mcp_config.json:

{
  "docker_isolation": {
    "enabled": true,
    "memory_limit": "512m",
    "cpu_limit": "1.0",
    "timeout": "60s",
    "network_mode": "bridge",
    "default_images": {
      "python": "python:3.11",
      "uvx": "python:3.11",
      "node": "node:20",
      "npx": "node:20",
      "go": "golang:1.21-alpine"
    }
  },
  "mcpServers": [
    {
      "name": "isolated-python-server",
      "command": "uvx",
      "args": ["some-python-package"],
      "env": {
        "API_KEY": "your-api-key"
      },
      "enabled": true
      // Docker isolation applied automatically
    },
    {
      "name": "custom-isolation-server",
      "command": "python",
      "args": ["-m", "my_server"],
      "isolation": {
        "enabled": true,
        "image": "custom-python:latest",
        "working_dir": "/app"
      },
      "enabled": true
    }
  ]
}

🎯 Automatic Runtime Detection

🔐 Security Features

• Environment Variables: API keys and secrets are passed securely to containers
• Git Support: Full images include Git for installing packages from repositories
• No Docker-in-Docker: Existing Docker servers are automatically excluded from isolation
• Resource Limits: Prevents runaway processes from consuming system resources
• Network Isolation: Containers run in isolated network environments

🐛 Docker Isolation Debugging

# Check which servers are using Docker isolation
mcpproxy serve --log-level=debug --tray=false | grep -i "docker isolation"

# Monitor Docker containers created by MCPProxy
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# View container logs for a specific server
docker logs <container-id>

---

🔄 Docker Recovery

MCPProxy includes intelligent Docker recovery that automatically detects and handles Docker engine outages:

✨ Key Features

• Automatic Detection: Monitors Docker health every 2-60 seconds with exponential backoff
• Graceful Reconnection: Automatically reconnects all Docker-based servers when Docker recovers
• System Notifications: Native notifications keep you informed of recovery progress
• Container Cleanup: Removes orphaned containers on shutdown
• Zero Configuration: Works out-of-the-box with sensible defaults

🔧 How It Works

1. Health Monitoring: Continuously checks Docker engine availability
2. Failure Detection: Detects when Docker becomes unavailable (paused, stopped, crashed)
3. Exponential Backoff: Starts with 2-second checks, backs off to 60 seconds to save resources
4. Automatic Reconnection: When Docker recovers, all affected servers are reconnected
5. User Notification: System notifications inform you of recovery status

📢 Notifications

MCPProxy shows native system notifications during Docker recovery:

🐛 Troubleshooting Docker Recovery

Servers don't reconnect after Docker recovery:

# 1. Check Docker is running
docker ps

# 2. Check mcpproxy logs
cat ~/.mcpproxy/logs/main.log | grep -i "docker recovery"

# 3. Verify container labels
docker ps -a --filter label=com.mcpproxy.managed

# 4. Force reconnect via system tray
# System Tray → Force Reconnect All Servers

Containers not cleaned up on shutdown:

# Check for orphaned containers
docker ps -a --filter label=com.mcpproxy.managed=true

# Manual cleanup if needed
docker ps -a --filter label=com.mcpproxy.managed=true -q | xargs docker rm -f

Docker recovery taking too long:

• Docker recovery uses exponential backoff (2s → 60s intervals)
• This is intentional to avoid wasting resources while Docker is offline
• You can force an immediate reconnect via the system tray menu

---

OAuth Authentication Support

MCPProxy provides seamless OAuth 2.1 authentication for MCP servers that require user authorization (like Cloudflare AutoRAG, Runlayer, GitHub, etc.):

✨ Key Features

• Zero-Config OAuth: Automatic detection and configuration for most OAuth servers
• RFC 8707 Resource Auto-Detection: Automatically discovers resource parameters from server metadata
• RFC 8252 Compliant: Dynamic port allocation for secure callback handling
• PKCE Security: Proof Key for Code Exchange for enhanced security
• Auto Browser Launch: Opens your default browser for authentication
• Dynamic Client Registration: Automatic client registration with OAuth servers
• Token Management: Automatic token refresh and storage

🔄 How It Works

1. Add OAuth Server: Configure an OAuth-enabled MCP server in your config
2. Auto Detection: MCPProxy detects OAuth requirements and auto-configures parameters
3. Browser Opens: Your default browser opens to the OAuth provider's login page
4. Dynamic Callback: MCPProxy starts a local callback server on a random port
5. Token Exchange: Authorization code is automatically exchanged for access tokens
6. Ready to Use: Server becomes available for tool calls immediately

📝 OAuth Configuration Examples

Zero-Config OAuth (Recommended)

For most OAuth servers (including Runlayer, Cloudflare, etc.), no OAuth configuration is needed. MCPProxy automatically:

• Detects OAuth requirements via 401 responses
• Discovers Protected Resource Metadata (RFC 9728)
• Injects the RFC 8707 resource parameter automatically

{
  "mcpServers": [
    {
      "name": "runlayer-slack",
      "url": "https://oauth.runlayer.com/api/v1/proxy/YOUR-UUID/mcp"
    },
    {
      "name": "cloudflare_autorag",
      "url": "https://autorag.mcp.cloudflare.com/mcp",
      "protocol": "streamable-http"
    }
  ]
}

That's it - no oauth block needed. MCPProxy handles everything automatically.

Explicit OAuth Configuration

Use explicit configuration when you need to:

• Customize OAuth scopes
• Override auto-detected parameters
• Use pre-registered client credentials
• Support providers with non-standard requirements

{
  "mcpServers": [
    {
      "name": "github-enterprise",
      "url": "https://github.example.com/mcp",
      "protocol": "http",
      "oauth": {
        "scopes": ["repo", "user:email", "read:org"],
        "pkce_enabled": true,
        "client_id": "your-registered-client-id",
        "extra_params": {
          "resource": "https://api.github.example.com",
          "audience": "github-enterprise-api"
        }
      }
    }
  ]
}

OAuth Configuration Options (all optional):

• scopes: OAuth scopes to request (auto-discovered if not specified)
• pkce_enabled: Enable PKCE for security (default: true, recommended)
• client_id: Pre-registered client ID (uses Dynamic Client Registration if empty)
• client_secret: Client secret (optional, for confidential clients)
• extra_params: Additional OAuth parameters (override auto-detected values)

🔍 OAuth Diagnostics

Check OAuth status and auto-detected parameters:

# View OAuth status for a specific server
mcpproxy auth status --server=runlayer-slack

# View all OAuth-enabled servers
mcpproxy auth status --all

# Run health diagnostics including OAuth issues
mcpproxy doctor

🔧 OAuth Debugging

Enable debug logging to see the complete OAuth flow:

mcpproxy serve --log-level=debug --tray=false

Check logs for OAuth flow details:

tail -f ~/Library/Logs/mcpproxy/main.log | grep -E "(oauth|OAuth)"

📂 Working Directory Configuration

Solve project context issues by specifying working directories for stdio MCP servers:

{
  "mcpServers": [
    {
      "name": "ast-grep-project-a",
      "command": "npx",
      "args": ["ast-grep-mcp"],
      "working_dir": "/home/user/projects/project-a",
      "enabled": true
    },
    {
      "name": "git-work-repo",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-git"],
      "working_dir": "/home/user/work/company-repo",
      "enabled": true
    }
  ]
}

Benefits:

• Project isolation: File-based servers operate in correct directory context
• Multiple projects: Same MCP server type for different projects
• Context separation: Work and personal project isolation

Tool-based Management:

# Add server with working directory
mcpproxy call tool --tool-name=upstream_servers \
  --json_args='{"operation":"add","name":"git-myproject","command":"npx","args_json":"[\"@modelcontextprotocol/server-git\"]","working_dir":"/home/user/projects/myproject","enabled":true}'

# Update existing server working directory
mcpproxy call tool --tool-name=upstream_servers \
  --json_args='{"operation":"update","name":"git-myproject","working_dir":"/new/project/path"}'

🔐 Optional HTTPS Setup

MCPProxy works with HTTP by default for easy setup. HTTPS is optional and primarily useful for production environments or when stricter security is required.

💡 Note: Most users can stick with HTTP (the default) as it works perfectly with all supported clients including Claude Desktop, Cursor, and VS Code.

Quick HTTPS Setup

1. Enable HTTPS (choose one method):

# Method 1: Environment variable
export MCPPROXY_TLS_ENABLED=true
mcpproxy serve

# Method 2: Config file
# Edit ~/.mcpproxy/mcp_config.json and set "tls.enabled": true

2. Trust the certificate (one-time setup):

mcpproxy trust-cert

3. Use HTTPS URLs:

• MCP endpoint: https://localhost:8080/mcp
• Web UI: https://localhost:8080/ui/

Claude Desktop Integration

For Claude Desktop, add this to your claude_desktop_config.json:

HTTP (Default - Recommended):

{
  "mcpServers": {
    "mcpproxy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8080/mcp"
      ]
    }
  }
}

HTTPS (With Certificate Trust):

{
  "mcpServers": {
    "mcpproxy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://localhost:8080/mcp"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "~/.mcpproxy/certs/ca.pem"
      }
    }
  }
}

Certificate Management

• Automatic generation: Certificates created on first HTTPS startup
• Multi-domain support: Works with localhost, 127.0.0.1, ::1
• Trust installation: Use mcpproxy trust-cert to add to system keychain
• Certificate location: ~/.mcpproxy/certs/ (ca.pem, server.pem, server-key.pem)

Troubleshooting HTTPS

Certificate trust issues:

# Re-trust certificate
mcpproxy trust-cert --force

# Check certificate location
ls ~/.mcpproxy/certs/

# Test HTTPS connection
curl -k https://localhost:8080/api/v1/status

Claude Desktop connection issues:

• Ensure NODE_EXTRA_CA_CERTS points to the correct ca.pem file
• Restart Claude Desktop after config changes
• Verify HTTPS is enabled: mcpproxy serve --log-level=debug

Learn More

• Documentation: Configuration, Features, Usage
• Website: https://mcpproxy.app
• Releases: https://github.com/smart-mcp-proxy/mcpproxy-go/releases

Contributing

We welcome issues, feature ideas, and PRs!

Development Setup

make dev-setup                # Install swag, frontend deps, Playwright
brew install prek             # Install pre-commit hook runner (or: uv tool install prek)
prek install                  # Install pre-commit hooks
prek install --hook-type pre-push  # Install pre-push hooks

Pre-commit Hooks

We use prek to catch issues before they reach CI:

Run hooks manually: prek run --all-files

Build & Test

make build          # Build frontend + backend
make swagger        # Regenerate OpenAPI spec
make test           # Unit tests
make test-e2e       # E2E tests
make lint           # Run linters