Ask an AI coding assistant to build an order list page and the UI appears in seconds. Then you run it:

  • The pagination param is pageSize. The API expects limit.
  • The code reads data.items. The server returns data.records.
  • Money is rendered as yuan. The contract stores amounts in cents.

You paste the API docs into the chat, it fixes everything, and you move on. Three days later, in a new session (or a different assistant), you are explaining the same fields all over again.

The faster an AI writes code, the faster wrong assumptions about your API get spread across the codebase. The fix is not a better prompt. It's giving the assistant a single source of truth it can query, instead of relying on whatever you happened to paste.

The failure is context, not intelligence

Here is the actual loop most teams run:

you:   paste a 400-line doc dump
AI:    writes code against that snapshot
API:   a field changes
you:   paste the doc again, hoping the model remembers
AI:    fixes this task, forgets the next one

The doc in the chat is a copy. Copies drift, get truncated by context windows, and don't survive a new conversation. Your API contract, meanwhile, already has a canonical home — an OpenAPI file. The problem is purely that the assistant can't reach it on demand.

MCP (Model Context Protocol) is the boring, practical answer: it's a standard way for an AI client to call external tools. Point an MCP server at your OpenAPI spec and the assistant stops guessing — it can look the contract up the same way a teammate would.

What "query, don't paste" looks like

A development MCP server exposes your spec as a small set of tools. The conversation changes from "here is everything, remember it" to "go look up what you need":

  1. List operations that match a keyword (order, refund).
  2. Read one operation — method, path, parameters, request body, responses, auth.
  3. Resolve a shared schema when the response references a component.
  4. Optionally send a real request and run a contract check against it.

The assistant fetches only the slice it needs for the current task, so context stays small and accurate. When the spec changes, the next query returns the new truth — no re-pasting, no "use the version I sent last Tuesday."

Rewrite the task prompt to enforce the order of operations:

First query the order-list operation through MCP. Confirm the pagination parameter, the response envelope, and the monetary unit before writing any code. If the spec doesn't state something, list it as an open question — do not assume.

That last sentence is the whole game. If the spec never says whether amounts are cents or yuan, MCP can't invent the answer — but the gap surfaces before code is written, where fixing it is a one-line spec edit instead of a production bug. You update the OpenAPI file, save it, and every future query sees the correction.

"Reads the spec" and "implements the spec" are two different skills

Knowing the shape of a response doesn't mean the implementation actually returns it. This is where most AI-generated code gives a false sense of completion: a 200 OK on one happy-path request gets reported as "done."

The same development MCP can drive multi-step scenarios with variables and assertions. For an order flow:

1. POST /orders                      -> create an order
2. extract orderId from the response  -> carry it forward
3. GET  /orders/{orderId}            -> assert the record matches
4. POST /orders/{orderId}/cancel     -> cancel it
5. GET  /orders/{orderId}            -> assert the final status is "cancelled"

The details that matter:

  • Step 3 uses the id from step 2, not a hard-coded sample.
  • The final assertion checks the state after cancellation, not merely that the cancel call returned 200.
  • A failed step produces concrete evidence — the actual response and the unmet assertion — which the assistant uses to keep debugging.

That turns "the code is finished" into a tight loop:

read contract -> implement -> run scenario -> inspect the failure -> fix

For teams that want this in CI rather than an interactive client, the same contract can be batch-tested with a CLI across HTTP, SSE, WebSocket, GraphQL, gRPC and MCP — so the spec that the AI reads is the same spec your pipeline enforces.

When the backend isn't ready, mock the contract, not the UI

A common workaround for a missing dependency is to hard-code fake objects in components. It demos well, then everything gets rewritten when the real service lands — paths, error branches, request shapes.

If the contract is already agreed, the missing implementation shouldn't block front-end work. Serve example- or schema-based responses from a local mock so the front end still sends real HTTP requests to the agreed paths and shapes, just pointed at localhost. Through the development MCP, the assistant can start the mock, inspect captured requests, and deliberately inject failures:

  • return an empty list and check the empty state has a next step;
  • return the documented business error and check the message is preserved;
  • return a 503 from the coupon service and check the spinner actually stops and input is retained.

You're testing the unhappy path on purpose, before the dependency exists. When the real service ships, you repoint the base URL and re-run the same scenarios.

Local-first file, model-agnostic context

One subtle benefit: the source of truth is a local OpenAPI file in your repo. It gets reviewed in pull requests, diffed, and rolled back like any other code. It is not trapped in one vendor's chat history — switch assistants, models, or IDEs and the project context comes along because it lives in the MCP server, not the conversation.

One boundary to be explicit about: local-first describes where the file lives, not where data goes. When you use a cloud model, the slices the assistant queries are sent to that model as context. Pick the model and the scope of what you expose according to your own requirements; the tool doesn't have to send your whole spec anywhere.

Start with one prompt

You don't have to redesign your workflow. On your next API-adjacent task, change the first sentence from "write the code" to:

"Query the actual API contract first, then implement, and list anything the spec doesn't prove."

That single reordering — contract before code — removes most of the silent integration bugs AI coding produces, and it compounds: every gap you close in the spec makes the next assistant, and the next teammate, faster.

You can wire a development MCP server to a local OpenAPI file and try the loop — list an operation, read its schema, run a request — in the free app at powerduck.com/app. If your API already exists as code rather than a spec, generate the starting OpenAPI deterministically with @powerduck/code-to-openapi.

What's the most common wrong assumption your AI assistant makes about your API — pagination names, response envelopes, or units? I'd bet it's one of those three.