Intro: the first time I pointed an agent at my own API
I pointed a test agent at the billing API on my hosting platform last year and gave it a simple job: find customers more than two weeks overdue and suspend their VPS. It called the list endpoint, got a 200 with fifty invoices, and stopped. There were 1,340 invoices. Nothing in the response said more rows existed, so the agent had no way to know it was looking at a truncated page. That was my introduction to why agent-friendly APIs are a different design problem than the ones I had spent the previous seven years solving.
The second run went worse. I asked the agent to open a suspension ticket for the accounts it had found, the write timed out at thirty seconds, and the agent retried. I ended up with two tickets for the same customer and a duplicate dunning email that went out at 2am. Nobody noticed for two days. That is the shape of most agent failures I have dealt with since: not a crash, not a 500, just duplicated work that looks like normal activity until you read the rows.
The working premise of this post is that an agent reads your API the way a junior developer with no context and no ability to ask you a question reads it. Every implicit sort order, every undocumented default, every empty 200 where a 404 was meant, is a gap the model fills with a guess. The New Stack’s piece on building scalable, agent-friendly APIs (opens in new tab) makes a similar argument about designing for machine callers rather than human ones, and it matches what I keep finding on my own boxes and in client specs.
I am not covering prompt engineering, model selection, or framework comparisons. None of those fix a pagination contract, and the calls that break in production almost always break at the contract.
Background: what agent-friendly APIs do differently from human-facing REST
Most of what breaks agents is not exotic. It is the set of conventions we all rely on when a human is holding the keyboard.
Take implicit sort order. A human opens a list view, sees records in some order, and if the order looks wrong they sort a column. An agent has no column headers. If your endpoint returns rows in insertion order and the agent asks for “the five most recent suspended accounts,” it will take the first five rows it receives and call it done. Nothing in the response contradicts it. Same with undocumented defaults. A per_page that silently defaults to 25 is invisible unless you read the code, and a model reading a schema that says per_page: integer will assume it got everything.
Then there is the error shape. I have lost count of the times an agent has happily parsed an nginx HTML error page as a successful body because the status code came back 200 through a proxy. A human sees a wall of HTML and knows something is wrong. A model sees text and does its best. If your gateway rewrites a 404 into an empty 200 with [], the agent thinks the resource does not exist and there are zero rows, which are two different facts you have now merged into one.
The MCP question comes up here. Running an MCP server is a wrapper layer: you expose a handful of coarse tools (list_overdue_accounts, suspend_account) and the agent never sees your REST surface at all. That is genuinely useful when credentials have to stay server-side, or when your API has forty endpoints and you only want the model touching four of them. What it costs you is a second interface to keep in sync with the first. Every time the REST API changes, someone has to remember the MCP tool descriptions. If the agent has HTTP access and a good spec, calling REST directly skips that maintenance entirely, at the cost of exposing the full surface.
The documentation surface that actually reaches the model is narrow. It is your OpenAPI spec, and if you run MCP, the one-line tool descriptions you wrote. Nobody reads your docs portal. They read operationId, they read required, they read the example values. If your examples say "string", the model learns nothing.
What is happening now with agent-friendly APIs
A lot of teams are pointing agents at production endpoints that were built for a mobile app in 2021, and the failure mode is not a crash. It is a duplicate write. The agent sends a POST /invoices, the connection times out at 30 seconds because the database is doing a slow fsync, the agent retries with no idempotency key, and now the customer has two invoices and a confused support ticket. The New Stack’s piece on building scalable, agent-friendly APIs for AI applications (opens in new tab) makes the same point about retries being the normal outcome of a slow write rather than an edge case, and that framing changes how you read your own logs. Your 2019 spike in duplicate orders was probably not a client bug.
The second shift is quieter. OpenAPI specs are being fed into prompt context now, which means spec hygiene that was cosmetic two years ago is load-bearing today. I have seen spec files where every response reuses one GenericResponse schema with no required fields, because the docs portal rendered fine and nobody complained. A model reading that spec has no way to know that id is always present and next_cursor sometimes is. It will guess, and it will guess wrong on the one field that mattered. Teams that wrote their spec for a Swagger UI page in 2019 are now discovering that the same file is being read as instructions.
Rate limiting is the third place this shows up, and it is the one I run into on my own boxes. Limits tuned for browser sessions assume a human who clicks, waits, and gets bored. A cron job hits you on a predictable schedule, once. An agent that gets a bare 429 with no Retry-After header will often retry immediately, and then again, because nothing in the response told it that waiting was the correct action. You end up rate limiting your own best-behaved automation into a hot loop.
None of this is exotic. It is ordinary REST meeting callers that never read your changelog.
What makes agent-friendly APIs different from normal REST?
The honest answer is that agent-friendly APIs are not a different protocol. They are the same REST you already have, with the implicit parts written down. Every convention you left for a human to infer from context is a place an agent invents its own answer, and it will not tell you which answer it picked. Four questions come up often enough that I have a stock response for each.
Do I need to adopt MCP to be agent-friendly? No. If the agent has HTTP access and your spec, it can call your endpoints directly, and that is the cheapest thing to maintain because there is no new service to run. MCP earns its keep in two situations: when credentials have to stay server-side so the model never sees the token, and when you would rather expose five coarse tools than forty fine-grained endpoints. Wrapping REST in MCP because it is the current fashion adds a component for you to page about at 3am without changing what the model can actually do.
How should I paginate? Cursor tokens, returned in the JSON body as next_cursor, set to null on the final page. Agents skip Link headers often enough that relying on them is a bet you will lose. The null matters as much as the token, because it is the only signal that the dataset ended. Without it the agent guesses, and the guess is usually that it received everything.
What belongs in an error response? A stable machine-readable code, a message short enough for a model to act on, and a retryable boolean. A 429 with no Retry-After is a dead end. The agent knows the call failed, not whether to wait or give up, so it retries immediately. That is how you get the hot loop I described above.
Can I skip idempotency keys if I only accept POST? That is precisely where they matter. A write that times out is a normal outcome on a slow endpoint, and the client’s only reasonable move is to send the request again. Without a key, the second send creates the second row, and you find out when a customer gets billed twice.
None of this needs a new framework. It needs a decision, made once, about what your API says when it is unsure, and then the discipline to write that decision into the spec instead of leaving it in someone’s head.
What agent-friendly APIs look like in practice
Start with the write path. Every POST that creates or mutates something should accept an Idempotency-Key header, and your spec needs to state how long you keep that key. Twenty-four hours is the common choice. Mine is 48, because a retry storm during a billing run can outlast a single support shift, and rediscovering the same request the next morning is worse than the storage it costs.
Two behaviours matter when a key repeats. If the original request is still running when the second arrives, return 409 Conflict with a body that says the first is in flight and links to a status endpoint. A bare 409 leaves the agent guessing, so it either hammers you or marks the write as failed when it actually succeeded. If the original already finished, replay the stored response with its original status code. Same key, same body, no new row.
Rate limit headers are the other half of this. X-RateLimit-Limit, X-RateLimit-Remaining, and a Retry-After on the 429. The bare number tells the agent nothing about what to do next, which is how you end up with a hot loop on a call that cannot succeed yet. Per-key budgets matter as much. A runaway loop should burn its own quota, not the shared pool. I watched a single misconfigured cron on one customer’s VPS drain a global limit for every other tenant for about forty minutes, and the fix afterwards was moving every limit to be tracked per key.
OpenAPI hygiene now pays off twice, once in the docs portal and once as context the model reads before it calls anything. operationId: createInvoice maps to intent in a way that post_invoices_v2 does not. Set required on the fields that genuinely are required, because a model will happily omit a mandatory argument and then act surprised at the 422. Swap "string" in your examples for something real. If your example email is "[email protected]" the model learns more than if it is "string".
Batch endpoints need the same treatment. When three of ten items fail, return per-item status objects instead of one flat 200. A single success code that hides three failures gets reported to a human as “done”, and someone reconciles the database by hand an hour later.
What to expect next
MCP server design will settle into something closer to a plugin contract than the loose collection of servers people are spinning up today. I do not know whether that contract standardises on JSON Schema or drifts into per-vendor shapes, and anyone telling you they know is guessing. My expectation is that the schema side converges, because most of us are generating tool definitions from the same OpenAPI tooling already, while the auth side stays fragmented for a while longer. If you are writing an MCP server now, keep the tool definitions thin and the business logic in your existing HTTP layer so a shift in the contract costs you a wrapper, not a rewrite.
Auth for agents is the genuinely unsolved part. Long-lived API keys pasted into a config file or an environment variable is what most teams will ship first, and I would probably ship the same thing this week, because it works immediately and a browser redirect flow is miserable inside an agent loop. That is a problem more than a strategy. A key that never expires and carries full account scope means a prompt injection has the blast radius of a compromised admin account. I expect scoped, short-lived tokens to become normal, but I would not wait for the tooling to force the change. Write down what each key is allowed to do, even if it is a comment in a config file, and give the agent a key that cannot delete anything.
Spend controls will move into the API layer itself. A looping agent with a valid key is a billing incident waiting for a quiet weekend, and “watch the dashboard” fails at three in the morning. Per-key spend caps, a hard ceiling on write volume, and an alert when one key’s call rate triples its own seven day baseline are worth more than a nicer SDK. On my own hosting billing API, a runaway loop against a metered endpoint is not hypothetical. It happened on a Tuesday, and I found out from the invoice rather than the monitoring.
Versioning will get messier too. Agents cache your spec in context, so a breaking change you roll out on a Friday can keep getting called the old way for days by a client you cannot see and did not deploy.
Closing: pick one endpoint and make it agent-ready this week
Everything above is easier to argue about than to ship, so pick one endpoint. Not the whole API. The write endpoint your agent calls most often, the one that creates a record or opens a ticket or provisions something. If you have any request metrics, sort by write volume and take the top result.
Add the idempotency key requirement first. It is the smallest diff with the largest payoff. Accept the key as a header, store it against the response you already returned, and reject a replay that arrives while the original is still in flight with a 409 instead of processing it twice. Then test it the boring way:
curl -X POST https://api.example.com/v1/orders \
-H "Idempotency-Key: 8f14e45f-a1b2-4c3d-9e7f-000000000001" \
-H "Content-Type: application/json" \
-d '{"sku":"VPS-2GB","region":"blr1"}'
Run that twice without changing the key. If the second call creates a second order, you have a bug that will surface as a duplicate charge the first time a model retries after a gateway timeout, and it will surface at whatever hour you are least able to fix it. If the second call returns the original response body with the same order ID, the contract holds and you can move on.
Then point an agent at it and read the transcript. Not the access logs, the transcript: the sequence of calls plus whatever reasoning got printed between them. Watching a model hit your list endpoint and quietly decide that one page is the whole dataset is instructive in a way a design doc never is, because you get to see which field it treated as the end signal, and where it ignored your Link header without ever saying so. Ten minutes of that beats a week of redesign meetings.
Fix one thing from what you read. Pagination is usually where the guessing starts, so start there and return an explicit next_cursor that goes null on the final page. Then put the contract you just enforced into your OpenAPI spec, in the response schema, not in a prose description, so the next agent inherits the rule instead of rediscovering it on your production database.