stuntman / providers / openapi
OpenAPI
Give Stuntman the provider's OpenAPI or Swagger spec and it answers like the API: routes, answers, schema checks and the token route.
Stands in for
- OpenAPI 3.0 and 3.1
- Swagger 2.0
- JSON or YAML specs with $ref files
- OAuth2 client-credentials token URLs
- OpenAPI webhooks and callbacks
Everything OpenAPI gives you
- 01
A route per operation
Each path and method becomes a route with the server's base path in front; the operationId is kept.
- 02
Answers from the spec
The lowest 2xx is the default; every other response becomes a named answer like payment_required or not_found.
- 03
Built when no example
From the schema: ids that change per call, now() for date-time, and fields that echo what the app sent.
- 04
Bodies checked
Types, required, enums, allOf, oneOf, additionalProperties: false and date, date-time, email formats; a bad body gets the spec's 400 or 422.
- 05
Token route included
OAuth2 client credentials in the spec add a token route at its tokenUrl; routes using it require a Bearer token.
- 06
Webhooks ready to send
3.1 webhooks and 3.0 callbacks become webhook_<name> answers holding their payloads.
- 07
The spec served back
Kept with the files its $refs point to, so clients generated from it work unchanged.
- 08
Re-import keeps edits
A new version adds routes; your steps, answers, data and settings stay. Routes it lacks are listed in notInSpec.
The screens
Each number is a control or a reading on the real screen. Everything you can click there, your agent can do with a tool.
A new service from a spec

OpenAPI 3.x, Swagger 2.0 or a WSDL; Stuntman tells which one it is.
Files the spec points to with $ref are read too.
A body that breaks the schema gets the provider's 400 error.
Every route with the responses it declares, before anything is created.
Client credentials on /oauth/token, any client accepted until you add some.
- Start from a spec
OpenAPI 3.x, Swagger 2.0 or a WSDL; Stuntman tells which one it is.
- URL or file
Files the spec points to with $ref are read too.
- Check bodies
A body that breaks the schema gets the provider's 400 error.
- What the spec has
Every route with the responses it declares, before anything is created.
- OAuth from securitySchemes
Client credentials on /oauth/token, any client accepted until you add some.
Routes made from the spec are normal routes

One per operation, with calls today.
Bearer token from /oauth/token; the body is checked against ChargeRequest, else the invalid answer.
Rules you add pick the spec's other responses: a card ending 0002 gets 402.
Reads a new version and keeps your steps; the served spec is one click away.
A call to a path the spec does not have shows in Unmatched.
- Routes from the spec
One per operation, with calls today.
- Receive
Bearer token from /oauth/token; the body is checked against ChargeRequest, else the invalid answer.
- Decide
Rules you add pick the spec's other responses: a card ending 0002 gets 402.
- Re-import the spec
Reads a new version and keeps your steps; the served spec is one click away.
- Path it lacks
A call to a path the spec does not have shows in Unmatched.
Answers from the spec's responses

Marked example (the spec's example) or schema (built from the schema).
Edit an answer to match the real provider, or go back to what the spec said.
The body is a template checked against the response schema.
What the call leaves on the timeline, as a template.
Status, headers and body, filled from the last call.
- One per response
Marked example (the spec's example) or schema (built from the schema).
- Reset to the spec
Edit an answer to match the real provider, or go back to what the spec said.
- Checked against the schema
The body is a template checked against the response schema.
- Timeline sentence
What the call leaves on the timeline, as a template.
- What the app gets
Status, headers and body, filled from the last call.
Break it on purpose
The failures you need to test, exactly when you ask: from the screen or by a tool call, each one shown on the timeline with who caused it.
Any declared response402, 404, 409 or any response the spec declares, on the next calls
force_answer payment_requiredValidation errorA body that breaks the schema gets the spec's 400 or 422 naming the field
send a bad bodyExpired tokenEvery token becomes invalid; the next call gets 401
expire_tokensMissing tokenA route that uses the OAuth scheme refuses a call without Bearer
call without a tokenUndeclared responseAn answer the spec does not have
set_answerNetwork and server failuresReset, empty, timeout, 500, 503 or an HTML page
force_answerSlow or flakyLatency on every answer, or a random share of failures
set_service latency, fail_sharePath not in the specThe app calls a version the spec lacks; it answers 404 no route
list_unmatched
Why not the real sandbox
Right on the first call
A 201 that echoes the amount and currency the app sent, without writing a line.
Every response reachable
Responses a sandbox rarely returns come on cue: 402, 409, 422, 503.
Contract drift caught
Bodies that break the schema are refused, and calls to paths the spec lacks are listed.
Follows new versions
Re-import the provider's new spec without losing the rules you added.
Your AI agent drives it
Claude Code, Codex or any MCP client connects to /mcp (or calls /api over plain HTTP), sets the stand-in up, breaks it on cue and reads what your app did.
Stand in for the payments API from its OpenAPI spec and test a declined card at checkout.
MCP tools
import_specA service from OpenAPI 3.x, Swagger 2.0 or a WSDLreimport_specReads the spec again and keeps your stepslist_answersNamed answers and which route uses eachset_answerCreates or replaces a named answerset_routeCreates or replaces a routetry_routeRuns a route on a sample requestforce_answerThe next calls get a named answerexpire_tokensEvery token becomes invalidlist_unmatchedCalls to paths no route takes
The same over HTTP
- POST
/api/plugins/spec - POST
/api/plugins/{service}/spec - GET
/api/plugins/{service}/answers - POST
/api/plugins/{service}/try - POST
/api/plugins/{service}/tokens/expire
- Only JSON bodies are checked; pattern, lengths, numeric ranges and discriminator are not. Path, query and headers are not checked.
- API keys and OAuth flows other than client credentials are not checked.