MCPProxy – Smart Proxy for AI Agents

MCPProxy is an open-source desktop application that super-charges AI agents with intelligent tool discovery, massive token savings, and built-in security quarantine against malicious MCP servers.

🌐 Visit mcpproxy.app

    
System Tray - Upstream Servers          System Tray - Quarantine Management

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 – Native binaries for macOS (Intel & Apple Silicon), Windows (x64 & ARM64), and Linux (x64 & ARM64) with system-tray UI.

---

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

Alternative install methods:

macOS (Homebrew):

brew install smart-mcp-proxy/mcpproxy/mcpproxy

Manual download (all platforms):

• Linux: AMD64 | ARM64
• Windows: AMD64 | ARM64
• 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": ":8080",
  "data_dir": "~/.mcpproxy",
  "enable_tray": true,

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

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

Key parameters

Field	Description	Default
listen	Address the proxy listens on	: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
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

Serve Command Flags:

mcpproxy serve --help
  -c, --config <file>          path to mcp_config.json
  -l, --listen <addr>          listen address (":8080")
  -d, --data-dir <dir>         custom data directory
      --tray                   enable/disable system tray (default true, use --tray=false to disable)
      --log-level <level>      debug|info|warn|error
      --read-only              forbid config changes
      --disable-management     disable upstream_servers tool
      --allow-server-add       allow adding servers (default true)
      --allow-server-remove    allow removing servers (default true)

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

---

🐳 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

Command	Detected Runtime	Docker Image
uvx	Python with UV package manager	python:3.11
npx	Node.js with npm	node:20
python, python3	Python	python:3.11
node	Node.js	node:20
go	Go language	golang:1.21-alpine
cargo	Rust	rust:1.75-slim

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

---

OAuth Authentication Support

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

✨ Key Features

• 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 Authentication: MCPProxy detects when OAuth is required (401 response)
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 Server Configuration

Note: The "oauth" configuration is optional. MCPProxy will automatically detect when OAuth is required and use sensible defaults in most cases. You only need to specify OAuth settings if you want to customize scopes or have pre-registered client credentials.

{
  "mcpServers": [
    {
      "name": "cloudflare_autorag",
      "url": "https://autorag.mcp.cloudflare.com/mcp",
      "protocol": "streamable-http",
      "enabled": true,
      "oauth": {
        "scopes": ["mcp.read", "mcp.write"],
        "pkce_enabled": true
      }
    }
  ]
}

OAuth Configuration Options (all optional):

• scopes: OAuth scopes to request (default: ["mcp.read", "mcp.write"])
• pkce_enabled: Enable PKCE for security (default: true, recommended)
• client_id: Pre-registered client ID (optional, uses Dynamic Client Registration if empty)
• client_secret: Client secret (optional, for confidential clients)

🔧 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"}'

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! Fork the repo, create a feature branch, and open a pull request. See CONTRIBUTING.md (coming soon) for guidelines.