Why coding agents invent endpoints you never shipped
An agent asked to integrate your API will recite one it saw in training or guess from the name. Both produce code that looks right and does not run. The fix is not a better prompt.
Ask a coding agent to integrate your API and watch what it writes. If your product is well known, it will produce a confident, plausible, subtly outdated client based on the version of your API that was in its training data. If your product is not well known, it will invent one from the name.
Both failures look identical from the outside: clean code, correct-looking method names, imports that resolve. It does not run.
This gets read as a model problem, and people respond with prompt engineering. It is not a model problem. The agent was asked a question about a system it cannot see, so it answered from memory. Any of us would.
Two failure modes, one cause
Recall. Your API was in the training data at some version. The agent reproduces that version. Every field you renamed since, every endpoint you deprecated, every parameter you made required is wrong in a way that is invisible to a reviewer who does not already know your API by heart. This is the more dangerous failure, because the output is high quality. It was correct once.
Invention. Your API was not in the training data, so the agent reasons from the name. An API called Payments gets POST /payments taking amount and currency, because that is what such an API usually looks like. Sometimes it is right, which is worse than always being wrong, because it teaches the reviewer to trust it.
Neither improves with a better prompt. You can tell a model to be careful, and a careful model still cannot read a document it has not been given.
Pasting the spec is not the fix either
The obvious answer is to hand the agent your OpenAPI document. This works for small APIs and stops working at exactly the point it matters.
A real spec is large. Stripe's is over a megabyte. Dropping it into context costs a fortune, crowds out everything else the agent needs to hold, and puts the agent in the position of parsing JSON to answer a question about one endpoint. You also get one snapshot: the moment you publish a change, the pasted copy is stale and nothing tells anybody.
The version people actually run is worse still, which is pasting the parts of the spec you thought were relevant. Now the agent has your API with the pagination envelope missing, and it invents that instead.
What changes when the agent can look things up
The Model Context Protocol exists for this shape of problem. The agent does not receive your API. It receives the ability to ask about it, and it asks the questions it needs while it works.
That distinction does more than it sounds like. An agent with retrieval over your documentation searches for the endpoint it needs, reads that endpoint in full with every parameter, checks the changelog when it hits something that looks like a version difference, and gets your written guides for the parts that are conventions rather than schemas. It pays for what it reads instead of paying for the whole document up front.
The tool that changes the output most is the one that returns the real call in your own SDK, for one endpoint or all of them, in whichever language the agent is writing. The agent stops constructing HTTP requests from a schema and starts writing your client library, with your method names, in the shape your users actually install. It writes client.invoices.create(...) because it looked up what that method is called, not because invoices.create is a plausible name for it.
And because the tools read your published documentation rather than a snapshot, a spec change that updates your docs updates what the agent sees. There is no rebuild step and nothing to keep in sync.
Reading is half of it
The other half is that the agent can call your API rather than guessing what a call returns.
Each endpoint you expose becomes a callable tool. An agent integrating your API can make a real request against a real environment and read a real response, which collapses the loop between writing code and finding out whether the code was right.
This is the point where the honest version of this post has to slow down, because that capability is genuinely dangerous and the marketing version of this argument does not mention it.
An operation tool is not a preview. A call hits your live API with the credentials you configured, and a write endpoint writes. An agent exploring your API in a loop is an agent issuing real requests in a loop. Point it at staging while you evaluate. If an endpoint should never be reachable by an agent, exclude it, and then no tool exists for it at all rather than existing and being politely declined.
The useful default is that the exclusion list you already wrote for your public SDK is usually the right permission list for an agent. An endpoint that does not belong in a client library rarely belongs in an agent's hands either.
What this does not fix
An agent reading your documentation is bounded by your documentation. If an endpoint is undocumented, has no description and returns an untyped object, the agent gets exactly what a human integrator gets, which is a name and a shrug. Wiring up MCP does not upgrade a thin spec; it removes the excuse that the agent could not see it.
That is the part worth taking seriously if you are evaluating this. The failure mode moves from "the agent invented an endpoint" to "the agent used the endpoint correctly and could not tell what the response meant". The second is a better problem, and it is still a problem, and it is yours.
Our spec audit scores a document on those grounds and publishes every rule it checks. Operations with no summary, responses with no schema and parameters with no description are the three that decide what an agent can do with your API, and they are the three most specs fail.
The short version
Agents invent endpoints because they are answering from memory about a system they cannot inspect. Give them a way to inspect it and the invention stops, on the condition that there is something worth reading when they look.
If you want the mechanics, generating an MCP server from an OpenAPI spec covers the setup, the environment variables, and the part about pointing it at staging before you point it at production.
