# fetchsandbox-mcp FetchSandbox MCP - The MCP that proves your AI's integration fixes work | Product Hunt Also on [Smithery](https://smithery.ai/servers/fetchsandbox/mcp), [npm](https://www.npmjs.com/package/fetchsandbox-mcp) and the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=fetchsandbox). A deterministic verification engine for agents, as an MCP server for [FetchSandbox](https://fetchsandbox.com). Your agent writes an integration. This checks whether it actually works — against a sandbox that behaves like the real provider, including the failures: retried webhooks, declined cards, rate limits, auth errors. When it finds a bug, it can propose a fix and then prove it: the same failure is run against your code before and after the diff. Green only if it reproduced first and stopped after. You get a receipt URL either way. ## Install Same stdio command everywhere. `npx` fetches the current version, so there's nothing to install. ```json { "mcpServers": { "fetchsandbox": { "command": "npx", "args": ["-y", "fetchsandbox-mcp@latest"], "env": { "FETCHSANDBOX_API_KEY": "fsk_your_key_here" } } } } ``` The key is optional — leave `env` out and everything still runs. Get one at **https://fetchsandbox.com/keys** when you want receipts that outlive 15 days. See [Accounts](#accounts). | Client | File | |---|---| | Claude Code | `.mcp.json` in your project root, or `claude mcp add` | | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Cursor | `~/.cursor/mcp.json`, or `.cursor/mcp.json` in the repo | | Zed | `~/.config/zed/settings.json`, under `context_servers` | | Codex | `~/.codex/config.toml`, as `[mcp_servers.fetchsandbox]` | Restart the client afterwards. Anything else that speaks MCP takes the same command and args. ### No terminal? Use the hosted endpoint Browser-based builders — Lovable, Bolt, v0 — can't run `npx`. They connect straight to the hosted streamable-HTTP transport instead: ``` https://fetchsandbox.com/mcp/v1 ``` Authenticate with a **Bearer token**, not "None" — paste the key from https://fetchsandbox.com/keys. Same twins, same scenarios, seven tools: `validate_integration`, `quickrun`, `run_workflow`, `verify_behavior`, `list_workflows`, `guide`, `coach`. The rest are not hidden — they cannot work there. `find_bugs`, `fix_bug` and `prove_fix` read your project from disk and a hosted server has no copy of it, so advertising them only produced sessions that dead-ended. To analyse your own code, run `npx fetchsandbox-mcp` locally in the project you want looked at. Start with `validate_integration`. A green `quickrun` proves the provider behaves as documented; it does not touch your checkout endpoint, your webhook handler, or your email send. `validate_integration` hands you a fresh twin per provider and then reports what **your** code actually called. ## Using it Describe the problem the way you'd describe it to a colleague. You don't need to name a tool. > Customers are reporting more seats than they bought after a Paddle payment. > Can you find out why? The agent works through: route the symptom, reproduce it against the provider sandbox, read your code, get a fix, prove the fix on your code. Each step hands back what the next one needs. One thing worth knowing, because it's easy to get backwards: `prove_fix` needs the **unfixed** tree. Run it before you write the diff to disk, or there's no bug left to reproduce and no proof to be had. ## Accounts You don't need one to start. Install it, ask a question, and everything runs. The first time a run produces something worth keeping — a receipt, or a set of findings — you'll get a short code and a link. Signing in takes about twenty seconds and does two things: the evidence behind your receipts stops being archived after 15 days, and the runs from that machine collect in one place. You'll be asked at most once a day, and never once you're signed in. For CI, the hosted endpoint, or anywhere a browser isn't available, set a key instead. Create one at **https://fetchsandbox.com/keys** — sign in, then "Create a key". It looks like `fsk_...`. In an MCP client config, it goes in `env`: ```json "env": { "FETCHSANDBOX_API_KEY": "fsk_your_key_here" } ``` In a shell or CI: ``` export FETCHSANDBOX_API_KEY=fsk_your_key_here ``` On the hosted endpoint, send it as `Authorization: Bearer fsk_...`. The key is also written to `~/.fetchsandbox/credentials.json` when you sign in from an editor; the environment variable always wins. ## Tools Start with `guide`. It picks the right ones for what you asked. **Finding and fixing** | Tool | What it does | Arguments | |---|---|---| | `guide` | Routes a symptom to a spec, workflow and known failure class | `intent*`, `hints` | | `find_bugs` | Audits your project against known integration failure classes. No git remote needed — it reads the directory you point it at | `path`, `spec`, `timeout_s` | | `fix_bug` | Returns a `git diff` for one finding. Doesn't touch your files | `bug*`, `fix_pattern`, `path`, `spec`, `timeout_s` | | `prove_fix` | Runs the failure against your code before and after the diff. Green only on a measured flip | `diff*`, `bug`, `scenario`, `sandbox_id`, `path`, `timeout_s` | **Verifying an integration** | Tool | What it does | Arguments | |---|---|---| | `validate_integration` | Proves **your own code** against a provider, not that our twin works. Hands back a fresh twin per provider, then reads our request log to report what your app actually called | `providers`, `app_base_url`, `session_id` | | `quickrun` | Runs one of OUR curated workflows against a bundled spec. Green here says the provider behaves as documented — it says nothing about your integration | `spec_slug*`, `workflow_name*`, `scenario` | | `run_workflow` | The same, on a sandbox you already have — this is where you re-run with a `scenario` armed | `sandbox_id*`, `workflow_name*`, `scenario` | | `verify_behavior` | Shows a failure class on **reference** handlers — buggy vs fixed. Not your code | `bug_pattern_id*`, `prompt`, `sandbox_id`, `flow_run_id` | | `list_workflows` | Workflows AND the failure scenarios a spec can inject, in one answer | `spec_slug` or `spec_id` | | `guide` | Routes a symptom to the provider behaviour that explains it, and returns the next call with its arguments filled in | `intent*`, `hints` | | `coach` | Multi-turn help building an integration | `intent`, `session_id`, `user_response`, `context` | Those seven are the whole of what a browser-based builder sees, and they are the only ones that need no filesystem. Everything below requires a local project. **On a machine with your code** | Tool | What it does | Arguments | |---|---|---| | `find_bugs` | Audits your project against known integration failure classes | `path`, `spec`, `timeout_s` | | `fix_bug` | Returns a `git diff` for one finding. Doesn't touch your files | `bug*`, `fix_pattern`, `path`, `spec`, `timeout_s` | | `prove_fix` | Runs the failure against your code before and after the diff. Green only on a measured flip | `diff*`, `bug`, `scenario`, `sandbox_id`, `path`, `timeout_s` | | `run_all_workflows` | Runs several workflows in one call | `sandbox_id*`, `workflow_names` | | `list_scenarios` | The failures a spec can inject | `sandbox_id*` | | `set_scenario` | Arms a failure on a sandbox | `sandbox_id*`, `scenario*` | | `list_runs` | Past runs for a sandbox | `sandbox_id*`, `limit` | | `list_specs` | Specs already available | `filter` | | `submit_proof` | Publishes a receipt for a run | `sandbox_id`, `flow_run_id`, `bug_pattern_id`, `summary`, `proofs` | `*` = required. ## What leaves your machine `find_bugs`, `fix_bug` and `prove_fix` package the directory you point them at and upload it for analysis. Worth saying plainly, because the previous wording here implied the opposite. Excluded before packing: `.git`, `node_modules` and build output, agent instruction files, and anything credential-shaped — `.env*`, `*.pem`, `*.key`, `id_rsa*`, `*.tfstate`, `.npmrc`, `.aws`, `.ssh` and more. Then the archive is read back and **refused** if it still contains something shaped like a live credential, wherever it lives and whatever it is called. A key in `config/local.yml` stops the upload and names the file. Patterns only cover what someone thought of; the scan is there for the rest. If you would rather nothing left at all, the analysis needs the source today. That is the honest state. ### Receipts are public to anyone holding the link `submit_proof` attaches the real requests and responses from your app's before/after run to the receipt page, so the receipt shows your code's own behaviour. That page is served without a login — that is the point of it, you drop the link in a PR — which means the bodies on it are readable by anyone who has the link. The probes run against the FetchSandbox twin, not your provider, so the data is sandbox data. But the request bodies are the ones your app built, and those can carry values from your config. Look at a receipt before you share it. ## Configuration | Env var | Default | Purpose | |---|---|---| | `FETCHSANDBOX_API_KEY` | none | Sign in without a browser. Overrides the stored credentials | | `FETCHSANDBOX_BASE_URL` | `https://fetchsandbox.com` | Point at a different backend | | `FETCHSANDBOX_TELEMETRY` | on | Set to `0` to turn off | Telemetry records an opaque per-machine id (a random UUID in `~/.fetchsandbox/session.json`), the tool name, latency, and whether the call succeeded. Not spec content, not request bodies, not credentials. It's how we count sessions and see which APIs people bring. Once you sign in, calls are also attributed to your account — that is the point of signing in, and it is what lets your runs appear in one place. `FETCHSANDBOX_TELEMETRY=0` stops the per-machine id being sent, so calls are no longer linked to your machine. It does not make a call invisible: the server still records that a tool ran, because it is the thing running it. And if you are signed in, your key identifies you regardless — that is what a key is. To be unattributed, don't sign in. ## License MIT — see [LICENSE](LICENSE). - [fetchsandbox.com](https://fetchsandbox.com) - [Source](https://github.com/fetchsandbox/mcp) · [Issues](https://github.com/fetchsandbox/mcp/issues)