Here is a story most API teams know by heart. A new endpoint ships on Friday. Someone adds it to the Postman collection. Someone else updates the mock for the mobile team. The reference docs get edited next sprint, maybe. And when an engineer wires up an AI agent, they hand-build an MCP tool description from memory of how the endpoint used to work.

Three weeks later, the collection, the mock, the docs and the agent all disagree. Nobody trusts any of them, so every integration starts with "wait, what does this endpoint actually return?"

The root cause is tool sprawl, not discipline

The usual fix is a spreadsheet of ownership rules and a calendar of sync meetings. It never sticks, because the information lives in five stores with five formats. The spec is treated as documentation — an artifact generated after the work — instead of the working file the work happens in.

Powerduck flips that around. One local OpenAPI document is the single source of truth, and every other artifact is a view or a projection of it:

  • Debug requests are generated from the operations in the spec, and a quick request that proves useful can be promoted back into the spec in one action.
  • Tests and scenarios assert against the same schemas and examples the spec defines.
  • Mocks answer from the spec's responses, so a changed schema changes the mock automatically.
  • Documentation renders from the file, locally or hosted.
  • MCP tools are served straight from the operations, so AI agents call the same contract your frontend does.

A day in the one-spec workflow

Imagine adding POST /v1/refunds. You describe the intent to the built-in AI assistant, and it drafts the operation, request schema, error responses and examples directly in the spec. You review the diff — every proposal is a reversible patch — and apply it. Immediately:

  • the operation appears in the API navigator, ready to send with generated example bodies;
  • the mock starts accepting refunds with realistic responses;
  • the docs page exists;
  • the MCP server exposes a create_refund tool.

No copy-paste, no second editor, no meeting. The file moved once, and everything derived from it moved with it.

Local first, not locked in

The spec is a plain YAML or JSON file on your machine. It works offline, survives a vendor outage, diffs cleanly in git, and never requires an account to open in the desktop app. When you do want hosted documentation or a shared MCP endpoint, Powerduck Cloud publishes the same file — it is a deployment target, not where your work lives.

Start the habit this week

Pick one service whose Postman collection has quietly become the real spec. Import it (Postman, cURL, an existing OpenAPI file, or a Git URL all work), and make the next change in the spec first. The moment the debug request, the mock and the docs all update together is the moment the drift ends.

One local OpenAPI spec. Everything else follows from it.