Lets an AI agent verify integration fixes by running them against a deterministic sandbox that simulates real-world provider failures.
Also known as fetchsandbox/mcp, mcp, fetchsandbox-mcp
- Stars
- 1
- Tools
- 19
- Downloads, 30 days
- —
- Latest version
- 0.7.33
- Last commit
- Nov 15, 2026
- License
- MIT
What is FetchSandbox MCP?
FetchSandbox lets an AI agent verify integration fixes by running them against a deterministic sandbox that simulates real-world provider failures. It exposes 19 tools, such as coach, find_bugs, fix_bug.
Summary generated from the project's README
About FetchSandbox MCP server
Verifying that integration fixes actually work against real-world provider failures is what FetchSandbox enables for AI agents. It provides a deterministic verification engine that simulates scenarios like declined cards, rate limits, auth errors, and retried webhooks. This allows developers to use an AI client to not only find bugs in their integration code but to prove that a proposed fix successfully resolves the issue.
The server runs locally via Node.js using npx, making it compatible with clients like Claude Desktop, Cursor, Zed, and Claude Code. For browser-based builders that cannot run local commands, a hosted HTTP transport is available. While discovery tools work without an account, advanced features like application planning and verification require a FetchSandbox API key. When running locally, tools like find_bugs and prove_fix package and upload your project directory for analysis, though the system automatically excludes sensitive files like .env or .pem to protect credentials.
What you can do with it
- 1Verify integration fixesAn agent can run a failure against your code both before and after applying a diff to prove the bug is gone.
- 2Simulate provider failuresDevelopers can use the sandbox to inject specific failure scenarios into a workflow to test resilience.
Written from the project's README. Every use case is checked against a quote from it.
How to install FetchSandbox MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall FetchSandbox MCP in Claude Code
$ claude mcp add --env 'FETCHSANDBOX_API_KEY=<YOUR_FETCHSANDBOX_API_KEY>' mcp -- npx -y fetchsandbox-mcpInstall FetchSandbox MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"fetchsandbox-mcp"
],
"env": {
"FETCHSANDBOX_API_KEY": "<YOUR_FETCHSANDBOX_API_KEY>"
}
}
}
}Install FetchSandbox MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"fetchsandbox-mcp"
],
"env": {
"FETCHSANDBOX_API_KEY": "<YOUR_FETCHSANDBOX_API_KEY>"
}
}
}
}Install FetchSandbox MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","fetchsandbox-mcp"],"env":{"FETCHSANDBOX_API_KEY":"<YOUR_FETCHSANDBOX_API_KEY>"}}'Install FetchSandbox MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"fetchsandbox-mcp"
],
"env": {
"FETCHSANDBOX_API_KEY": "<YOUR_FETCHSANDBOX_API_KEY>"
}
}
}
}Install FetchSandbox MCP in Codex
$ codex mcp add mcp --env 'FETCHSANDBOX_API_KEY=<YOUR_FETCHSANDBOX_API_KEY>' -- npx -y fetchsandbox-mcpInstall FetchSandbox MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "fetchsandbox-mcp"] [mcp_servers.mcp.env] FETCHSANDBOX_API_KEY = "<YOUR_FETCHSANDBOX_API_KEY>"
Install FetchSandbox MCP in Gemini CLI
$ gemini mcp add -s user -e 'FETCHSANDBOX_API_KEY=<YOUR_FETCHSANDBOX_API_KEY>' mcp npx -- -y fetchsandbox-mcpInstall FetchSandbox MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"fetchsandbox-mcp"
],
"env": {
"FETCHSANDBOX_API_KEY": "<YOUR_FETCHSANDBOX_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for fetchsandbox-mcp 0.7.33 in an isolated container with no network and no keys. It answered and listed 19 tools.
FetchSandbox MCP tools 19
Read from the server with tools/listcoachRead-onlyConversational 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 temporary TEST credentials: configure them server-side in the app-builder project, never ask the user for live Paddle/Resend keys, and never claim they were applied until the builder reports the change and the verifier observes app traffic. Infer app configuration details from the project when available; ask the user only for a fact the builder cannot discover. The deterministic verifier, not this conversation, owns the verdict. The state machine is server-side — DON'T try to predict the next step or skip ahead; let the server drive.
find_bugsRead-onlyLong work returns status:running and next_tool_call:get_job within a short response. Follow that SAME job until done; never repeat this tool to poll. FIRST STEP for any API-integration bug — webhooks, payments, auth, email, SMS, subscriptions. Reach for this the moment a user reports a symptom in an app that talks to a provider: 'customers charged twice', 'the webhook fires but nothing happens', 'their balance is wrong', 'we keep emailing a bounced address', 'paused but they still have access'. Packages the current project — local, uncommitted, private, no git URL needed — and audits it against a corpus of real, harvested API-integration failures (idempotency, signature verification, event ordering, pagination, rate limits, state drift) that a read of the code alone does not surface. THIS IS A FINDING, NOT A PROOF. Every finding is a hypothesis until it is measured on the real code. Do NOT stop here, and do NOT write your own test to confirm one — call fix_bug for a proposed diff, then prove_fix to measure it. The response carries `next_actions` telling you exactly what to call next; follow it. Runs for up to a few minutes.
fix_bugRead-onlyLong work returns status:running and next_tool_call:get_job within a short response. Follow that SAME job until done; never repeat this tool to poll. FetchSandbox remediation: get a proposed fix for a specific bug in YOUR code. The 'fix' step after find_bugs. Ships the project to the FetchSandbox runtime, which authors a MINIMAL fix grounded in the known remediation for that failure class and returns a git diff — it does NOT modify your files. Review the diff, then call prove_fix with the diff and the STILL-BUGGY project BEFORE applying it. Apply the patch only after inspecting that result. The diff is a proposal, not a proof; quickrun and verify_behavior on reference handlers do not prove this change on your application. Runs for up to a few minutes.
get_jobRead-onlyRetrieve 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.
prove_fixActionLong work returns status:running and next_tool_call:get_job within a short response. Follow that SAME job until done; never repeat this tool to poll. THE PROOF STEP. The only way to establish that a fix actually works, and produces an own-code proof receipt. Ship the STILL-BUGGY project plus your proposed diff: FetchSandbox applies the diff to a copy and runs the SAME failure probe against the buggy and the fixed tree. Inspect the receipt's provider modes: a recording double, a twin and an original provider are different evidence scopes. Green ONLY on a measured flip — the bug demonstrably present before, demonstrably gone after. CALL THIS BEFORE YOU WRITE THE FIX TO DISK. prove_fix needs the broken tree to reproduce against; applying the diff first makes a measured proof impossible. DO NOT SUBSTITUTE YOUR OWN TEST. A harness you write runs only the FIXED code, so it can show a fix passing while proving nothing about whether the bug was ever reproduced or is genuinely gone — and an agent-authored check must never be reported to a user as 'proven' or 'verified'. If you have already written one, still call this: your test and this proof answer different questions.
guideRead-onlyROUTE 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.
quickrunActionRun 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.
list_specsRead-onlyBrowse the FetchSandbox spec catalog — every API (Stripe, GitHub, Twilio, Notion, OpenAI, Polar, GitLab, and 40+ more) that has a ready-to-use sandbox with curated workflows. Use when the user asks 'what APIs do you support?', 'what specs are available?', 'show me the catalog', 'do you have <X>?', or wants to explore before committing to one. Returns each spec's slug (use as `name` arg to import_spec), description, endpoint count, and tags. Pass `filter` to narrow by substring (e.g., filter='pay' returns Stripe, Paddle, Polar).
install_test_credentialsActionLocal coding agents only: after validate_integration configures an owned run, install its temporary twin API keys, webhook signing secrets and verifier token privately. Uses your existing FetchSandbox MCP account key; no browser sign-in or secret values in chat. Returns a private dotenv file path and variable names ONLY. Supply env_mapping from returned required_secret_names to the inspected app setting names, e.g. FETCHSANDBOX_STRIPE_WEBHOOK_SECRET:STRIPE_WEBHOOK_SECRET. Never invent secrets or remove signature checks. Start/restart ONLY the disposable test app with this file using its dotenv loader; never cat/read/print it or paste values into a prompt, source, logs or shell arguments. Twin base URLs come from validate_integration and must also be configured. Preserve existing production configuration. Then preflight and execute once, retrieve the same run receipt, and delete this temporary file after testing. Hosted Replit/Lovable use their existing protected browser handoff and native secret manager.
manage_tunnelActionConnect the actual local disposable test app to the FetchSandbox verifier, without installing ngrok or sharing an account token. Local stdio coding agents only; hosted builders use their published app origin. Steps: (1) inspect the real app, its provider clients, existing webhook handler route, signature verification and saved-state read-back; never invent a substitute webhook route or remove signature checks. (2) Start that app on a loopback port and call action=open,port. (3) Call validate_integration with providers and the returned app_base_url; retain session_id. (4) Inspect coverage_policy, propose application checks, prepare/read back fixtures, and configure suite=application_workflow_v1. Register the exact inspected webhook path in application_config.event_destinations, e.g. stripe:/stripe-webhook ONLY if that is the real handler. For Stripe purchase verification, set application_config.event_delivery=provider_lifecycle. FetchSandbox registers this exact tunnel route using the isolated Stripe twin POST /v1/webhook_endpoints, returns registration metadata, and supplies its signing secret through the protected handoff. Drive the real app order/payment entry points and confirm/capture its actual PaymentIntent; do not replace the purchase with synthetic success events. Assert saved order and email effects. Other provider lifecycle registrations remain explicit gaps; existing hosted receipt suites keep their current path. Direct signed-event mode remains for targeted event tests and is not full purchase lifecycle proof. Use provider-native event types/payloads and exact event-ID replay. (5) Use the native protected handoff: call install_test_credentials with session_id/run_id and inspected env_mapping; load its private dotenv file into the disposable app without reading or printing it. Configure temporary provider base URLs; preserve production configuration. The relay credential is internal and never goes to the app. (6) Preflight, execute ONCE, then poll the same session_id/run_id and retrieve its receipt. Independently assert order/state and receipt effects across replay, concurrent/stale/delayed events, invalid signatures and relevant provider failures, response loss and restart. HTTP 200 or connectivity alone is not proof; retain unsupported/unmeasured checks. Compare original buggy and fixed app versions under the same contract. (7) Close the tunnel and clean temporary settings. If local startup/connectivity fails, retain the blocker and use the existing Phalanx prove_fix fallback. This temporary address is verifier-only, not a public website. Direct browser/curl requests deliberately return 404 even when the relay is healthy. Do not treat that 404 as failed connectivity, inspect FetchSandbox internals, expose relay credentials or switch verification paths because of it. After configuration and credential installation, use validate_integration preflight to test actual app connectivity; manage_tunnel status checks only the transport. A disconnect or backend restart ends the lease; do not automatically replay uncertain writes.
validate_integrationActionCompletion 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 probe with the same session_id and returned run_id. Independently assert saved app state in the host and report that evidence separately. Provider traffic alone remains app_verified:false; it does not establish application execution or state. Do not substitute a standalone simulation, direct twin calls or a curated workflow for the user's implementation. A public origin is required when FetchSandbox must drive or observe an HTTP application suite; the hosted setup instructions below apply to that path. For hosted application_workflow_v1 apps, build and publish the disabled test adapter before requesting short-lived credentials. After installing the existing handoff and republishing, call preflight:true with session_id/run_id. A setup_blocked response is not a failed application test. Its next_tool_call is null: repair its exact host-side blocker first, then call resume_tool_call for the SAME run/preflight without rotating credentials. Do not poll an unchanged setup blocker. Execution has a separate deadline. Execution is already non-blocking: execute:true starts the existing backend job and returns running promptly. Use the SAME builder agent to follow status; no extra background helper or helper approval is needed. Never execute twice; retrieve status with session_id/run_id only. If the browser stops at a security challenge, immediately hand the owner the SAME run/order-verified original TEST checkout URL (livemode=false) while observation continues; never bypass the challenge, silently wait, create a replacement checkout or retry Pay. For an owner-assisted browser step, use ONE native question containing that verified URL, pause the builder for its answer while the backend job continues, and record that answer once. Do not keep working while asking for a plain chat reply that the host queues, or ask again after confirmation is recorded. Browser payments require an available browser or one explicit user action, and independently observed paid state; a click is not proof. After proof, remove only temporary settings, republish and verify disabled externally. When asked to reassess or recontract, set reassess=true and supply application_config.scope_review for every candidate check. Record outside-scope features separately, and keep relevant missing or failed behavior required. Scope is declared by the app-owning agent from its inspected code and requirements, not guessed from a provider name. For every app, inspect capabilities, coverage_policy and application_actions. Review every supplied coverage dimension against inspected app behavior without waiting for the user to enumerate failure tests. Supply application_config.coverage_review with relevance, reason and linked check IDs when the builder authors the plan. Missing dimensions stay unreviewed. A dimension review is not execution proof; never claim all possible invariants are known. Prepare missing test products, prices and related records before failures: author fixtures using documented provider operations, include a final GET with an exact identity assertion, then configure the app with returned fixture IDs. The server uses the existing twin workflow runner and independently checks read-back. Fixture readiness is not app proof. Unsupported application checks must be reported explicitly, not replaced by a separate script or quickrun. Use the returned fixture_authoring contract, not a web search for assertion syntax. Prepare fixtures before configuring any attempt. Fixture assertions are GET-only and contain select, equals (string), required:true, count:1. Use separate asserted GET steps for each additional value; do not use application all_of or where predicates in fixture assertions. Paddle selectors include the response envelope, e.g. data.id; Stripe uses id. Read the provided Paddle one-time-price example and adapt its product and amount to the app. If fixed receipt-suite transactions cannot match the app's product, price and pending order, do not execute them as app proof or a pointless rejection diagnostic. Report that compatibility gap, cancel any unexecuted mismatched attempt, then use application_workflow_v1 for supported checks while preserving untested receipt rules. After session creation, send session_id and application_context with the original goal and inspected workflow to obtain model-proposed rules, missing observations and fixture requirements. This planning action requires sign-in. Proposals are not executed checks. The app-owning agent authors the executable contract from inspected code and business scope. Server suggestions are advisory. Review every coverage dimension; declare relevant unsupported behavior explicitly and explain genuinely unrelated features as not_applicable. Omitted suggestions are retained separately and cannot add required checks. If server_requirements_model_available is false or planning returns requirements_model_unavailable, inspect the app and author the candidate contract with your own model; label it builder-proposed, not a FetchSandbox model result. Never wait for the human to write routine test requirements. For a Stripe app on a managed tunnel or published origin, use application_config.event_delivery=provider_lifecycle with the exact Stripe handler in event_destinations and require_verifier_token=true. Configuration creates a real subscription on this isolated Stripe twin via POST /v1/webhook_endpoints; the protected handoff supplies its returned signing secret. Select a returned catalog lifecycle profile with application_config.provider_lifecycle_workflows, e.g. {stripe:'create_and_send_invoice'} for invoice.sent or {stripe:'accept_payment'} for payment_intent.succeeded. The server freezes the workflow's subscription events, witness types and provider readback; missing delivery or mismatched provider state cannot pass. Drive that workflow through the inspected app's actual entry point. Do not manufacture a payment for an invoice or another non-payment workflow. Without a selectio
list_workflowsRead-onlyList 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.
| 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 temporary TEST credentials: configure them server-side in the app-builder project, never ask the user for live Paddle/Resend keys, and never claim they were applied until the builder reports the change and the verifier observes app traffic. Infer app configuration details from the project when available; ask the user only for a fact the builder cannot discover. The deterministic verifier, not this conversation, owns the verdict. The state machine is server-side — DON'T try to predict the next step or skip ahead; let the server drive. | Read-only |
| find_bugs | Long work returns status:running and next_tool_call:get_job within a short response. Follow that SAME job until done; never repeat this tool to poll. FIRST STEP for any API-integration bug — webhooks, payments, auth, email, SMS, subscriptions. Reach for this the moment a user reports a symptom in an app that talks to a provider: 'customers charged twice', 'the webhook fires but nothing happens', 'their balance is wrong', 'we keep emailing a bounced address', 'paused but they still have access'. Packages the current project — local, uncommitted, private, no git URL needed — and audits it against a corpus of real, harvested API-integration failures (idempotency, signature verification, event ordering, pagination, rate limits, state drift) that a read of the code alone does not surface. THIS IS A FINDING, NOT A PROOF. Every finding is a hypothesis until it is measured on the real code. Do NOT stop here, and do NOT write your own test to confirm one — call fix_bug for a proposed diff, then prove_fix to measure it. The response carries `next_actions` telling you exactly what to call next; follow it. Runs for up to a few minutes. | Read-only |
| fix_bug | Long work returns status:running and next_tool_call:get_job within a short response. Follow that SAME job until done; never repeat this tool to poll. FetchSandbox remediation: get a proposed fix for a specific bug in YOUR code. The 'fix' step after find_bugs. Ships the project to the FetchSandbox runtime, which authors a MINIMAL fix grounded in the known remediation for that failure class and returns a git diff — it does NOT modify your files. Review the diff, then call prove_fix with the diff and the STILL-BUGGY project BEFORE applying it. Apply the patch only after inspecting that result. The diff is a proposal, not a proof; quickrun and verify_behavior on reference handlers do not prove this change on your application. Runs for up to a few minutes. | Read-only |
| 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. | Read-only |
| prove_fix | Long work returns status:running and next_tool_call:get_job within a short response. Follow that SAME job until done; never repeat this tool to poll. THE PROOF STEP. The only way to establish that a fix actually works, and produces an own-code proof receipt. Ship the STILL-BUGGY project plus your proposed diff: FetchSandbox applies the diff to a copy and runs the SAME failure probe against the buggy and the fixed tree. Inspect the receipt's provider modes: a recording double, a twin and an original provider are different evidence scopes. Green ONLY on a measured flip — the bug demonstrably present before, demonstrably gone after. CALL THIS BEFORE YOU WRITE THE FIX TO DISK. prove_fix needs the broken tree to reproduce against; applying the diff first makes a measured proof impossible. DO NOT SUBSTITUTE YOUR OWN TEST. A harness you write runs only the FIXED code, so it can show a fix passing while proving nothing about whether the bug was ever reproduced or is genuinely gone — and an agent-authored check must never be reported to a user as 'proven' or 'verified'. If you have already written one, still call this: your test and this proof answer different questions. | Action |
| 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. | Read-only |
| 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. | Action |
| list_specs | Browse the FetchSandbox spec catalog — every API (Stripe, GitHub, Twilio, Notion, OpenAI, Polar, GitLab, and 40+ more) that has a ready-to-use sandbox with curated workflows. Use when the user asks 'what APIs do you support?', 'what specs are available?', 'show me the catalog', 'do you have <X>?', or wants to explore before committing to one. Returns each spec's slug (use as `name` arg to import_spec), description, endpoint count, and tags. Pass `filter` to narrow by substring (e.g., filter='pay' returns Stripe, Paddle, Polar). | Read-only |
| install_test_credentials | Local coding agents only: after validate_integration configures an owned run, install its temporary twin API keys, webhook signing secrets and verifier token privately. Uses your existing FetchSandbox MCP account key; no browser sign-in or secret values in chat. Returns a private dotenv file path and variable names ONLY. Supply env_mapping from returned required_secret_names to the inspected app setting names, e.g. FETCHSANDBOX_STRIPE_WEBHOOK_SECRET:STRIPE_WEBHOOK_SECRET. Never invent secrets or remove signature checks. Start/restart ONLY the disposable test app with this file using its dotenv loader; never cat/read/print it or paste values into a prompt, source, logs or shell arguments. Twin base URLs come from validate_integration and must also be configured. Preserve existing production configuration. Then preflight and execute once, retrieve the same run receipt, and delete this temporary file after testing. Hosted Replit/Lovable use their existing protected browser handoff and native secret manager. | Action |
| manage_tunnel | Connect the actual local disposable test app to the FetchSandbox verifier, without installing ngrok or sharing an account token. Local stdio coding agents only; hosted builders use their published app origin. Steps: (1) inspect the real app, its provider clients, existing webhook handler route, signature verification and saved-state read-back; never invent a substitute webhook route or remove signature checks. (2) Start that app on a loopback port and call action=open,port. (3) Call validate_integration with providers and the returned app_base_url; retain session_id. (4) Inspect coverage_policy, propose application checks, prepare/read back fixtures, and configure suite=application_workflow_v1. Register the exact inspected webhook path in application_config.event_destinations, e.g. stripe:/stripe-webhook ONLY if that is the real handler. For Stripe purchase verification, set application_config.event_delivery=provider_lifecycle. FetchSandbox registers this exact tunnel route using the isolated Stripe twin POST /v1/webhook_endpoints, returns registration metadata, and supplies its signing secret through the protected handoff. Drive the real app order/payment entry points and confirm/capture its actual PaymentIntent; do not replace the purchase with synthetic success events. Assert saved order and email effects. Other provider lifecycle registrations remain explicit gaps; existing hosted receipt suites keep their current path. Direct signed-event mode remains for targeted event tests and is not full purchase lifecycle proof. Use provider-native event types/payloads and exact event-ID replay. (5) Use the native protected handoff: call install_test_credentials with session_id/run_id and inspected env_mapping; load its private dotenv file into the disposable app without reading or printing it. Configure temporary provider base URLs; preserve production configuration. The relay credential is internal and never goes to the app. (6) Preflight, execute ONCE, then poll the same session_id/run_id and retrieve its receipt. Independently assert order/state and receipt effects across replay, concurrent/stale/delayed events, invalid signatures and relevant provider failures, response loss and restart. HTTP 200 or connectivity alone is not proof; retain unsupported/unmeasured checks. Compare original buggy and fixed app versions under the same contract. (7) Close the tunnel and clean temporary settings. If local startup/connectivity fails, retain the blocker and use the existing Phalanx prove_fix fallback. This temporary address is verifier-only, not a public website. Direct browser/curl requests deliberately return 404 even when the relay is healthy. Do not treat that 404 as failed connectivity, inspect FetchSandbox internals, expose relay credentials or switch verification paths because of it. After configuration and credential installation, use validate_integration preflight to test actual app connectivity; manage_tunnel status checks only the transport. A disconnect or backend restart ends the lease; do not automatically replay uncertain writes. | Action |
| 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 probe with the same session_id and returned run_id. Independently assert saved app state in the host and report that evidence separately. Provider traffic alone remains app_verified:false; it does not establish application execution or state. Do not substitute a standalone simulation, direct twin calls or a curated workflow for the user's implementation. A public origin is required when FetchSandbox must drive or observe an HTTP application suite; the hosted setup instructions below apply to that path. For hosted application_workflow_v1 apps, build and publish the disabled test adapter before requesting short-lived credentials. After installing the existing handoff and republishing, call preflight:true with session_id/run_id. A setup_blocked response is not a failed application test. Its next_tool_call is null: repair its exact host-side blocker first, then call resume_tool_call for the SAME run/preflight without rotating credentials. Do not poll an unchanged setup blocker. Execution has a separate deadline. Execution is already non-blocking: execute:true starts the existing backend job and returns running promptly. Use the SAME builder agent to follow status; no extra background helper or helper approval is needed. Never execute twice; retrieve status with session_id/run_id only. If the browser stops at a security challenge, immediately hand the owner the SAME run/order-verified original TEST checkout URL (livemode=false) while observation continues; never bypass the challenge, silently wait, create a replacement checkout or retry Pay. For an owner-assisted browser step, use ONE native question containing that verified URL, pause the builder for its answer while the backend job continues, and record that answer once. Do not keep working while asking for a plain chat reply that the host queues, or ask again after confirmation is recorded. Browser payments require an available browser or one explicit user action, and independently observed paid state; a click is not proof. After proof, remove only temporary settings, republish and verify disabled externally. When asked to reassess or recontract, set reassess=true and supply application_config.scope_review for every candidate check. Record outside-scope features separately, and keep relevant missing or failed behavior required. Scope is declared by the app-owning agent from its inspected code and requirements, not guessed from a provider name. For every app, inspect capabilities, coverage_policy and application_actions. Review every supplied coverage dimension against inspected app behavior without waiting for the user to enumerate failure tests. Supply application_config.coverage_review with relevance, reason and linked check IDs when the builder authors the plan. Missing dimensions stay unreviewed. A dimension review is not execution proof; never claim all possible invariants are known. Prepare missing test products, prices and related records before failures: author fixtures using documented provider operations, include a final GET with an exact identity assertion, then configure the app with returned fixture IDs. The server uses the existing twin workflow runner and independently checks read-back. Fixture readiness is not app proof. Unsupported application checks must be reported explicitly, not replaced by a separate script or quickrun. Use the returned fixture_authoring contract, not a web search for assertion syntax. Prepare fixtures before configuring any attempt. Fixture assertions are GET-only and contain select, equals (string), required:true, count:1. Use separate asserted GET steps for each additional value; do not use application all_of or where predicates in fixture assertions. Paddle selectors include the response envelope, e.g. data.id; Stripe uses id. Read the provided Paddle one-time-price example and adapt its product and amount to the app. If fixed receipt-suite transactions cannot match the app's product, price and pending order, do not execute them as app proof or a pointless rejection diagnostic. Report that compatibility gap, cancel any unexecuted mismatched attempt, then use application_workflow_v1 for supported checks while preserving untested receipt rules. After session creation, send session_id and application_context with the original goal and inspected workflow to obtain model-proposed rules, missing observations and fixture requirements. This planning action requires sign-in. Proposals are not executed checks. The app-owning agent authors the executable contract from inspected code and business scope. Server suggestions are advisory. Review every coverage dimension; declare relevant unsupported behavior explicitly and explain genuinely unrelated features as not_applicable. Omitted suggestions are retained separately and cannot add required checks. If server_requirements_model_available is false or planning returns requirements_model_unavailable, inspect the app and author the candidate contract with your own model; label it builder-proposed, not a FetchSandbox model result. Never wait for the human to write routine test requirements. For a Stripe app on a managed tunnel or published origin, use application_config.event_delivery=provider_lifecycle with the exact Stripe handler in event_destinations and require_verifier_token=true. Configuration creates a real subscription on this isolated Stripe twin via POST /v1/webhook_endpoints; the protected handoff supplies its returned signing secret. Select a returned catalog lifecycle profile with application_config.provider_lifecycle_workflows, e.g. {stripe:'create_and_send_invoice'} for invoice.sent or {stripe:'accept_payment'} for payment_intent.succeeded. The server freezes the workflow's subscription events, witness types and provider readback; missing delivery or mismatched provider state cannot pass. Drive that workflow through the inspected app's actual entry point. Do not manufacture a payment for an invoice or another non-payment workflow. Without a selectio | Action |
| 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. | Read-only |
Show all 19 toolsShow fewer tools
run_all_workflowsActionExecute EVERY workflow (or a scoped subset) for a sandbox in ONE call. Use this — NOT a loop of run_workflow — for any validation-style request: "validate this integration", "run all workflows", "check coverage", "test stripe checkout", "fs validate". IDEs (Cursor, Claude Code) approve each MCP call individually, so 18 workflows via run_workflow = 18 clicks. This tool = 1 click, total. Scope via `workflow_names`: pass an array of workflow ids to run a subset (e.g., user says "validate stripe CHECKOUT" → pass ["create_checkout_session", "checkout_complete"]). Names are case-insensitive; dashes and underscores interchangeable. Returns: summary (pass/fail counts, totals) + full step trace per workflow. After running, the user can visit fetchsandbox.com/runs/<sandbox_id> for a shareable visual timeline.
run_workflowActionExecute 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.
verify_behaviorActionProve 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.
submit_proofActionReceipts are readable by anyone with the link — do not attach bodies the user would not paste into a public PR. Attach REAL before/after evidence from the USER's actual app to the run receipt. Use this AFTER you've fixed the bug and re-run the app: it makes the receipt show their own code's behavior (before your fix vs after), which is far stronger proof than a reference simulation. Provide one `proofs` entry per probe you fired — the request you sent, the response BEFORE the fix (bug reproduces), and the response AFTER the fix (bug gone) — keyed to the run's sandbox_id + flow_run_id (from run_workflow's result). This is SELF-REPORTED evidence: it's shown on the receipt but never counts as a proven (green) result. For a MEASURED green proof — FetchSandbox reproduces the bug on your real code and verifies your fix flips it — use `prove_fix` instead.
list_runsRead-onlyList recent workflow runs (and ad-hoc traffic) for a sandbox, newest first. Use when the user asks 'what did I run', 'show me recent validation runs', 'did the stripe test pass earlier', or wants to find a previous run to share or re-inspect. Each run includes its shareable timeline URL (fetchsandbox.com/runs/<sandbox_id>) so the user can open the visual trace in a browser or drop it in Slack / a PR comment. Requires sandbox_id (from import_spec).
list_scenariosRead-onlyList the FAILURE SCENARIOS this sandbox can inject on demand — the specific ways the real provider misbehaves in production. Call this BEFORE claiming an integration works. A checkout that passes on the happy path tells you almost nothing; the bugs that reach customers are declined cards, webhooks delivered twice or out of order, expired tokens, rate limits and slow networks. Typical names: payment_declined, insufficient_funds, webhook_retries, flaky_webhooks, replayed_old_signed_event, signed_event_with_mutated_body, auth_failure, rate_limited, slow_network — but they differ per provider, which is why you list them instead of guessing. Returns each scenario's name and what it does. Arm one with set_scenario, then re-run the same request and check the app still behaves correctly.
set_scenarioActionARM a failure scenario on a sandbox, so the next requests hit the provider misbehaving instead of the happy path. This is how you find out whether the integration you just wrote actually survives production. Use it like this: run the flow once on 'default' and confirm it works, call set_scenario with a failure from list_scenarios, run the SAME flow again, then check the end state is still correct — not that the call merely returned. A declined payment must not produce a confirmed order; a webhook delivered twice must not charge twice or send two emails. Set scenario to 'default' to return the sandbox to normal. The scenario stays armed until you change it, and it affects every caller of that sandbox — so put it back when you are done.
| run_all_workflows | Execute EVERY workflow (or a scoped subset) for a sandbox in ONE call. Use this — NOT a loop of run_workflow — for any validation-style request: "validate this integration", "run all workflows", "check coverage", "test stripe checkout", "fs validate". IDEs (Cursor, Claude Code) approve each MCP call individually, so 18 workflows via run_workflow = 18 clicks. This tool = 1 click, total. Scope via `workflow_names`: pass an array of workflow ids to run a subset (e.g., user says "validate stripe CHECKOUT" → pass ["create_checkout_session", "checkout_complete"]). Names are case-insensitive; dashes and underscores interchangeable. Returns: summary (pass/fail counts, totals) + full step trace per workflow. After running, the user can visit fetchsandbox.com/runs/<sandbox_id> for a shareable visual timeline. | Action |
| 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. | Action |
| 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. | Action |
| submit_proof | Receipts are readable by anyone with the link — do not attach bodies the user would not paste into a public PR. Attach REAL before/after evidence from the USER's actual app to the run receipt. Use this AFTER you've fixed the bug and re-run the app: it makes the receipt show their own code's behavior (before your fix vs after), which is far stronger proof than a reference simulation. Provide one `proofs` entry per probe you fired — the request you sent, the response BEFORE the fix (bug reproduces), and the response AFTER the fix (bug gone) — keyed to the run's sandbox_id + flow_run_id (from run_workflow's result). This is SELF-REPORTED evidence: it's shown on the receipt but never counts as a proven (green) result. For a MEASURED green proof — FetchSandbox reproduces the bug on your real code and verifies your fix flips it — use `prove_fix` instead. | Action |
| list_runs | List recent workflow runs (and ad-hoc traffic) for a sandbox, newest first. Use when the user asks 'what did I run', 'show me recent validation runs', 'did the stripe test pass earlier', or wants to find a previous run to share or re-inspect. Each run includes its shareable timeline URL (fetchsandbox.com/runs/<sandbox_id>) so the user can open the visual trace in a browser or drop it in Slack / a PR comment. Requires sandbox_id (from import_spec). | Read-only |
| list_scenarios | List the FAILURE SCENARIOS this sandbox can inject on demand — the specific ways the real provider misbehaves in production. Call this BEFORE claiming an integration works. A checkout that passes on the happy path tells you almost nothing; the bugs that reach customers are declined cards, webhooks delivered twice or out of order, expired tokens, rate limits and slow networks. Typical names: payment_declined, insufficient_funds, webhook_retries, flaky_webhooks, replayed_old_signed_event, signed_event_with_mutated_body, auth_failure, rate_limited, slow_network — but they differ per provider, which is why you list them instead of guessing. Returns each scenario's name and what it does. Arm one with set_scenario, then re-run the same request and check the app still behaves correctly. | Read-only |
| set_scenario | ARM a failure scenario on a sandbox, so the next requests hit the provider misbehaving instead of the happy path. This is how you find out whether the integration you just wrote actually survives production. Use it like this: run the flow once on 'default' and confirm it works, call set_scenario with a failure from list_scenarios, run the SAME flow again, then check the end state is still correct — not that the call merely returned. A declined payment must not produce a confirmed order; a webhook delivered twice must not charge twice or send two emails. Set scenario to 'default' to return the sandbox to normal. The scenario stays armed until you change it, and it affects every caller of that sandbox — so put it back when you are done. | Action |
Configuration
FETCHSANDBOX_API_KEYSecretSign in using an account API key. Discovery is available anonymously; application planning, verification and managed local tunnels require authentication.
FETCHSANDBOX_BASE_URLOverride the FetchSandbox backend base URL (defaults to https://fetchsandbox.com). Useful for stage/self-hosted testing.
FETCHSANDBOX_TELEMETRYSet to '0' to disable anonymous usage telemetry.
| Name | Description | |
|---|---|---|
| FETCHSANDBOX_API_KEY | Sign in using an account API key. Discovery is available anonymously; application planning, verification and managed local tunnels require authentication. | Secret |
| FETCHSANDBOX_BASE_URL | Override the FetchSandbox backend base URL (defaults to https://fetchsandbox.com). Useful for stage/self-hosted testing. | |
| FETCHSANDBOX_TELEMETRY | Set to '0' to disable anonymous usage telemetry. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubfetchsandbox-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.
| 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] |
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", "fetchsandbox-mcp@0.7.24"],
"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
| 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 |
get_job |
Retrieve the same running job without starting another analysis or proof | job_id* |
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 |
get_job |
Retrieve the same running job without starting another analysis or proof | job_id* |
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, .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 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.
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.
FetchSandbox MCP questions
How do I add FetchSandbox MCP to Claude Code?
Run claude mcp add --env 'FETCHSANDBOX_API_KEY=<YOUR_FETCHSANDBOX_API_KEY>' mcp -- npx -y fetchsandbox-mcp in your terminal. Add --scope user to make it available in every project.
How do I add FetchSandbox MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does FetchSandbox MCP provide?
It exposes 19 tools, including coach, find_bugs, fix_bug, get_job, prove_fix.
How does the server prove a fix works?
It runs the failure against your code both before and after the proposed diff, requiring a 'measured flip' from failure to success to pass.
What happens if I run prove_fix after I have already applied the fix to my files?
The tool will fail to provide proof because it requires the unfixed version of the code to demonstrate the reproduction of the bug.