fetchsandbox-mcp

Also on Smithery, npm and the official MCP registry.

A deterministic verification engine for agents, as an MCP server for FetchSandbox.

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

The MCP server runs locally through Node.js. Clients can resolve npx differently; Cursor on Mac may need the full path from command -v npx.

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

Discovery and reference tools are available without a key. Application planning, verification and managed local tunnelling require sign-in or an API key from https://fetchsandbox.com/keys. See Accounts.

Cursor on Mac: tested setup

Get a real account key from https://fetchsandbox.com/keys. Run command -v npx and use that full path in ~/.cursor/mcp.json. This example is for Homebrew on Apple Silicon; replace the path if yours differs. On Windows, use where.exe npx to locate your installed command.

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

Replace fsk_your_key_here privately with the real raw key, without a Bearer prefix. The placeholder cannot authenticate. Check for a second FetchSandbox entry in .cursor/mcp.json in your project. Fully quit and reopen Cursor after saving; a window reload may retain the old MCP process. Enable the server if needed and confirm its tools load. A green connection alone does not prove that an application verification call is authenticated.

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:

"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

Verifying an integration

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

* = 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, .mcp.json, .mcp.*.json, mcp.json, 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.

Long-running work

The MCP response waits briefly, then returns status: running, its job_id, and a next_tool_call for get_job. Follow that call until status: done or error. It reads the existing backend job; it does not upload the project again or start another proof. Keep the original tree unchanged while the proof runs. A running job does not establish a pass.

This applies to discovery, proposed fixes, application proofs, and async reference verification. Direct library calls keep their blocking behavior. Job retention and ownership still belong to the existing backend. This change does not make its in-memory job tracker survive a backend restart.

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.

Provider execution can use a FetchSandbox twin or a recording test double; read the receipt's execution scope. A recording double does not establish twin or live-provider fidelity. 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

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.

• fetchsandbox.com
• Source · Issues

Verify a local app without ngrok

Version 0.7.13 adds manage_tunnel to the local MCP package. Start your actual isolated app, open its loopback port, and give the returned app_base_url to validate_integration. Declare the existing app webhook path in application_config.event_destinations. FetchSandbox signs provider-native events and checks independently saved state through the existing application runner. Configure test secrets via the protected handoff, preflight, execute once and retrieve the same run receipt. Close the connection and remove temporary settings afterward. Connectivity alone is not a passing test.

Requires outbound HTTPS to fetchsandbox.com, a running local MCP process and a real local app. No inbound firewall rule or separate tunnel install is needed. Restricted networks may require their approved proxy/CA configuration. Node 22.21+ or 24.5+ supports NODE_USE_ENV_PROXY=1 with HTTPS_PROXY and NO_PROXY; include 127.0.0.1/localhost in NO_PROXY and use NODE_EXTRA_CA_CERTS for an approved corporate CA. Older Node versions do not automatically support this proxy setup. Do not disable TLS certificate validation. Corporate firewalls can still block the connection. Leases expire after 30 minutes or server restart; uncertain writes are not automatically repeated.

Private credentials for local app verification (0.7.14)

After configuring an owned application run, Cursor, Claude Code and other local MCP clients call install_test_credentials with its session and run IDs. The existing FetchSandbox account key authorizes retrieval. Temporary provider keys, webhook secrets and the verifier token are written to a new private dotenv file under ~/.fetchsandbox/handoffs/ (directory 0700, file 0600), outside the project. Only its path and variable names enter the tool result. env_mapping explicitly maps returned names to the real app's environment settings.

Load that file with the disposable application's dotenv loader without printing it. Configure the returned twin base URLs, restart the app, preflight, execute once and retrieve the same receipt. Remove the temporary file after testing. Files do not delete themselves and are not production credentials. Never paste values into chat, source, logs or command arguments. Replit/Lovable keep their existing owner browser handoff and native secret managers. This change does not route prove_fix through the local relay.