{"id":32593860,"url":"https://github.com/smart-mcp-proxy/mcpproxy-go","last_synced_at":"2026-04-26T16:05:58.074Z","repository":{"id":299764602,"uuid":"1004056914","full_name":"smart-mcp-proxy/mcpproxy-go","owner":"smart-mcp-proxy","description":"Supercharge AI Agents, Safely","archived":false,"fork":false,"pushed_at":"2026-02-28T19:50:22.000Z","size":148290,"stargazers_count":136,"open_issues_count":19,"forks_count":19,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-28T22:54:24.287Z","etag":null,"topics":["ai","ai-agents","audit-logging","bm25","cli","context-window","developer-tools","docker","golang","llm","llm-tools","local-first","mcp","mcp-proxy","mcp-server","model-context-protocol","proxy-server","security","tool-routing","web-ui"],"latest_commit_sha":null,"homepage":"https://mcpproxy.app","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smart-mcp-proxy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-06-18T03:59:17.000Z","updated_at":"2026-02-28T19:50:27.000Z","dependencies_parsed_at":"2025-07-02T09:24:43.412Z","dependency_job_id":"43e7319b-2902-49ee-b0b5-1f85b69e1fbc","html_url":"https://github.com/smart-mcp-proxy/mcpproxy-go","commit_stats":null,"previous_names":["smart-mcp-proxy/mcpproxy-go"],"tags_count":158,"template":false,"template_full_name":null,"purl":"pkg:github/smart-mcp-proxy/mcpproxy-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smart-mcp-proxy%2Fmcpproxy-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smart-mcp-proxy%2Fmcpproxy-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smart-mcp-proxy%2Fmcpproxy-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smart-mcp-proxy%2Fmcpproxy-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smart-mcp-proxy","download_url":"https://codeload.github.com/smart-mcp-proxy/mcpproxy-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smart-mcp-proxy%2Fmcpproxy-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30040335,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T06:58:30.252Z","status":"ssl_error","status_checked_at":"2026-03-03T06:58:15.329Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","audit-logging","bm25","cli","context-window","developer-tools","docker","golang","llm","llm-tools","local-first","mcp","mcp-proxy","mcp-server","model-context-protocol","proxy-server","security","tool-routing","web-ui"],"created_at":"2025-10-30T02:02:38.587Z","updated_at":"2026-04-26T16:05:58.067Z","avatar_url":"https://github.com/smart-mcp-proxy.png","language":"Go","readme":"# MCPProxy – Smart Proxy for AI Agents\n\n**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.\n\n### **📚 [Read the Documentation](https://docs.mcpproxy.app/)**\n\n\u003c!-- Old video: https://youtu.be/l4hh6WOuSFM --\u003e\n[![MCPProxy Demo](https://img.youtube.com/vi/2aKrgJnbbcw/0.jpg)](https://youtu.be/2aKrgJnbbcw)\n\n\u003ca href=\"https://mcpproxy.app\" target=\"_blank\" rel=\"noopener\"\u003e🌐 Visit mcpproxy.app\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://mcpproxy.app/images/menu_upstream_servers.png\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://mcpproxy.app/images/menu_upstream_servers.png\" alt=\"System Tray - Upstream Servers\" width=\"250\" /\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://mcpproxy.app/images/menu_security_quarantine.png\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://mcpproxy.app/images/menu_security_quarantine.png\" alt=\"System Tray - Quarantine Management\" width=\"250\" /\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n  \u003cem\u003eSystem Tray - Upstream Servers \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; System Tray - Quarantine Management\u003c/em\u003e\n\u003c/div\u003e\n\n\n## Why MCPProxy?\n\n- **Scale beyond API limits** – Federate hundreds of MCP servers while bypassing Cursor's 40-tool limit and OpenAI's 128-function cap.\n- **Save tokens \u0026 accelerate responses** – Agents load just one `retrieve_tools` function instead of hundreds of schemas. Research shows ~99 % token reduction with **43 % accuracy improvement**.\n- **Advanced security protection** – Automatic quarantine blocks Tool Poisoning Attacks until you manually approve new servers.\n- **Works offline \u0026 cross-platform** – Native binaries for macOS (Intel \u0026 Apple Silicon), Windows (x64 \u0026 ARM64), and Linux (x64 \u0026 ARM64) with system-tray UI.\n\n---\n\n## Quick Start\n\n### 1. Install\n\n**macOS (Recommended - DMG Installer):**\n\nDownload the latest DMG installer for your architecture:\n- **Apple Silicon (M1/M2):** [Download DMG](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-*-darwin-arm64.dmg`\n- **Intel Mac:** [Download DMG](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-*-darwin-amd64.dmg`\n\n**Windows (Recommended - Installer):**\n\nDownload the latest Windows installer for your architecture:\n- **x64 (64-bit):** [Download Installer](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-setup-*-amd64.exe`\n- **ARM64:** [Download Installer](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest) → `mcpproxy-setup-*-arm64.exe`\n\nThe installer automatically:\n- Installs both `mcpproxy.exe` (core server) and `mcpproxy-tray.exe` (system tray app) to Program Files\n- Adds MCPProxy to your system PATH for command-line access\n- Creates Start Menu shortcuts\n- Supports silent installation: `.\\mcpproxy-setup.exe /VERYSILENT`\n\n**Alternative install methods:**\n\nmacOS (Homebrew):\n```bash\nbrew install smart-mcp-proxy/mcpproxy/mcpproxy\n```\n\nLinux (Debian/Ubuntu) — apt repository, auto-updates via `apt upgrade`:\n```bash\nsudo install -m 0755 -d /etc/apt/keyrings\ncurl -fsSL https://apt.mcpproxy.app/mcpproxy.gpg \\\n  | sudo tee /etc/apt/keyrings/mcpproxy.gpg \u003e /dev/null\necho \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/mcpproxy.gpg] https://apt.mcpproxy.app stable main\" \\\n  | sudo tee /etc/apt/sources.list.d/mcpproxy.list \u003e /dev/null\nsudo apt update \u0026\u0026 sudo apt install mcpproxy\n```\n\nLinux (Fedora / RHEL / Rocky / AlmaLinux) — dnf repository, auto-updates via `dnf upgrade`:\n```bash\nsudo dnf config-manager --add-repo https://rpm.mcpproxy.app/mcpproxy.repo\nsudo dnf install -y mcpproxy\n```\n\nBoth 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`.\n\nFor one-off `.deb` / `.rpm` downloads (air-gapped installs), grab them from the [latest release](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest).\n\nManual download (all platforms):\n- **Linux tarball**: [AMD64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-linux-amd64.tar.gz) | [ARM64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-linux-arm64.tar.gz)\n- **Windows**: [AMD64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-windows-amd64.zip) | [ARM64](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-windows-arm64.zip)\n\n**Prerelease Builds (Latest Features):**\n\nWant to try the newest features? Download prerelease builds from the `next` branch:\n\n1. Go to [GitHub Actions](https://github.com/smart-mcp-proxy/mcpproxy-go/actions)\n2. Click the latest successful \"Prerelease\" workflow run\n3. Download from **Artifacts**:\n   - `dmg-darwin-arm64` (Apple Silicon Macs)\n   - `dmg-darwin-amd64` (Intel Macs)\n   - `versioned-linux-amd64`, `versioned-windows-amd64` (other platforms)\n\n\u003e **Note**: Prerelease builds are signed and notarized for macOS but contain cutting-edge features that may be unstable.\n\n- **macOS**: [Intel](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-darwin-amd64.tar.gz) | [Apple Silicon](https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-darwin-arm64.tar.gz)\n\nAnywhere with Go 1.22+:\n```bash\ngo install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest\n```\n\n### 2. Run\n\n```bash\nmcpproxy serve          # starts HTTP server on :8080 and shows tray\n```\n\n### 3. Add servers\n\nEdit `mcp_config.json` (see below). Or **ask LLM** to add servers (see [doc](https://mcpproxy.app/docs/configuration#adding-servers)).\n\n### 4. Connect to your IDE/AI tool\n\n📖 **[Complete Setup Guide](docs/setup.md)** - Detailed instructions for Cursor, VS Code, Claude Desktop, and Goose\n\n## Add proxy to Cursor\n\n### One-click install into Cursor IDE\n\n[![Install in Cursor IDE](https://img.shields.io/badge/Install_in_Cursor-3e44fe?logo=data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94P…\u0026style=for-the-badge)](https://mcpproxy.app/cursor-install.html)\n\n### Manual install\n\n\n1. Open Cursor Settings\n2. Click \"Tools \u0026 Integrations\"\n3. Add MCP server\n```json\n    \"MCPProxy\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8080/mcp/\"\n    }\n```\n\n---\n\n## Minimal configuration (`~/.mcpproxy/mcp_config.json`)\n\n```jsonc\n{\n  \"listen\": \"127.0.0.1:8080\",   // Localhost-only by default for security\n  \"data_dir\": \"~/.mcpproxy\",\n  \"enable_tray\": true,\n\n  // Search \u0026 tool limits\n  \"top_k\": 5,\n  \"tools_limit\": 15,\n  \"tool_response_limit\": 20000,\n\n  // Optional HTTPS configuration (disabled by default)\n  \"tls\": {\n    \"enabled\": false,          // Set to true to enable HTTPS\n    \"require_client_cert\": false,\n    \"hsts\": true\n  },\n\n  \"mcpServers\": [\n    { \"name\": \"local-python\", \"command\": \"python\", \"args\": [\"-m\", \"my_server\"], \"protocol\": \"stdio\", \"enabled\": true },\n    { \"name\": \"remote-http\", \"url\": \"http://localhost:3001\", \"protocol\": \"http\", \"enabled\": true }\n  ]\n}\n```\n\n### Key parameters\n\n| Field | Description | Default |\n|-------|-------------|---------|\n| `listen` | Address the proxy listens on | `127.0.0.1:8080` |\n| `data_dir` | Folder for config, DB \u0026 logs | `~/.mcpproxy` |\n| `enable_tray` | Show native system-tray UI | `true` |\n| `top_k` | Tools returned by `retrieve_tools` | `5` |\n| `tools_limit` | Max tools returned to client | `15` |\n| `tool_response_limit` | Auto-truncate responses above N chars (`0` disables) | `20000` |\n| `tls.enabled` | Enable HTTPS with local CA certificates | `false` |\n| `tls.require_client_cert` | Enable mutual TLS (mTLS) for client authentication | `false` |\n| `tls.certs_dir` | Custom directory for TLS certificates | `{data_dir}/certs` |\n| `tls.hsts` | Send HTTP Strict Transport Security headers | `true` |\n| `docker_isolation` | Docker security isolation settings (see below) | `enabled: false` |\n\n### CLI Commands\n\n**Main Commands:**\n```bash\nmcpproxy serve                      # Start proxy server with system tray\nmcpproxy tools list --server=NAME  # Debug tool discovery for specific server\nmcpproxy trust-cert                 # Install CA certificate as trusted (for HTTPS)\n```\n\n**Management Commands:**\n```bash\n# Single-server operations\nmcpproxy upstream list              # List all servers with status\nmcpproxy upstream restart \u003cname\u003e    # Restart specific server\nmcpproxy upstream enable \u003cname\u003e     # Enable specific server\nmcpproxy upstream disable \u003cname\u003e    # Disable specific server\nmcpproxy upstream logs \u003cname\u003e       # View server logs (--tail, --follow)\n\n# Bulk operations (multiple servers)\nmcpproxy upstream restart --all     # Restart all configured servers\nmcpproxy upstream enable --all      # Enable all servers\nmcpproxy upstream disable --all     # Disable all servers\n\n# Health diagnostics\nmcpproxy doctor                     # Run comprehensive health checks\n```\n\n**Management Service Architecture:**\n\nAll management operations (CLI, REST API, and MCP protocol) share a unified service layer that provides:\n- **Configuration gates**: Respects `disable_management` and `read_only_mode` settings\n- **Event integration**: Real-time updates to system tray and web UI\n- **Bulk operations**: Efficient multi-server management with partial failure handling\n- **Consistent behavior**: Same validation and error handling across all interfaces\n\n**Serve Command Flags:**\n```text\nmcpproxy serve --help\n  -c, --config \u003cfile\u003e              path to mcp_config.json\n  -l, --listen \u003caddr\u003e              listen address for HTTP mode\n  -d, --data-dir \u003cdir\u003e             custom data directory\n      --log-level \u003clevel\u003e          trace|debug|info|warn|error\n      --log-to-file                enable logging to file in standard OS location\n      --read-only                  enable read-only mode\n      --disable-management         disable management features\n      --allow-server-add           allow adding new servers (default true)\n      --allow-server-remove        allow removing existing servers (default true)\n      --enable-prompts             enable prompts for user input (default true)\n      --tool-response-limit \u003cnum\u003e  tool response limit in characters (0 = disabled)\n```\n\n**Tools Command Flags:**\n```text\nmcpproxy tools list --help\n  -s, --server \u003cname\u003e          upstream server name (required)\n  -l, --log-level \u003clevel\u003e      trace|debug|info|warn|error (default: info)\n  -t, --timeout \u003cduration\u003e     connection timeout (default: 30s)\n  -o, --output \u003cformat\u003e        output format: table|json|yaml (default: table)\n  -c, --config \u003cfile\u003e          path to mcp_config.json\n```\n\n**Debug Examples:**\n```bash\n# List tools with trace logging to see all JSON-RPC frames\nmcpproxy tools list --server=github-server --log-level=trace\n\n# List tools with custom timeout for slow servers\nmcpproxy tools list --server=slow-server --timeout=60s\n\n# Output tools in JSON format for scripting\nmcpproxy tools list --server=weather-api --output=json\n```\n\n---\n\n## 🔐 Secrets Management\n\nMCPProxy provides secure secrets management using your operating system's native keyring to store sensitive information like API keys, tokens, and credentials.\n\n### ✨ **Key Features**\n- **OS-native security**: Uses macOS Keychain, Linux Secret Service, or Windows Credential Manager\n- **Placeholder expansion**: Automatically resolves `${keyring:secret_name}` placeholders in config files\n- **Global access**: Secrets are shared across all MCPProxy configurations and data directories\n- **CLI management**: Full command-line interface for storing, retrieving, and managing secrets\n\n### 🔧 **Managing Secrets**\n\n**Store a secret:**\n```bash\n# Interactive prompt (recommended for sensitive values)\nmcpproxy secrets set github_token\n\n# From command line (less secure - visible in shell history)\nmcpproxy secrets set github_token \"ghp_abcd1234...\"\n\n# From environment variable\nmcpproxy secrets set github_token --from-env GITHUB_TOKEN\n```\n\n**List all secrets:**\n```bash\nmcpproxy secrets list\n# Output: Found 3 secrets in keyring:\n#   github_token\n#   openai_api_key\n#   database_password\n```\n\n**Retrieve a secret:**\n```bash\nmcpproxy secrets get github_token\n```\n\n**Delete a secret:**\n```bash\nmcpproxy secrets delete github_token\n```\n\n### 📝 **Using Placeholders in Configuration**\n\nUse `${keyring:secret_name}` placeholders in your `mcp_config.json`:\n\n```jsonc\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"github-mcp\",\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-github\"],\n      \"protocol\": \"stdio\",\n      \"env\": {\n        \"GITHUB_TOKEN\": \"${keyring:github_token}\",\n        \"OPENAI_API_KEY\": \"${keyring:openai_api_key}\"\n      },\n      \"enabled\": true\n    },\n    {\n      \"name\": \"database-server\",\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"my_db_server\", \"--password\", \"${keyring:database_password}\"],\n      \"protocol\": \"stdio\",\n      \"enabled\": true\n    }\n  ]\n}\n```\n\n**Placeholder expansion works in:**\n- ✅ Environment variables (`env` field)\n- ✅ Command arguments (`args` field)\n- ❌ Server names, commands, URLs (static fields)\n\n### 🏗️ **Secret Storage Architecture**\n\n**Storage Location:**\n- **macOS**: Keychain Access (`/Applications/Utilities/Keychain Access.app`)\n- **Linux**: Secret Service (GNOME Keyring, KDE Wallet, etc.)\n- **Windows**: Windows Credential Manager\n\n**Service Name:** All secrets are stored under the service name `\"mcpproxy\"`\n\n**Global Scope:**\n- ✅ Secrets are **shared across all MCPProxy instances** regardless of:\n  - Configuration file location (`--config` flag)\n  - Data directory (`--data-dir` flag)\n  - Working directory\n- ✅ Same secrets work across different projects and setups\n- ⚠️ **No isolation** - all MCPProxy instances access the same keyring\n\n### 🎯 **Best Practices for Multiple Projects**\n\nIf you use MCPProxy with multiple projects or environments, use descriptive secret names:\n\n```bash\n# Environment-specific secrets\nmcpproxy secrets set prod_database_url\nmcpproxy secrets set dev_database_url\nmcpproxy secrets set staging_api_key\n\n# Project-specific secrets\nmcpproxy secrets set work_github_token\nmcpproxy secrets set personal_github_token\nmcpproxy secrets set client_a_api_key\n```\n\nThen reference them in your configs:\n```jsonc\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"work-github\",\n      \"env\": {\n        \"GITHUB_TOKEN\": \"${keyring:work_github_token}\"\n      }\n    },\n    {\n      \"name\": \"personal-github\",\n      \"env\": {\n        \"GITHUB_TOKEN\": \"${keyring:personal_github_token}\"\n      }\n    }\n  ]\n}\n```\n\n### 🔍 **Security Considerations**\n\n- **Encrypted storage**: Secrets are encrypted by the OS keyring\n- **Process isolation**: Other applications cannot access MCPProxy secrets without appropriate permissions\n- **No file storage**: Secrets are never written to config files or logs\n- **Audit trail**: OS keyring may provide access logs (varies by platform)\n\n### 🐛 **Troubleshooting**\n\n**Secret not found:**\n```bash\n# Verify secret exists\nmcpproxy secrets list\n\n# Check the exact secret name (case-sensitive)\nmcpproxy secrets get your_secret_name\n```\n\n**Keyring access denied:**\n- **macOS**: Grant MCPProxy access in `System Preferences \u003e Security \u0026 Privacy \u003e Privacy \u003e Accessibility`\n- **Linux**: Ensure your desktop session has an active keyring service\n- **Windows**: Run MCPProxy with appropriate user permissions\n\n**Placeholder not resolving:**\n```bash\n# Test secret resolution\nmcpproxy secrets get your_secret_name\n\n# Check logs for secret resolution errors\nmcpproxy serve --log-level=debug\n```\n\n---\n\n## 🐳 Docker Security Isolation\n\nMCPProxy provides **Docker isolation** for stdio MCP servers to enhance security by running each server in its own isolated container:\n\n### ✨ **Key Security Benefits**\n- **Process Isolation**: Each MCP server runs in a separate Docker container\n- **File System Isolation**: Servers cannot access host file system outside their container\n- **Network Isolation**: Configurable network modes for additional security\n- **Resource Limits**: Memory and CPU limits prevent resource exhaustion\n- **Automatic Runtime Detection**: Detects Python, Node.js, Go, Rust environments automatically\n\n### 🔧 **How It Works**\n1. **Runtime Detection**: Automatically detects server type (uvx→Python, npx→Node.js, etc.)\n2. **Container Selection**: Maps to appropriate Docker images with required tools\n3. **Environment Passing**: Passes API keys and config via secure environment variables\n4. **Git Support**: Uses full Docker images with Git for package installations from repositories\n\n### 📝 **Docker Isolation Configuration**\n\nAdd to your `mcp_config.json`:\n\n```jsonc\n{\n  \"docker_isolation\": {\n    \"enabled\": true,\n    \"memory_limit\": \"512m\",\n    \"cpu_limit\": \"1.0\",\n    \"timeout\": \"60s\",\n    \"network_mode\": \"bridge\",\n    \"default_images\": {\n      \"python\": \"python:3.11\",\n      \"uvx\": \"python:3.11\",\n      \"node\": \"node:20\",\n      \"npx\": \"node:20\",\n      \"go\": \"golang:1.21-alpine\"\n    }\n  },\n  \"mcpServers\": [\n    {\n      \"name\": \"isolated-python-server\",\n      \"command\": \"uvx\",\n      \"args\": [\"some-python-package\"],\n      \"env\": {\n        \"API_KEY\": \"your-api-key\"\n      },\n      \"enabled\": true\n      // Docker isolation applied automatically\n    },\n    {\n      \"name\": \"custom-isolation-server\",\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"my_server\"],\n      \"isolation\": {\n        \"enabled\": true,\n        \"image\": \"custom-python:latest\",\n        \"working_dir\": \"/app\"\n      },\n      \"enabled\": true\n    }\n  ]\n}\n```\n\n### 🎯 **Automatic Runtime Detection**\n\n| Command | Detected Runtime | Docker Image |\n|---------|------------------|--------------|\n| `uvx` | Python with UV package manager | `python:3.11` |\n| `npx` | Node.js with npm | `node:20` |\n| `python`, `python3` | Python | `python:3.11` |\n| `node` | Node.js | `node:20` |\n| `go` | Go language | `golang:1.21-alpine` |\n| `cargo` | Rust | `rust:1.75-slim` |\n\n### 🔐 **Security Features**\n\n- **Environment Variables**: API keys and secrets are passed securely to containers\n- **Git Support**: Full images include Git for installing packages from repositories\n- **No Docker-in-Docker**: Existing Docker servers are automatically excluded from isolation\n- **Resource Limits**: Prevents runaway processes from consuming system resources\n- **Network Isolation**: Containers run in isolated network environments\n\n### 🐛 **Docker Isolation Debugging**\n\n```bash\n# Check which servers are using Docker isolation\nmcpproxy serve --log-level=debug --tray=false | grep -i \"docker isolation\"\n\n# Monitor Docker containers created by MCPProxy\ndocker ps --format \"table {{.Names}}\\t{{.Image}}\\t{{.Status}}\"\n\n# View container logs for a specific server\ndocker logs \u003ccontainer-id\u003e\n```\n\n---\n\n## 🔄 Docker Recovery\n\nMCPProxy includes **intelligent Docker recovery** that automatically detects and handles Docker engine outages:\n\n### ✨ **Key Features**\n- **Automatic Detection**: Monitors Docker health every 2-60 seconds with exponential backoff\n- **Graceful Reconnection**: Automatically reconnects all Docker-based servers when Docker recovers\n- **System Notifications**: Native notifications keep you informed of recovery progress\n- **Container Cleanup**: Removes orphaned containers on shutdown\n- **Zero Configuration**: Works out-of-the-box with sensible defaults\n\n### 🔧 **How It Works**\n1. **Health Monitoring**: Continuously checks Docker engine availability\n2. **Failure Detection**: Detects when Docker becomes unavailable (paused, stopped, crashed)\n3. **Exponential Backoff**: Starts with 2-second checks, backs off to 60 seconds to save resources\n4. **Automatic Reconnection**: When Docker recovers, all affected servers are reconnected\n5. **User Notification**: System notifications inform you of recovery status\n\n### 📢 **Notifications**\n\nMCPProxy shows native system notifications during Docker recovery:\n\n| Event | Notification |\n|-------|-------------|\n| **Recovery Started** | \"Docker engine detected offline. Reconnecting servers...\" |\n| **Recovery Success** | \"Successfully reconnected X server(s)\" |\n| **Recovery Failed** | \"Unable to reconnect servers. Check Docker status.\" |\n| **Retry Attempts** | \"Retry attempt X. Next check in Y\" |\n\n### 🐛 **Troubleshooting Docker Recovery**\n\n**Servers don't reconnect after Docker recovery:**\n```bash\n# 1. Check Docker is running\ndocker ps\n\n# 2. Check mcpproxy logs\ncat ~/.mcpproxy/logs/main.log | grep -i \"docker recovery\"\n\n# 3. Verify container labels\ndocker ps -a --filter label=com.mcpproxy.managed\n\n# 4. Force reconnect via system tray\n# System Tray → Force Reconnect All Servers\n```\n\n**Containers not cleaned up on shutdown:**\n```bash\n# Check for orphaned containers\ndocker ps -a --filter label=com.mcpproxy.managed=true\n\n# Manual cleanup if needed\ndocker ps -a --filter label=com.mcpproxy.managed=true -q | xargs docker rm -f\n```\n\n**Docker recovery taking too long:**\n- Docker recovery uses exponential backoff (2s → 60s intervals)\n- This is intentional to avoid wasting resources while Docker is offline\n- You can force an immediate reconnect via the system tray menu\n\n---\n\n## OAuth Authentication Support\n\nMCPProxy provides **seamless OAuth 2.1 authentication** for MCP servers that require user authorization (like Cloudflare AutoRAG, Runlayer, GitHub, etc.):\n\n### ✨ **Key Features**\n- **Zero-Config OAuth**: Automatic detection and configuration for most OAuth servers\n- **RFC 8707 Resource Auto-Detection**: Automatically discovers resource parameters from server metadata\n- **RFC 8252 Compliant**: Dynamic port allocation for secure callback handling\n- **PKCE Security**: Proof Key for Code Exchange for enhanced security\n- **Auto Browser Launch**: Opens your default browser for authentication\n- **Dynamic Client Registration**: Automatic client registration with OAuth servers\n- **Token Management**: Automatic token refresh and storage\n\n### 🔄 **How It Works**\n1. **Add OAuth Server**: Configure an OAuth-enabled MCP server in your config\n2. **Auto Detection**: MCPProxy detects OAuth requirements and auto-configures parameters\n3. **Browser Opens**: Your default browser opens to the OAuth provider's login page\n4. **Dynamic Callback**: MCPProxy starts a local callback server on a random port\n5. **Token Exchange**: Authorization code is automatically exchanged for access tokens\n6. **Ready to Use**: Server becomes available for tool calls immediately\n\n### 📝 **OAuth Configuration Examples**\n\n#### Zero-Config OAuth (Recommended)\n\nFor most OAuth servers (including Runlayer, Cloudflare, etc.), **no OAuth configuration is needed**. MCPProxy automatically:\n- Detects OAuth requirements via 401 responses\n- Discovers Protected Resource Metadata (RFC 9728)\n- Injects the RFC 8707 `resource` parameter automatically\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"runlayer-slack\",\n      \"url\": \"https://oauth.runlayer.com/api/v1/proxy/YOUR-UUID/mcp\"\n    },\n    {\n      \"name\": \"cloudflare_autorag\",\n      \"url\": \"https://autorag.mcp.cloudflare.com/mcp\",\n      \"protocol\": \"streamable-http\"\n    }\n  ]\n}\n```\n\nThat's it - **no `oauth` block needed**. MCPProxy handles everything automatically.\n\n#### Explicit OAuth Configuration\n\nUse explicit configuration when you need to:\n- Customize OAuth scopes\n- Override auto-detected parameters\n- Use pre-registered client credentials\n- Support providers with non-standard requirements\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"github-enterprise\",\n      \"url\": \"https://github.example.com/mcp\",\n      \"protocol\": \"http\",\n      \"oauth\": {\n        \"scopes\": [\"repo\", \"user:email\", \"read:org\"],\n        \"pkce_enabled\": true,\n        \"client_id\": \"your-registered-client-id\",\n        \"extra_params\": {\n          \"resource\": \"https://api.github.example.com\",\n          \"audience\": \"github-enterprise-api\"\n        }\n      }\n    }\n  ]\n}\n```\n\n**OAuth Configuration Options** (all optional):\n- `scopes`: OAuth scopes to request (auto-discovered if not specified)\n- `pkce_enabled`: Enable PKCE for security (default: `true`, recommended)\n- `client_id`: Pre-registered client ID (uses Dynamic Client Registration if empty)\n- `client_secret`: Client secret (optional, for confidential clients)\n- `extra_params`: Additional OAuth parameters (override auto-detected values)\n\n### 🔍 **OAuth Diagnostics**\n\nCheck OAuth status and auto-detected parameters:\n```bash\n# View OAuth status for a specific server\nmcpproxy auth status --server=runlayer-slack\n\n# View all OAuth-enabled servers\nmcpproxy auth status --all\n\n# Run health diagnostics including OAuth issues\nmcpproxy doctor\n```\n\n### 🔧 **OAuth Debugging**\n\nEnable debug logging to see the complete OAuth flow:\n\n```bash\nmcpproxy serve --log-level=debug --tray=false\n```\n\nCheck logs for OAuth flow details:\n```bash\ntail -f ~/Library/Logs/mcpproxy/main.log | grep -E \"(oauth|OAuth)\"\n```\n\n### 📂 **Working Directory Configuration**\n\nSolve project context issues by specifying working directories for stdio MCP servers:\n\n```jsonc\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"ast-grep-project-a\",\n      \"command\": \"npx\",\n      \"args\": [\"ast-grep-mcp\"],\n      \"working_dir\": \"/home/user/projects/project-a\",\n      \"enabled\": true\n    },\n    {\n      \"name\": \"git-work-repo\",\n      \"command\": \"npx\",\n      \"args\": [\"@modelcontextprotocol/server-git\"],\n      \"working_dir\": \"/home/user/work/company-repo\",\n      \"enabled\": true\n    }\n  ]\n}\n```\n\n**Benefits**:\n- **Project isolation**: File-based servers operate in correct directory context\n- **Multiple projects**: Same MCP server type for different projects\n- **Context separation**: Work and personal project isolation\n\n**Tool-based Management**:\n```bash\n# Add server with working directory\nmcpproxy call tool --tool-name=upstream_servers \\\n  --json_args='{\"operation\":\"add\",\"name\":\"git-myproject\",\"command\":\"npx\",\"args_json\":\"[\\\"@modelcontextprotocol/server-git\\\"]\",\"working_dir\":\"/home/user/projects/myproject\",\"enabled\":true}'\n\n# Update existing server working directory\nmcpproxy call tool --tool-name=upstream_servers \\\n  --json_args='{\"operation\":\"update\",\"name\":\"git-myproject\",\"working_dir\":\"/new/project/path\"}'\n```\n\n## 🔐 Optional HTTPS Setup\n\nMCPProxy works with HTTP by default for easy setup. HTTPS is optional and primarily useful for production environments or when stricter security is required.\n\n**💡 Note**: Most users can stick with HTTP (the default) as it works perfectly with all supported clients including Claude Desktop, Cursor, and VS Code.\n\n### Quick HTTPS Setup\n\n**1. Enable HTTPS** (choose one method):\n```bash\n# Method 1: Environment variable\nexport MCPPROXY_TLS_ENABLED=true\nmcpproxy serve\n\n# Method 2: Config file\n# Edit ~/.mcpproxy/mcp_config.json and set \"tls.enabled\": true\n```\n\n**2. Trust the certificate** (one-time setup):\n```bash\nmcpproxy trust-cert\n```\n\n**3. Use HTTPS URLs**:\n- MCP endpoint: `https://localhost:8080/mcp`\n- Web UI: `https://localhost:8080/ui/`\n\n### Claude Desktop Integration\n\nFor Claude Desktop, add this to your `claude_desktop_config.json`:\n\n**HTTP (Default - Recommended):**\n```json\n{\n  \"mcpServers\": {\n    \"mcpproxy\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"http://localhost:8080/mcp\"\n      ]\n    }\n  }\n}\n```\n\n**HTTPS (With Certificate Trust):**\n```json\n{\n  \"mcpServers\": {\n    \"mcpproxy\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://localhost:8080/mcp\"\n      ],\n      \"env\": {\n        \"NODE_EXTRA_CA_CERTS\": \"~/.mcpproxy/certs/ca.pem\"\n      }\n    }\n  }\n}\n```\n\n### Certificate Management\n\n- **Automatic generation**: Certificates created on first HTTPS startup\n- **Multi-domain support**: Works with `localhost`, `127.0.0.1`, `::1`\n- **Trust installation**: Use `mcpproxy trust-cert` to add to system keychain\n- **Certificate location**: `~/.mcpproxy/certs/` (ca.pem, server.pem, server-key.pem)\n\n### Troubleshooting HTTPS\n\n**Certificate trust issues**:\n```bash\n# Re-trust certificate\nmcpproxy trust-cert --force\n\n# Check certificate location\nls ~/.mcpproxy/certs/\n\n# Test HTTPS connection\ncurl -k https://localhost:8080/api/v1/status\n```\n\n**Claude Desktop connection issues**:\n- Ensure `NODE_EXTRA_CA_CERTS` points to the correct ca.pem file\n- Restart Claude Desktop after config changes\n- Verify HTTPS is enabled: `mcpproxy serve --log-level=debug`\n\n## Learn More\n\n* Documentation: [Configuration](https://mcpproxy.app/docs/configuration), [Features](https://mcpproxy.app/docs/features), [Usage](https://mcpproxy.app/docs/usage)\n* Website: \u003chttps://mcpproxy.app\u003e\n* Releases: \u003chttps://github.com/smart-mcp-proxy/mcpproxy-go/releases\u003e\n\n## Contributing\n\nWe welcome issues, feature ideas, and PRs!\n\n### Development Setup\n\n```bash\nmake dev-setup                # Install swag, frontend deps, Playwright\nbrew install prek             # Install pre-commit hook runner (or: uv tool install prek)\nprek install                  # Install pre-commit hooks\nprek install --hook-type pre-push  # Install pre-push hooks\n```\n\n### Pre-commit Hooks\n\nWe use [prek](https://github.com/j178/prek) to catch issues before they reach CI:\n\n| Hook | Stage | What it does |\n|------|-------|-------------|\n| `gofmt` | pre-commit | Auto-formats staged Go files |\n| `trailing-whitespace` | pre-commit | Removes trailing whitespace |\n| `end-of-file-fixer` | pre-commit | Ensures files end with newline |\n| `check-merge-conflict` | pre-commit | Detects merge conflict markers |\n| `swagger-verify` | pre-push | Fails if OpenAPI spec is out of date |\n| `go-build` | pre-push | Verifies the project compiles |\n\nRun hooks manually: `prek run --all-files`\n\n### Build \u0026 Test\n\n```bash\nmake build          # Build frontend + backend\nmake swagger        # Regenerate OpenAPI spec\nmake test           # Unit tests\nmake test-e2e       # E2E tests\nmake lint           # Run linters\n```\n","funding_links":[],"categories":["Aggregators \u0026 Gateways","Open-source MCP Gateways","Go","📦 Other","📚 Projects (2474 total)","Utilities","CI/CD \u0026 DevOps Pipelines","Gateways \u0026 Proxies"],"sub_categories":["Gateways \u0026 Proxies","MCP Servers","Proxies and Gateways","🔗 Aggregators"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmart-mcp-proxy%2Fmcpproxy-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmart-mcp-proxy%2Fmcpproxy-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmart-mcp-proxy%2Fmcpproxy-go/lists"}