mcpproxy-go

by smart-mcp-proxy

Not rated
GitHub

About

Open-source local MCP proxy server. Routes multiple MCP servers through a single endpoint with BM25 tool filtering, quarantine security, activity logging, and web UI.

Details

Author
smart-mcp-proxy
Categories
Developer Tools

Setup

Install mcpproxy-go in your MCP client (Claude Desktop, Cursor, Windsurf, and others).

Repository: https://github.com/smart-mcp-proxy/mcpproxy-go

Follow the installation instructions in the repository README, then restart your MCP client.

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

The demo above shows theembedded web UI. The MCPProxycore is a single binary for macOS, Linux, and Windows— the web UI ships inside it, with no extra service to run. OnmacOS, an optionalmenu‑bar appadds one‑click convenience (start/stop, server health, quarantine, logs).

- 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 oneretrieve_toolsfunction instead of hundreds of schemas. Research shows ~99 % token reduction with43 % 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 theweb UI embedded. macOS additionally ships an optional menu-bar app.

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

Download the latest Windows installer for your architecture:

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

- Installs bothmcpproxy.exe(core server) andmcpproxy-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

# 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 viabrew upgrade.

Linux (Debian/Ubuntu) — apt repository, auto-updates viaapt 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 viadnf 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
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 hardenedsystemdunit and start the service automatically. Repository signing key fingerprint:3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B.

For one-off.deb/.rpmdownloads (air-gapped installs), grab them from thelatest release.

- Linux tarball:AMD64|ARM64
- Windows:
AMD64|ARM64

Want to try the newest features? Download prerelease builds from thenextbranch:
- Go to
GitHub Actions
- Click the latest successful "Prerelease" workflow run
- Download fromArtifacts:

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

go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest
mcpproxy serve # starts HTTP server on :8080 and shows tray

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 } ] }

SeeConfigurationandUpstream Serversfor the full reference.

📖Complete Setup Guide- Detailed instructions for Cursor, VS Code, Claude Desktop, and Goose
- Open Cursor Settings
- Click "Tools & Integrations"
- Add MCP server

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

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 viaretrieve_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 acall_withhint 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 agentdidn'tneed never enter its context. The agent loads full schemas on demand withdescribe_tool(batch up to 5 ids) only for the tools it's about to use.

The agent executes the tool through the variant matching its intent (call_tool_read,call_tool_write, orcall_tool_destructive), addressing it asserver: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.

Every call lands in the localActivity Logwith 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

SeeRequired-Tools Preflightfor the full reason taxonomy, REST endpoint, and GitHub Actions / n8n recipes.

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.

# 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):

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

For Claude Desktop, add this to yourclaude_desktop_config.json:

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

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

# Re-trust certificate mcpproxy trust-cert --force # Check certificate location ls ~/.mcpproxy/certs/ # Test HTTPS connection curl -k https://localhost:8080/api/v1/status

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

- Config File Reference
-
Upstream Servers
-
Environment Variables

- 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

- Command Reference
-
Management Commands
-
Activity Commands
-
Security Commands

We welcome issues, feature ideas, and PRs!

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

We useprekto catch issues before they reach CI:

Run hooks manually:prek run --all-files

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

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Create crafted UI components inspired by the best 21st.dev design engineers.

Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server

An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .

MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent

ALAPI MCP Tools,Call hundreds of API interfaces via MCP

AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform

MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references.

APIMatic MCP Server is used to validate OpenAPI specifications using APIMatic. The server processes OpenAPI files and returns validation summaries by leveraging APIMatic’s API.

One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.