io.github.fetchsandbox/mcp

Tools

• 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: (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. The state machine is server-side — DON'T try to predict the next step or skip ahead; let the server drive.

  shallow
• find_bugs

  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.

  shallow
• fix_bug

  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, so review the diff and apply it yourself. IMPORTANT: the diff is a proposal, not a proof. After applying it, prove the fix (submit_proof / verify_behavior) so the buggy→fixed flip is measured, not assumed. Runs for up to a few minutes.

  shallow
• 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.

  shallow
• 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.

  shallow
• import_spec

  Ingest an OpenAPI spec and get a working sandbox you can call immediately. REQUIRED: pass EITHER `url` OR `content` — never just `name` alone (name is a display label, not a lookup). If the user mentions a popular API by name (Stripe, GitHub, Twilio, Notion, OpenAI, etc.), FIRST call `list_specs` with a filter to confirm it's in the catalog, then call import_spec with that vendor's public OpenAPI URL (e.g. Stripe: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json). The backend content-hashes the spec and auto-matches to the bundled sandbox when applicable. Returns sandbox_id, workflows_preview, and a base_url that proxies schema-validated responses. Private URLs (localhost, 10.x, 192.168.x) are rejected by the backend — use `content` to paste those inline.

  shallow
• 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).

  shallow
• 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.

  shallow
• 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).

  shallow
• list_workflows

  List the named, runnable workflows for a previously-imported spec. Workflows are realistic multi-step API journeys (e.g. 'create customer → attach payment method → create subscription'). Use this after import_spec 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. Returns the workflows AND the failure scenarios this spec can simulate — each with a plain description and the exact call to run it. Read the scenarios out to the user and ask which matter; do not guess scenario names.

  shallow
• prove_fix

  THE PROOF STEP. The only way to establish that a fix actually works, and the only thing that produces a shareable 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, against real provider behaviour. 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.

  shallow
• quickrun

  Run a curated proof 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. This is the normal path when the user is testing an integration with a well-known provider: 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 prove the fix — plus a receipt URL. Use run_workflow instead ONLY when you already hold a sandbox_id from import_spec of a custom/private spec.

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• 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.

  shallow
• validate_integration

  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. 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. 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. For every app, inspect capabilities and application_actions. 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. Send application_context with the original goal and inspected workflow to obtain model-proposed rules, missing observations and fixture requirements. Proposals are not executed checks. Preserve all proposed rules in the coverage report, even when unsupported. 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 normal HTTP app workflow with independently readable state, configure application_workflow_v1 and application_config. Declare a positive baseline first, normal app actions, GET observations and required exact assertions. Reuse the proposed rule IDs; omitted rules remain unmeasured. Signed callback app_response contains a sanitized acknowledgement; response remains delivery metadata. Inspect response_capture_status when the body is missing, and independently read state for the verdict. Signed provider event actions are supported through event_destinations and isolated secure-handoff signing secrets; bind payload identity to actual app responses and verify saved state. No browser, arbitrary auth-header or SQL execution is supported by this HTTP contract: record those gaps explicitly. Do not weaken signature or access checks to make a test pass. Start a validation session for the user's integration. quickrun and run_workflow execute OUR curated workflow against a twin — green there says the provider behaves as documented, and says nothing about whether their integration wired to it correctly. This instead hands back a FRESH twin per provider and asks the user to point their app at it, then reads external provider traffic. Direct agent calls also appear there; caller identity is not established. Use it when someone wants their integration verified before launch. Call once with `providers`, then follow the returned `next_action`. Inspect the app and supply a complete `receipt_config` before configuring the suite; the application suite drives its own purchases and webhooks, so do not ask the user to run a manual flow first. The matrix is returned before any traffic: pass `arm` with a probe ID before exercising the app. Send the returned request_headers on every provider request in that attempt, then pass `probe` and `run_id` to evaluate. Use `cancel: true` with `run_id` to abort or retry failed cleanup. Request logs alone do not prove application state or production readiness. For a supported payment-to-receipt integration, follow the structured `next_action`; call `next_tool_call` only when it is non-null and its arguments are complete. Never execute while host-side setup is pending. Do not substitute guide, quickrun, list_workflows, or reference probes for application verification. Use the widest suite the server recommends. receipt_recovery_v1 includes R1-R4 and adds checks R5-R8 for accepted-send response loss, concurrent redelivery, source/email transient failures and delayed redelivery. Pass suite plus receipt_config with the app's exact webhook URL, test recipients and observable purchase marker. FetchSandbox freezes all four receipt rules for both same-customer and different-customer purchases. You are responsible for completing this setup: treat the target as a disposable test app, not the user's live production service, until its declared suite passes. For a greenfield app, keep live billing disabled and publish a temporary test build first to obtain its stable public origin. Use the published webhook URL, not a private preview URL. Inspect the app and identify the exact webhook route before suite configuration. Before requesting or applying test secrets, send an unsigned POST to that exact URL from outside the workspace; a 400 signature rejection is expected, while a 307/login redirect is a blocker. Keep signature validation enabled. After the successful preflight, configure the suite with its complete receipt_config. Apply the returned twin URLs, X-Flow-Run-Id, and three temporary credentials only to this disposable app; execute only after the host-side setup actions are complete. The credentials are twin-only test values: PADDLE_API_KEY, RESEND_API_KEY, and PADDLE_WEBHOOK_SECRET. Use the platform's supported secret store or secret-writing tool and never use real provider credentials or enable live billing. After every required check is held, remove only the test secrets and twin config this run added, including from the disposable test app's published scope. Never modify a separate live production app or delete pre-existing, shared, or real-provider values. Confirm the temporary names are absent, then hand the app to its owner to configure separate development/staging credentials. If the suite is failing or inconclusive, retain test config for repair and a fresh run. The configure_app response contains public twin URLs/IDs and a secret_handoff_url, never the secret values themselves. If the host exposes no safe way for you to write test secrets, explain that specific limitation and show the human the link to open while signed in to the owning FetchSandbox account; they can copy the three values directly into the platform secret store. Do not ask the human to discover endpoints, call FetchSandbox manually, or paste secret values into chat, project files, or logs. Wait for confirmation only when the human must complete that secure-store action. Then call execute:true with its run_id. FetchSandbox drives signed events and independently observes accepted email records. Keep every check and the observation windows in your report. Restore any temporary host privacy setting after the test. On an inconclusive execute result, inspect and report its `execution_diagnostics` field directly; do not ask the human to infer a cause from the public receipt page, which intentionally omits private proof. If you cannot configure the app, report that blocker; reference tests cannot replace app execution. A verified receipt suite covers only its declared rules and windows, never all production behavior. A missing or untriggered recovery fault stays unmeasured. This application suite requires sign-in. Paddle checkout is a separate app-owned browser flow: if a transaction's `checkout.url` points to `fetchsandbox.com/checkout`, returns 404, or does not show a checkout page, do not imply FetchSandbox hosts the merchant's payment UI. Inspect the exact URL and the Paddle Sandbox default payment link or per-transaction override. Tell the builder to use a reachable app checkout page that loads Paddle.js and opens the `_ptxn` transaction, or a supported Paddle-hosted flow. Verify browser checkout/payment separately from twin API and webhook tests; transaction creation alone is not payment proof.

  shallow
• 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 — apply the brain's fix_pattern to inherit the proven behavior.

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/65aa1aeb-2687-4361-93f0-ff0e74064442/badge.svg)](https://vouch.tools/servers/65aa1aeb-2687-4361-93f0-ff0e74064442)