FetchSandbox

fetchsandbox-mcp

也可在 Smithery、npm 和 官方 MCP 注册表 上找到。

面向 Agent 的确定性验证引擎，以 FetchSandbox 的 MCP 服务形式提供。

你的 Agent 编写集成代码。此工具会在一个行为仿真真实服务提供商的沙盒中检查代码是否真正可用，包括各种故障：重试的 Webhook、被拒绝的银行卡、速率限制和身份验证错误。

发现 Bug 后，它可以提出修复方案并验证修复是否有效：在应用代码差异前后，针对你的代码运行相同的故障。只有在故障先被复现、之后又不再出现时，结果才会显示为绿色。无论结果如何，你都会获得一个凭证 URL。

安装

MCP 服务通过 Node.js 在本地运行。不同客户端解析 npx 的方式可能有所不同；在 Mac 上使用 Cursor 时，可能需要使用 command -v npx 获取完整路径。

{
  "mcpServers": {
    "fetchsandbox": {
      "command": "npx",
      "args": ["-y", "fetchsandbox-mcp@latest"],
      "env": { "FETCHSANDBOX_API_KEY": "fsk_your_key_here" }
    }
  }
}

无需密钥即可使用发现和参考工具。应用规划、验证和托管式本地隧道功能需要登录，或提供 API 密钥，获取地址为 **https://fetchsandbox.com/keys**。 请参阅账号。

客户端	文件
Claude Code	项目根目录中的 .mcp.json，或运行 claude mcp add
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	~/.cursor/mcp.json，或仓库中的 .cursor/mcp.json
Zed	~/.config/zed/settings.json 中的 context_servers 项
Codex	~/.codex/config.toml 中的 [mcp_servers.fetchsandbox] 项

Mac 上的 Cursor：经过测试的设置

从 https://fetchsandbox.com/keys 获取真实账号密钥。运行 command -v npx 并在 ~/.cursor/mcp.json 中使用完整路径。此示例适用于 Apple Silicon 上的 Homebrew；如果你的路径不同，请替换为自己的路径。在 Windows 上，使用 where.exe npx 查找已安装命令的位置。

{
  "mcpServers": {
    "fetchsandbox": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "[email protected]"],
      "env": { "FETCHSANDBOX_API_KEY": "fsk_your_key_here" }
    }
  }
}

请在本地将 fsk_your_key_here 替换为真实的原始密钥，不要加 Bearer 前缀。占位符无法通过身份验证。检查项目中的 .cursor/mcp.json 是否还有第二个 FetchSandbox 条目。保存后，完全退出并重新打开 Cursor；重新加载窗口可能会保留旧的 MCP 进程。根据需要启用该服务，并确认其工具已加载。连接状态显示绿色，并不能证明应用验证调用已通过身份验证。

之后重启客户端。其他所有支持 MCP 的程序也使用相同的命令和参数。

没有终端？使用托管端点

基于浏览器的构建工具——Lovable、Bolt、v0——无法运行 npx。它们可以直接连接到托管的可流式 HTTP 传输端点：

https://fetchsandbox.com/mcp/v1

请使用 Bearer 令牌进行身份验证，而不是“None”——粘贴从 https://fetchsandbox.com/keys 获取的密钥。

相同的双胞胎、相同的场景、七种工具：validate_integration、quickrun、run_workflow、verify_behavior、list_workflows、guide、coach。

其余工具并未隐藏——它们无法在此处运行。find_bugs、fix_bug 和 prove_fix 会读取磁盘上的项目文件，而托管服务没有这些文件的副本，因此宣传这些工具只会让会话无法继续。要分析自己的代码，请在你希望检查的项目目录中本地运行 npx fetchsandbox-mcp。

从 validate_integration 开始。绿色的 quickrun 只能证明服务提供商的行为符合文档；它不会触及你的结账端点、Webhook 处理程序或邮件发送功能。validate_integration 会为每个服务提供商提供一个全新的双胞胎，然后报告你的代码实际调用了什么。

使用方法

像向同事描述问题那样描述即可，无需指定工具。

客户反馈，Paddle 付款后获得的席位数比购买的多。 能查明原因吗？

Agent 会依次处理：判断症状对应的路由、在服务商沙盒中复现问题、读取你的代码、获取修复方案，并在你的代码上验证修复。每一步都会交接下一步所需的内容。

有一点值得注意，因为很容易弄反：prove_fix 需要的是未修复的代码树。请在将差异写入磁盘之前运行它，否则就没有 bug 可供复现，也无法进行验证。

账户

开始使用无需账户。安装后提出问题即可，一切都会自动运行。

首次运行生成值得保留的内容（例如回执或一组发现）时，你会收到一个简短代码和一个链接。登录大约需要 20 秒，并会完成两件事：回执背后的证据不再于 15 天后归档，而且这台设备上的运行记录会汇集到一处。系统每天最多询问一次，登录后则不会再询问。

对于 CI、托管端点或无法使用浏览器的场景，请改为设置密钥。前往 https://fetchsandbox.com/keys 创建密钥——登录后点击“Create a key”。密钥格式类似 fsk_...。

在 MCP 客户端配置中，将其放入 env：

"env": { "FETCHSANDBOX_API_KEY": "fsk_your_key_here" }

在 Shell 或 CI 中：

export FETCHSANDBOX_API_KEY=fsk_your_key_here

使用托管端点时，请通过 Authorization: Bearer fsk_... 发送密钥。

从编辑器登录时，密钥也会写入 ~/.fetchsandbox/credentials.json；环境变量始终优先。

工具

从 guide 开始。它会根据你的需求选择合适的工具。

查找和修复

工具	功能	参数
guide	将问题症状路由到规范、工作流和已知故障类别	intent*, hints
find_bugs	根据已知集成故障类别审查你的项目。无需 git 远程仓库——它会读取你指定的目录	path, spec, timeout_s
fix_bug	为一项发现返回 git diff。不会修改你的文件	bug*, fix_pattern, path, spec, timeout_s
get_job	获取同一个正在运行的作业，不会启动另一项分析或验证	job_id*
prove_fix	在应用 diff 前后，针对你的代码运行故障。只有经过测量确认结果发生翻转才会显示绿色	diff*, bug, scenario, sandbox_id, path, timeout_s

验证集成

工具	功能	参数
validate_integration	针对提供方验证你自己的代码，而不是验证我们的孪生实例是否正常。它会为每个提供方生成一个全新的孪生实例，然后读取我们的请求日志，报告你的应用实际调用了什么	providers, app_base_url, session_id
quickrun	针对捆绑的规范运行一项由我们整理的工作流。在此处显示绿色表示提供方的行为符合文档说明——这并不说明你的集成没有问题	spec_slug*, workflow_name*, scenario
run_workflow	同上，但在你已有的沙盒中运行——你可以在这里启用 scenario 后重新运行	sandbox_id*, workflow_name*, scenario
verify_behavior	在参考处理程序上展示故障类别——有缺陷与已修复的对比。不是针对你的代码	bug_pattern_id*, prompt, sandbox_id, flow_run_id
list_workflows	在一次响应中列出工作流以及规范可注入的故障场景	spec_slug or spec_id
guide	将问题症状路由到能解释该症状的提供方行为，并返回已填好参数的下一次调用	intent*, hints
coach	通过多轮交互帮助你构建集成	intent, session_id, user_response, context

这七种工具涵盖了基于浏览器的构建者可见的全部工具，也是唯一无需文件系统的工具。以下所有工具都需要本地项目。

在有代码的计算机上

工具	功能	参数
find_bugs	根据已知集成故障类别审查你的项目	path, spec, timeout_s
fix_bug	为一项发现返回 git diff。不会修改你的文件	bug*, fix_pattern, path, spec, timeout_s
get_job	获取同一个正在运行的作业，不会启动另一项分析或验证	job_id*
prove_fix	在应用 diff 前后，针对你的代码运行故障。只有经过测量确认结果发生翻转才会显示绿色	diff*, bug, scenario, sandbox_id, path, timeout_s
run_all_workflows	在一次调用中运行多个工作流	sandbox_id*, workflow_names
list_scenarios	列出规范可注入的故障	sandbox_id*
set_scenario	在沙盒中启用一个故障	sandbox_id*, scenario*
list_runs	列出沙盒的过往运行记录	sandbox_id*, limit
list_specs	列出已可用的规范	filter
submit_proof	为一次运行发布凭证	sandbox_id, flow_run_id, bug_pattern_id, summary, proofs

* = 必填。

会离开你设备的内容

find_bugs、fix_bug 和 prove_fix 会打包你指定的目录，并上传以供分析。这里有必要明确说明，因为之前的措辞让人误以为并非如此。

打包前会排除：.git、node_modules 和构建产物、Agent 指令文件，以及任何看起来像凭据的内容——.env*、*.pem、*.key、id_rsa*、*.tfstate、.npmrc、.aws、.ssh、.mcp.json、.mcp.*.json、mcp.json 等。

随后会重新读取压缩包；如果其中仍包含任何看起来像有效凭据的内容，无论它位于何处、名称是什么，都会拒绝上传。例如，config/local.yml 中的密钥会导致上传停止，并指出相应文件。匹配模式只能涵盖人们想到的情况；扫描就是为处理其余情况而设。

如果你希望完全不上传任何内容，那么目前分析就需要源代码。这就是实际情况。

长时间运行的任务

MCP 响应会短暂等待，然后返回 status: running、其 job_id 和一个指向 get_job 的 next_tool_call。持续跟进该调用，直到 status: done 或 error。它会读取现有的后端任务；不会再次上传项目，也不会启动另一项验证。在验证运行期间，请保持原始目录树不变。任务正在运行并不代表验证通过。

这适用于问题发现、拟议修复、应用验证和异步参考验证。直接调用库仍保持阻塞行为。任务保留和归属仍由现有后端负责。此更改不会让后端的内存任务跟踪器在后端重启后继续保留。

任何持有链接的人都能查看回执

submit_proof 会将应用运行前后的真实请求和响应附加到回执页面，因此回执会显示你代码自身的行为。该页面无需登录即可访问——这正是它的用途：你可以把链接放进 PR——这意味着任何持有链接的人都能读取其中的请求和响应正文。

提供方执行可以使用 FetchSandbox 双胞胎或录制测试替身；请查看回执中的执行范围。录制替身不能证明与双胞胎或真实提供方一致。但请求正文确实是由你的应用构建的，其中可能包含配置中的值。分享回执前，请先查看。

配置

环境变量	默认值	用途
FETCHSANDBOX_API_KEY	无	无需浏览器即可登录。优先于已存储的凭据
FETCHSANDBOX_BASE_URL	https://fetchsandbox.com	指向其他后端
FETCHSANDBOX_TELEMETRY	开启	设为 0 以关闭

遥测会记录一个不透明的每台设备 ID（~/.fetchsandbox/session.json 中的随机 UUID）、工具名称、延迟，以及调用是否成功。不会记录规范内容、请求正文或凭据。我们借此统计会话数量，并了解大家使用哪些 API。

登录后，调用也会关联到你的账户——这正是登录的目的，也让你的运行记录能够集中显示在一个地方。

FETCHSANDBOX_TELEMETRY=0 会阻止发送每台设备的 ID，因此调用不再与该设备关联。这并不意味着调用不可见：服务器仍会记录工具运行过，因为它就是执行工具的服务器。如果你已登录，你的密钥仍会识别出你——密钥的作用正是如此。若不想被关联，请不要登录。

许可证

MIT — 参见 LICENSE。

• fetchsandbox.com
• 源代码 · 问题反馈

无需 ngrok 验证本地应用

0.7.13 版将 manage_tunnel 添加到了本地 MCP 包。启动实际的隔离应用，开放其环回端口，并将返回的 app_base_url 传给 validate_integration。在 application_config.event_destinations 中声明现有应用的 webhook 路径。FetchSandbox 会对提供方原生事件进行签名，并通过现有应用运行器独立检查已保存的状态。通过受保护的交接配置测试密钥，执行预检，只执行一次，然后获取同一运行回执。关闭连接，并在之后移除临时设置。仅连通并不代表测试通过。

需要能够通过出站 HTTPS 访问 fetchsandbox.com、运行中的本地 MCP 进程和真实的本地应用。无需配置入站防火墙规则，也无需单独安装隧道。受限网络可能需要使用经批准的代理/CA 配置。Node 22.21+ 或 24.5+ 支持搭配 HTTPS_PROXY 和 NO_PROXY 使用 NODE_USE_ENV_PROXY=1；请将 127.0.0.1/localhost 加入 NO_PROXY，并使用 NODE_EXTRA_CA_CERTS 配置经批准的企业 CA。较旧的 Node 版本不自动支持此代理设置。请勿禁用 TLS 证书验证。企业防火墙仍可能阻止连接。租约会在 30 分钟后或服务重启后过期；不确定是否成功的写入不会自动重试。

用于本地应用验证的私有凭据（0.7.14）

配置好自有应用的运行后，Cursor、Claude Code 和其他本地 MCP 客户端会使用其会话 ID 和运行 ID 调用 install_test_credentials。 现有 FetchSandbox 账户密钥用于授权获取凭据。临时提供方密钥、 webhook 密钥和验证器令牌会写入 ~/.fetchsandbox/handoffs/ 下的新私有 dotenv 文件（目录权限为 0700，文件权限为 0600），且位于 项目目录之外。工具结果中只会包含文件路径和变量名。env_mapping 会明确将返回的变量名映射到真实应用的环境设置。

使用一次性应用的 dotenv 加载器加载该文件，且不要打印文件内容。配置返回的 孪生环境基础 URL，重启应用，执行预检，只执行一次，然后获取同一回执。测试后 删除临时文件。文件不会自动删除，且这些凭据不能用于生产环境。切勿将 凭据值粘贴到聊天、源代码、日志或命令参数中。Replit/Lovable 保留 现有的所有者浏览器交接方式和原生密钥管理器。此更改不会通过本地中继转发 prove_fix。