FetchSandbox

io.github.fetchsandboxPublished by GitHub account fetchsandboxv0.7.30Updated Nov 2, 2026

A deterministic verification engine for agents. Proves a fix: fails on the old code, passes on new.

VerifiedStreamable HTTPWeb executableDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

FetchSandbox verifies API integrations: it reproduces provider failures against a sandbox, audits your code, and proves a fix with a shareable receipt.

What you can do
  • Route a symptom or provider question to the right spec, workflow and failure class
  • Run curated multi-step provider workflows and re-run them with injected failures
  • Audit a local project for known integration failure classes and get a git diff for a finding
  • Prove a fix by running the same failure before and after the diff, and publish a receipt
  • Validate your own app against a fresh provider twin and report what your code actually called
  • Poll long-running jobs and manage sandboxes, scenarios, runs and specs
When to use it
Useful when an assistant writes or debugs payment, email, auth, SMS or subscription integrations and you want evidence that the code handles retries, declined cards, rate limits and auth errors, rather than trusting documentation or a green connection.
Requirements
Runs locally via npx (Node.js) or as a hosted streamable-HTTP endpoint. Discovery and reference tools work without an account; planning, verification and managed tunnels need an API key in FETCHSANDBOX_API_KEY (or a Bearer token on the hosted endpoint). Outbound HTTPS to the backend is required; FETCHSANDBOX_BASE_URL and FETCHSANDBOX_TELEMETRY are optional.
Before you install
find_bugs, fix_bug and prove_fix upload the directory you point them at for analysis, with credential-shaped files excluded and a scan that refuses archives containing live-looking secrets. Receipts are public to anyone with the link and can contain request bodies built from your config. Temporary provider keys and webhook secrets are written to a private dotenv file that you must delete. Telemetry is on by default; FETCHSANDBOX_TELEMETRY=0 disables the per-machine id.

Installation

In SourceWeft

  1. Open FetchSandbox in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.fetchsandbox%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "fetchsandbox": {
      "type": "http",
      "url": "https://fetchsandbox.com/mcp/v1"
    }
  }
}

README

fetchsandbox-mcp

[FetchSandbox MCP - The MCP that proves your AI's integration fixes work | Product Hunt]

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.

json
{  "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.

ClientFile
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]

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.

json
{  "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:

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

ToolWhat it doesArguments
guideRoutes a symptom to a spec, workflow and known failure classintent*, hints
find_bugsAudits your project against known integration failure classes. No git remote needed — it reads the directory you point it atpath, spec, timeout_s
fix_bugReturns a git diff for one finding. Doesn't touch your filesbug*, fix_pattern, path, spec, timeout_s
get_jobRetrieve the same running job without starting another analysis or proofjob_id*
prove_fixRuns the failure against your code before and after the diff. Green only on a measured flipdiff*, bug, scenario, sandbox_id, path, timeout_s

Verifying an integration

ToolWhat it doesArguments
validate_integrationProves 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 calledproviders, app_base_url, session_id
quickrunRuns one of OUR curated workflows against a bundled spec. Green here says the provider behaves as documented — it says nothing about your integrationspec_slug*, workflow_name*, scenario
run_workflowThe same, on a sandbox you already have — this is where you re-run with a scenario armedsandbox_id*, workflow_name*, scenario
verify_behaviorShows a failure class on reference handlers — buggy vs fixed. Not your codebug_pattern_id*, prompt, sandbox_id, flow_run_id
list_workflowsWorkflows AND the failure scenarios a spec can inject, in one answerspec_slug or spec_id
guideRoutes a symptom to the provider behaviour that explains it, and returns the next call with its arguments filled inintent*, hints
coachMulti-turn help building an integrationintent, 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

ToolWhat it doesArguments
find_bugsAudits your project against known integration failure classespath, spec, timeout_s
fix_bugReturns a git diff for one finding. Doesn't touch your filesbug*, fix_pattern, path, spec, timeout_s
get_jobRetrieve the same running job without starting another analysis or proofjob_id*
prove_fixRuns the failure against your code before and after the diff. Green only on a measured flipdiff*, bug, scenario, sandbox_id, path, timeout_s
run_all_workflowsRuns several workflows in one callsandbox_id*, workflow_names
list_scenariosThe failures a spec can injectsandbox_id*
set_scenarioArms a failure on a sandboxsandbox_id*, scenario*
list_runsPast runs for a sandboxsandbox_id*, limit
list_specsSpecs already availablefilter
submit_proofPublishes a receipt for a runsandbox_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, .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

Env varDefaultPurpose
FETCHSANDBOX_API_KEYnoneSign in without a browser. Overrides the stored credentials
FETCHSANDBOX_BASE_URLhttps://fetchsandbox.comPoint at a different backend
FETCHSANDBOX_TELEMETRYonSet 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.

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.

Source: README.md at commit daab239

Tools

8

coach

Conversational integration coach for FetchSandbox. Server-side orchestrator that walks the user through adding an API integration (payments / email / auth / etc.) — intake the goal, elicit domain-aware discovery questions from the spec's brain.yaml, route to the right workflow, prove the contract via FetchSandbox, surface compliance notes. Call this BEFORE any other FetchSandbox tool when the user has an open-ended 'help me add X', 'integrate X', 'test my X integration' ask. BEHAVIOR — strict, do exactly this each turn: If next_action=act_in_app, carry out next_actions with your platform's code, configuration and test tools, then return the results to the same validation session. Do not ask the human to choose routine fault tests, supply missing fixture data you can generate, or copy tool output. Ask only for genuine access, secret-entry constraints or ambiguous business rules. Never claim unsupported checks passed. (1) Say `message_for_user` to the user (verbatim or lightly paraphrased to fit your voice — but don't add new content). (2) If `next_action=wait_for_user` AND `options` is present + non-empty: USE YOUR CLIENT'S NATIVE QUESTION-PICKER TOOL (in Cursor / Claude Code this is `AskUserQuestion`) to render the lettered picker with the `question` text, the `options[].label` as rows, `default_option` as default, and an 'Other...' freeform row when `allow_freeform=true`. When the user picks or types, call coach again with `{session_id, user_response: <picked value or freeform text>}`. (3) If `next_action=wait_for_user` AND no `options`: just wait for free text. (4) If `next_action=call_tool`: invoke `tool_call.tool` with `tool_call.args`, then call coach again with the result in `context`. (5) If `next_action=done`: end the session. For a hosted app-builder request to build or test an integration, keep the user's simple goal intact and let the server route all named providers into one validation session. When FetchSandbox returns twin bindings, treat those as temp

Parametersintentcontextsession_iduser_response

get_job

Retrieve the SAME running find_bugs, fix_bug, prove_fix, verify_behavior or validate_integration job (including requirements planning). Follow next_tool_call until status is done or error. Never restart the original tool to poll. A proposed plan is not execution proof; a running response is not proof. Only the completed measured verdict and receipt can establish a pass.

Parametersjob_idrequired

guide

ROUTE a symptom to the provider behaviour that explains it. Use this when the user names a provider or a domain (payments, email, auth, SMS, subscriptions) and you need to know what that provider ACTUALLY does — not what its docs say, and not what can be inferred from reading the integration code. Reading the code tells you what your app does with a field. It cannot tell you what the field MEANS at the provider — whether a line item is a seat count, whether a 200 body carries ok:false, whether an event can arrive out of order. That is the class of bug this routes. Returns {spec, workflow, scenario, confidence, reasoning} plus `next_actions`: a typed list of what to call next, with arguments pre-filled. Follow it rather than improvising the next step.

Parametershintsintentrequired

quickrun

Run a curated reference workflow against a KNOWN, bundled spec (stripe, clerk, descope, resend, twilio, and 50+ others) in ONE call — it spins up the sandbox by slug, so you do NOT need import_spec or a sandbox_id first. Use this when exploring the bundled provider contract: call `guide` on their prompt, then call `quickrun` with the returned spec + workflow. To reproduce a failure, pass the `scenario` from guide's matched_bug_pattern.reproduce_with.scenario (e.g. webhook_retries, payment_declined). Returns sandbox_id + flow_run_id — pass BOTH to verify_behavior to inspect the reference behavior — plus a receipt URL. This does not execute or prove the caller's application. For a bug in their project, use find_bugs, fix_bug and prove_fix on that project; do not substitute this reference receipt for an own-code proof. Use run_workflow instead ONLY when you already hold a sandbox_id from import_spec of a custom/private spec.

Parametersscenariospec_slugrequiredworkflow_namerequired

validate_integration

Completion rule: a request to verify an app includes its applicable failure checks without another user prompt. When verification_continuation.required is true, continue in this agent: inspect pending_checks, preserve every declared check and its assertions, implement supported actions, and rerun a fresh attempt. Stop only with measured results or concrete blockers showing the missing capability and attempted evidence. Not run, not armed, and no observer yet are work to finish, not unsupported features. Do not clean up the session or present a final proof while actionable checks remain. Ask the owner only for genuinely missing business decisions, credentials or actions you cannot perform. For a local app, start the actual app and call manage_tunnel with its port; use the returned app_base_url. No ngrok install is needed. The managed relay origin deliberately rejects direct browser/curl requests with 404; after configuration and credential installation, test connectivity with validate_integration preflight instead. Do not interpret that private-origin 404 as an app failure or expose relay credentials. Hosted builders use their published origin. Start with providers (and optional app_base_url), then reuse the returned session_id for application_context, fixtures and attempts. Do not include application_context in the initial session call. Inspect how the actual app or workflow executes before choosing a verification path. If the builder can run that workflow locally, bind its real provider clients to every returned twin URL and the supplied test authentication. Use the returned provider operation contracts to implement those clients; a missing canned workflow does not mean the provider lacks an API operation. The existing arm/probe path does not require a published app or webhook: select a probe from the returned matrix, call arm with session_id, send its request_headers on EVERY provider request across the session, execute the actual workflow entry point, then call p

Parametersarmprobesuitecancelrun_idexecuteinspectfixturesreassesspreflightproviderssession_id+4 more

list_workflows

List the named, runnable workflows for a known provider slug or imported spec. Workflows are realistic multi-step API journeys (e.g. 'create customer → attach payment method → create subscription'). Known provider slugs need no import. Use this for exploration ("what can I do?", "show me the flows") OR before run_all_workflows when the user wants a SCOPED validation: list, filter by user intent ("checkout", "webhooks"), then pass the matching ids as `workflow_names` to run_all_workflows. Default results are summaries. Pass workflow_name with an exact returned id or name to inspect that workflow's full definition, including request bodies, assertions, outcomes and invariants; this does not execute it. Returns the workflows AND the failure scenarios this spec can simulate — each with a plain description and the exact call to run it. When cross_service_available is present, use each exact run_with invocation: cross-provider workflows use the returned namespace, not this provider's slug. These curated workflows exercise provider behavior; they do not verify the user's app. Choose relevant scenarios from the inspected workflow and user goal; ask only about ambiguous business requirements. Do not guess scenario names.

Parametersspec_idspec_slugworkflow_name

run_workflow

Execute ONE specific workflow by name and return its step-by-step trace PLUS a `share_url` — a public, replayable proof URL that renders the full timeline (every request, response, webhook event) for this run. The share_url is the canonical 'here's what happened' artifact: surface it verbatim in any reply that needs evidence (PR comments, Slack threads, blog posts, X replies). Do NOT substitute a docs URL or any other link as the proof — the share_url is the only valid receipt. Use ONLY when the user explicitly names a single workflow to run (e.g., "run accept_payment", "just check the refund workflow"). For ANY validation-style request — "validate stripe", "check coverage", "run all workflows", "test this integration", or even "validate stripe checkout" (multiple workflows match "checkout") — use `run_all_workflows` instead. The batch tool collapses N approvals to 1 and supports a workflow_names filter for scope. Calling this in a loop is an anti-pattern.

Parametersscenariosandbox_idrequiredworkflow_namerequired

verify_behavior

Prove a known fix survives a bug — the 'prove' half of reproduce→prove. The backend spawns a buggy AND a fixed reference handler and fires the bug_pattern's probes at both, returning the side-by-side diff (e.g. the buggy handler double-charges on a duplicate webhook, the fixed handler dedupes). Call this AFTER run_workflow reproduces a failure, when the matched bug_pattern has a simulation block, to show the fix actually holds — not just that the failure reproduced. Pass sandbox_id + flow_run_id from the run so the diff is saved onto that run's receipt URL. bug_pattern_id comes from guide's matched_bug_pattern. The buggy/fixed handlers are FetchSandbox reference implementations, NOT the user's code. A confirmed reference result does not verify the user's app or show that it is ready to ship. Keep the returned provider and evidence scope with any reported result.

Parameterspromptsandbox_idflow_run_idbug_pattern_idrequired

Version history

14
  1. v0.7.30LatestOct 19, 2026
  2. v0.7.29Oct 18, 2026
  3. v0.7.28Oct 12, 2026
  4. v0.7.25Oct 12, 2026
  5. v0.7.17Oct 11, 2026
  6. v0.7.15Oct 11, 2026
  7. v0.7.2Oct 4, 2026
  8. v0.7.1Oct 2, 2026
  9. v0.7.0Sep 25, 2026
  10. v0.5.9Sep 23, 2026
  11. v0.5.7Sep 21, 2026
  12. v0.5.6Sep 18, 2026
  13. v0.5.5Sep 18, 2026
  14. v0.5.3Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts