MCPProxy.app: Supercharge AI Agents, Safely

📺 观看完整演示  ·  📚 阅读文档  ·  🌐 mcpproxy.app

上方演示展示的是内嵌式 Web UI。MCPProxy 核心是适用于 macOS、Linux 和 Windows 的单个二进制文件——Web UI 内置其中，无需运行额外服务。在 macOS 上，可选的菜单栏应用提供一键便捷操作（启动/停止、服务健康状况、隔离区、日志）。

## 为什么选择 MCPProxy？

• 突破 API 限制 – 联合数百个 MCP 服务，同时绕过 Cursor 的 40 个工具限制和 OpenAI 的 128 个函数上限。
• 减少工具定义占用的上下文 – Agent 只会看到一小组 MCPProxy 发现和执行工具（retrieve_tools、describe_tool、call_tool_* 各变体以及少数管理工具），而不是完整的上游工具目录，并按需获取架构（通过 retrieve_tools 和 code_execution 路由；direct 路由会逐个公开上游工具，详见路由模式）。具体能节省多少上下文取决于工具数量、路由模式、客户端和任务；详见Token 节省：测量与未测量的内容。
• 使用前审核 – 新服务会被隔离，其工具在你审核并批准前不会提供给 Agent；在默认的 manual 信任模式下，已批准工具定义的大多数后续更改也会再次暂缓，等待审核。已知例外：在 scan 模式之外，仅修改输入架构、新增输出架构，以及为获批时描述为空的工具添加描述，均不会暂缓；scan 模式会放行干净的更改，也会漏掉其检测器无法发现的更改；auto 模式不会暂缓更改。这能减少恶意工具定义（工具投毒攻击）带来的风险，但不能保证安全。详见隔离的作用范围。
• 可插拔安全扫描器 – 在批准隔离的服务前，可使用 Snyk、Semgrep、Trivy、Cisco 和其他基于 Docker 的扫描器对其进行扫描；扫描结果会统一为 SARIF 格式，并附带综合风险评分。详见安全扫描器插件。
• 支持离线运行且跨平台 – 单个核心二进制文件支持 macOS（Intel 和 Apple Silicon）、Windows（x64 和 ARM64）及 Linux（x64 和 ARM64），并内嵌 Web UI。macOS 另提供可选的菜单栏应用。

Token 节省：测量与未测量的内容

按需发现可减少 Agent 启动时加载到上下文中的上游工具定义数量。节省幅度并非固定百分比：连接的工具越多，节省通常越多；具体幅度取决于路由模式、客户端和任务。MCPProxy 不会公布一个醒目的 Token 减少或准确率提升数据，也不对延迟作出任何承诺。

本仓库实际测量的是一项第一方、确定性估算（测量方法及如何通过 go run ./bench/cmd/bench 复现，请参阅 bench/README.md）：

• 语料：冻结的 45 个工具参考语料；仅统计工具名称和描述（不含输入架构），使用 cl100k_base。
• 指标：初始工具菜单的 Token 数量，包括代理自身的发现、调用和管理工具。不包括整个工作流的 Token 数量、延迟或任务成功率。
• 结果：在这份包含 45 个工具的语料中，代理的初始菜单比列出所有上游工具更大（retrieve_tools 模式为 2625 个 Token，code_execution 模式为 1874 个 Token，基准值为 1730 个 Token），因为代理自身的工具会产生固定开销。只有上游工具数量超过盈亏平衡点后才会节省，因此引用百分比时应同时注明工具数量。

---

快速入门

1. 安装

macOS（推荐 — DMG 安装程序）：

下载适用于你的架构的最新 DMG 安装程序：

• Apple Silicon（M1/M2）： 下载 DMG → mcpproxy-*-darwin-arm64.dmg
• Intel Mac： 下载 DMG → mcpproxy-*-darwin-amd64.dmg

Windows（推荐 — 安装程序）：

下载适用于你的架构的最新 Windows 安装程序：

• x64（64 位）： 下载安装程序 → mcpproxy-setup-*-amd64.exe
• ARM64： 下载安装程序 → mcpproxy-setup-*-arm64.exe

安装程序会自动：

• 将 mcpproxy.exe（核心服务）和 mcpproxy-tray.exe（系统托盘应用）安装到 Program Files
• 将 MCPProxy 添加到系统 PATH，以便通过命令行访问
• 创建开始菜单快捷方式
• 支持静默安装：.\mcpproxy-setup.exe /VERYSILENT

其他安装方式：

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

cask 会安装菜单栏应用（内置 CLI）；formula 仅安装 CLI 二进制文件。两者均可通过 brew upgrade 更新。

Linux（Debian/Ubuntu）— apt 仓库，可通过 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 仓库，可通过 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

apt 和 dnf 软件包提供经过强化的 systemd 单元，并会自动启动服务。仓库签名密钥指纹：3B6F A1AD 5D53 59DA 51F1 8DDC E1B5 9B9B A1CB 8A3B。

如需一次性下载 .deb / .rpm 文件（用于隔离网络环境中的安装），请从最新版本获取。

手动下载（所有平台）：

• Linux 压缩包：AMD64 | ARM64
• Windows：AMD64 | ARM64

预发布版本（最新功能）：

想体验最新功能？可从 next 分支下载预发布版本：

1. 前往 GitHub Actions
2. 点击最新一次成功运行的“Prerelease”工作流
3. 从构件中下载：
   • dmg-darwin-arm64（Apple Silicon Mac）
   • dmg-darwin-amd64（Intel Mac）
   • versioned-linux-amd64、versioned-windows-amd64（其他平台）

注意：预发布版本已签名并经过 macOS 公证，但包含可能不稳定的前沿功能。

• macOS：Intel | Apple Silicon

适用于任何安装了 Go 1.26+ 的环境：

go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest

2. 运行

mcpproxy serve          # starts HTTP server on :8080 and shows tray

3. 添加第一个服务并批准它

新服务会先进入隔离区，等待你审核，因此添加服务分为两个步骤：添加，然后审核并批准。完整演练以真实的远程服务 Context7 为例，详见已发布的快速入门。简而言之（Context7 是一个公开的只读文档服务；你也可以换成任何自己信任的服务）：

# 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

扫描结果正常并不代表服务安全；这只意味着离线检查未在工具定义中发现问题。请仔细审核要批准的内容。

你也可以手动编辑 ~/.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 }
  ]
}

完整参考资料请参阅配置和上游服务，了解审核关卡的作用及其不涵盖的内容，请参阅安全隔离区。

4. 连接到 IDE/AI 工具

📖 完整设置指南 - Cursor、VS Code、Claude Desktop 和 Goose 的详细说明

将代理添加到 Cursor

一键安装到 Cursor IDE

手动安装

1. 打开 Cursor 设置
2. 点击“工具与集成”
3. 添加 MCP 服务

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

---

AI Agent 如何通过 MCPProxy 工作

连接后，你的 Agent 看到的是少量内置的 MCPProxy 工具，而不是数百个上游架构。典型会话分为三个阶段——发现、调用、审计——此外，无人值守自动化还可选择启用预检关卡。

1. 发现——只用一次查询，不占用上下文窗口

Agent 通过 retrieve_tools 使用简单关键词查询所需内容：

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

MCPProxy 会对所有已连接服务执行 BM25 搜索，并仅返回排名最高的匹配项——每项都附带 call_with 提示，根据工具注释推荐合适的调用变体：

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

这正是节省令牌的原因：Agent 不需要的数百个工具架构不会进入其上下文。Agent 只会在需要使用工具时，通过 describe_tool 按需加载完整架构（每批最多 5 个 ID）。

2. 调用——声明调用意图

Agent 使用与其意图匹配的变体（call_tool_read、call_tool_write 或 call_tool_destructive）执行工具，并以 server:tool 的形式指定目标：

{
  "name": "github:create_issue",
  "args": { "repo": "acme/api", "title": "Bug report" },
  "intent_reason": "Filing bug per user request"
}

MCPProxy 会根据工具注释验证调用意图（“读取”调用无法调用破坏性工具），并在转发调用前检查隔离和批准状态。敏感数据检测会在活动日志中标记参数和响应中可能存在的机密信息；默认情况下不会阻止调用。可选的输出清理功能可以在转发前，对受支持的文本响应中检测到的机密信息进行脱敏，或阻止严重级别的检测结果。该功能不涵盖工具参数、非文本内容、直接路由模式或上游错误响应。

3. 审计——每次调用都有记录

调用会记录在本地活动日志中，并附带请求 ID，方便你检查 Agent 执行的操作。日志受可配置的保留策略（按时间、记录数量和大小）以及单条响应大小上限约束，因此它是检查和调试辅助工具，并非合规保证：

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

在自动化任务耗尽令牌前进行检查

对于定期运行的无头任务（cron、CI、n8n），别让 Agent 以昂贵的方式发现缺少工具。只需运行一条预检命令，即可检查所有必需工具是否就绪——不会联系任何上游服务；若未就绪，还会准确说明原因（服务已隔离、工具在获批后发生变化、OAuth 已过期、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

完整的原因分类、REST 端点以及 GitHub Actions / n8n 配方，请参阅 必需工具预检。

---

🔐 可选的 HTTPS 设置

MCPProxy 默认使用 HTTP，便于快速设置。HTTPS 为可选项，主要适用于生产环境或需要更严格安全性的场景。

💡 注意：大多数用户使用 HTTP（默认选项）即可，它与所有受支持的客户端（包括 Claude Desktop、Cursor 和 VS Code）配合良好。

HTTPS 快速设置

1. 启用 HTTPS（选择一种方法）：

# 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. 信任证书（一次性设置）：

mcpproxy trust-cert

3. 使用 HTTPS URL：

• MCP 端点：https://localhost:8080/mcp
• Web UI：https://localhost:8080/ui/

Claude Desktop 集成

对于 Claude Desktop，请将以下内容添加到 claude_desktop_config.json：

HTTP（默认 — 推荐）：

{
  "mcpServers": {
    "mcpproxy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8080/mcp"
      ]
    }
  }
}

HTTPS（信任证书后）：

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

证书管理

• 自动生成：首次启动 HTTPS 时创建证书
• 多域名支持：适用于 localhost、127.0.0.1、::1
• 安装信任证书：使用 mcpproxy trust-cert 将证书添加到系统密钥链
• 证书位置：~/.mcpproxy/certs/（ca.pem、server.pem、server-key.pem）

HTTPS 故障排除

证书信任问题：

# 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 连接问题：

• 确保 NODE_EXTRA_CA_CERTS 指向正确的 ca.pem 文件
• 更改配置后重启 Claude Desktop
• 确认已启用 HTTPS：mcpproxy serve --log-level=debug

---

文档

入门

• 安装
• 快速入门

配置

• 配置文件参考
• 上游服务
• 环境变量

功能

• 搜索与工具发现
• 安全隔离
• 安全扫描器插件
• Docker 安全隔离
• 密钥与密钥链集成
• OAuth 身份验证
• 代码执行
• 活动日志
• 必需工具预检
• Agent 令牌
• 敏感数据检测

CLI 参考

• 命令参考
• 管理命令
• 活动命令
• 安全命令

API

• REST API
• MCP 协议

---

参与贡献

欢迎提交问题、功能创意和 PR！

开发环境设置

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

提交前钩子

我们使用 prek 在问题进入 CI 前进行检查：

钩子	阶段	功能
gofmt	pre-commit	自动格式化已暂存的 Go 文件
trailing-whitespace	pre-commit	删除行尾空白
end-of-file-fixer	pre-commit	确保文件以换行符结尾
check-merge-conflict	pre-commit	检测合并冲突标记
swagger-verify	pre-push	如果 OpenAPI 规范不是最新版本，则失败
go-build	pre-push	验证项目能否编译

手动运行钩子：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