Mcpproxy Go README

📺 Watch the full walkthrough  ·  📚 Read the docs  ·  🌐 mcpproxy.app

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).

    
macOS menu‑bar app   ·   Activity log & audit in the macOS app

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.
• Pluggable security scanners – Run Snyk, Semgrep, Trivy, Cisco, and other Docker-based scanners against quarantined servers before you approve them; findings are normalized to SARIF with a composite risk score. See Security scanner plugins.
• 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):

# macOS — GUI tray app (recommended):
brew install --cask smart-mcp-proxy/mcpproxy/mcpproxy

# macOS / Linux — headless CLI only:
brew install smart-mcp-proxy/mcpproxy/mcpproxy

The cask installs the menu-bar app (bundles the CLI); the formula is the CLI binary only. Both update via brew upgrade.

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
# Fedora 41+ (dnf5): sudo curl -fsSL https://rpm.mcpproxy.app/mcpproxy.repo -o /etc/yum.repos.d/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

The apt and dnf 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.25+:

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 your first server

Create or edit ~/.mcpproxy/mcp_config.json:

{
  "listen": "127.0.0.1:8080",
  "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 }
  ]
}

See Configuration and Upstream Servers for the full reference.

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/"
    }

How AI Agents Work Through MCPProxy

Once connected, your agent sees a handful of built-in MCPProxy tools instead of hundreds of upstream schemas. A typical session has three beats — discover, call, audit — plus an optional preflight gate for unattended automations.

1. Discover — spend one query, not your context window

The agent asks for what it needs in plain keywords via retrieve_tools:

{ "query": "create github issue", "limit": 5 }

MCPProxy runs a BM25 search across every connected server and returns only the top-ranked matches — each with a call_with hint recommending the right call variant for its annotations:

{
  "tools": [
    { "name": "github:create_issue", "score": 0.89, "call_with": "call_tool_write" },
    { "name": "gitlab:create_issue", "score": 0.72, "call_with": "call_tool_write" }
  ]
}

This is where the token savings come from: the schemas of the hundreds of tools the agent didn't need never enter its context. The agent loads full schemas on demand with describe_tool (batch up to 5 ids) only for the tools it's about to use.

2. Call — with declared intent

The agent executes the tool through the variant matching its intent (call_tool_read, call_tool_write, or call_tool_destructive), addressing it as server:tool:

{
  "name": "github:create_issue",
  "args_json": "{\"repo\": \"acme/api\", \"title\": \"Bug report\"}",
  "intent": { "operation_type": "write", "reason": "Filing bug per user request" }
}

MCPProxy validates the intent against the tool's annotations (a "read" call can't reach a destructive tool), checks quarantine and approval state, and scans arguments and responses for sensitive data before anything leaves the machine.

3. Audit — every call is on the record

Every call lands in the local Activity Log with a request ID, so you can reconstruct exactly what an agent did:

mcpproxy activity list                          # everything, newest first
mcpproxy activity list --request-id <id>        # one workflow, correlated

Gate automations before they burn tokens

For recurring headless jobs (cron, CI, n8n), don't let the agent discover a missing tool the expensive way. One preflight command checks that every required tool is ready — without contacting any upstream server — and reports exactly why when it isn't (server quarantined, tool changed since approval, OAuth expired, typo'd id):

mcpproxy tools preflight gh-ops:sync_issues slack:post_message --wait 10s
case $? in
  0)  run-agent-session ;;   # all ready — go
  10) exit 75 ;;             # transient (server starting) — let the next cron tick retry
  11) page-operator ;;       # blocked — someone must approve / enable / log in
  12) fail-pipeline ;;       # unknown tool id — the automation itself is misconfigured
esac

See Required-Tools Preflight for the full reason taxonomy, REST endpoint, and GitHub Actions / n8n recipes.

🔐 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

Documentation

Getting Started

• Installation
• Quick Start

Configuration

• Config File Reference
• Upstream Servers
• Environment Variables

Features

• Search & Tool Discovery
• Security Quarantine
• Security Scanner Plugins
• Docker Security Isolation
• Secrets & Keyring Integration
• OAuth Authentication
• Code Execution
• Activity Log
• Required-Tools Preflight
• Agent Tokens
• Sensitive Data Detection

CLI Reference

• Command Reference
• Management Commands
• Activity Commands
• Security Commands

API

• REST API
• MCP Protocol

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