From a scanned spec to mocks, scenario tests, and an MCP server
The scan produced a three-thousand-line OpenAPI document for a service we did not write. A document nobody exercises is just a slower wiki, so the same afternoon we put it to work in three places: a mock for teams blocked on us, scenario tests against staging, and an MCP server for the internal agents people were already building.
Tighten the spec where it pays off
Before any of that, spend twenty minutes on the operations that matter. The AST scan reconstructs structure — paths, methods, parameters, schemas — but it cannot know that status: 7 means "awaiting manager approval" or that POST /refunds is idempotent. Add descriptions and, more importantly, examples to the ten endpoints your consumers actually call. Examples are not documentation decoration: they become mock responses, scenario assertions, and the first thing an AI caller reads.
Start a mock from the spec
The mobile team was blocked on two endpoints still being rewritten. Instead of handing them a JSON file and a prayer, start the built-in mock server from the workspace. It answers real HTTP on a local port using the examples and response schemas in the document, so the mobile app compiles against the actual contract — same paths, same field names, same status codes — rather than a hand-maintained fake that drifts on the first hotfix.
Mocks earn their keep again when reproducing a partner bug. A partner reported that their import job silently dropped records on 409. We reproduced the exact response sequence from the spec, handed them a deterministic endpoint to test against, and fixed their retry logic without touching staging traffic. When the backend is ready, switching the environment is a dropdown change, not a code change.
Run the business scenario, not one request
A single green request proves a route exists. It does not prove the workflow works. The scenario runner chains real calls and passes data between steps:
| Step | Request | What gets carried forward |
|---|---|---|
| 1 | POST /auth/token | Access token into the environment's auth state |
| 2 | POST /projects | The new projectId from the response body |
| 3 | GET /projects/{projectId} | Asserts the created resource reads back correctly |
| 4 | POST /projects/{projectId}/compare | Asserts 200 plus the response schema |
| 5 | DELETE /projects/{projectId} | Asserts the terminal state, not just a 200 |
Pre-request scripts handle signing and token refresh; environments separate localhost, staging, and production variables; assertions check status codes and response shapes rather than eyeballed JSON. This is where the scanned spec found its first real bug: the create call returned 201, the immediate read returned 404 because of a replication delay nobody modeled, and the client had no retry. No single-request test would ever catch that. We wrote about that failure mode in a 200 is not done.
Scenarios export as reports for the ticket, and the run-host guide gives CI a one-command way to execute the same chain on every pull request. Contract verification stops being a release-eve ritual.
Serve the spec as an MCP server
Meanwhile, three teams had independently started pasting API docs into coding agents and getting subtly wrong calls — limit versus pageSize, data.records versus data.items, amounts in dollars versus cents. The fix is not a better prompt; it is letting the agent query the contract. Serving the workspace spec as an MCP server turns the operations into tools and the schemas into structured descriptions the agent cannot paraphrase away.
Start read-only. Expose the list and detail operations first, verify an agent can fetch an order and answer a question from the real response, and widen the surface deliberately. Write operations deserve their own permission and confirmation pass — MCP solves discovery and transport; it does not replace the service's authorization. For internal desktop use the local runtime is enough; for partners and hosted agents, publish the same document through Powerduck Cloud with access control and versioning, which also hosts the human-facing documentation. One document, both audiences — we made that case in detail here, and the mechanics of exposing a subset of endpoints live in the MCP server as a build artifact.
The loop that keeps it honest
The workflow only stays accurate if it is cheap to repeat. Code changes during the sprint; rescan the folder, review the diff against the sidecar, merge the new routes, and the mock, scenarios, docs, and MCP server all derive from the updated document on the next run. The spec is no longer a snapshot taken at launch and abandoned — it is rebuilt from the code the team actually ships, and every downstream consumer updates from the same source.
That covers services that already exist. The other half of the job happens before any code does — designing the contract first, with AI doing the drafting.