MCPProxy

📺 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.
• Spend less context on tool definitions – Agents see a small set of MCPProxy discovery and execution tools (retrieve_tools, describe_tool, the call_tool_* variants and a few management tools) instead of the full upstream tool catalog, and fetch schemas on demand (in retrieve_tools and code_execution routing; direct routing exposes upstream tools individually, see Routing modes). How much context this saves depends on the number of tools, the routing mode, the client and the task; see Token savings: what is and is not measured.
• Review before use – New servers are quarantined and their tools are withheld from agents until you review and approve them, and, under the default manual trust mode, most later changes to an approved tool's definition are held for review again. Known exceptions: input-schema-only edits outside scan mode, a newly added output schema, and a description added to a tool that was approved with an empty description are admitted without a hold; scan mode admits clean changes and misses what its detectors miss; auto mode does not hold changes. This reduces exposure to malicious tool definitions (Tool Poisoning Attacks); it is not a guarantee of safety. See What quarantine does and does not cover.
• 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.

Token savings: what is and is not measured

On-demand discovery reduces how many upstream tool definitions an agent loads into context up front. The saving is not a fixed percentage: it grows with the number of connected tools and depends on the routing mode, the client and the task. MCPProxy does not publish a headline token-reduction or accuracy-improvement figure, and it makes no latency claim.

What the repository does measure, as a first-party, deterministic estimate (see bench/README.md for the method and to reproduce it with go run ./bench/cmd/bench):

• Corpus: the frozen 45-tool reference corpus; counting tool name and description only (input schemas excluded), cl100k_base.
• Metric: size of the initial tool menu in tokens, including the proxy's own discovery, call and management tools. Not total workflow tokens, not latency, and not task success.
• Result: on that 45-tool corpus the proxy's initial menu is larger than listing every upstream tool (2625 tokens in retrieve_tools mode and 1874 in code_execution mode, against 1730 for the baseline), because the proxy's own tools have a fixed cost. A saving appears only above a break-even number of upstream tools, so quote the tool count with any percentage.

---

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.26+:

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 and approve it

New servers are held in quarantine until you review them, so adding a server is a two-step journey: add, then review and approve. The full walkthrough, with a real remote server (Context7), is the published Quick Start. In short (Context7 is a public, read-only documentation server; substitute any server you trust):

# 1. add (held in quarantine until approved)

mcpproxy upstream add context7 https://mcp.context7.com/mcp

2. review: capture the tool definitions, run the offline scan, read the verdict

mcpproxy review fetch context7 mcpproxy security rescan context7 mcpproxy review show context7

3. approve (with no --tools/--all, only read-only tools with a clean scan are allowed)

mcpproxy review approve context7 --yes

4. one harmless read, then see it in the activity log

mcpproxy call tool-read -t context7:resolve-library-id -j '{"libraryName":"vue-router","query":"routing"}' mcpproxy activity list --limit 3

A clean scan is not proof that a server is safe; it only means the offline checks found nothing in the tool definitions. Review what you approve.

You can also edit ~/.mcpproxy/mcp_config.json by hand; a first-seen entry is held for review in the same way:

{

"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](https://docs.mcpproxy.app/configuration/upstream-ser