The API Is the Product
API design has always been product work. AI didn't change the rules — it made the cost of breaking them itemised, immediate, and often silent.
On 23 March I shipped cxpak v1.0.0. The capstone was cxpak_auto_context — a deterministic pipeline that indexes a codebase across forty-two languages and delivers task-scoped context to an LLM in a single call. It was the feature the whole project had been building towards since the first overview command in v0.4.0.
I committed to stable semver on the MCP API the same day. Tool names, required parameters, response shapes — stable in 1.x.
Six weeks and four minor releases later, I know exactly which parts of that commitment I’d rewrite if I could.
The AutoContextResult envelope, for one. By v1.2.0 I was adding compound-intelligence fields — health, risks, architecture, co-changes, recent changes — as required fields on the response, which is a silent breaking change for any client doing strict deserialisation. By v1.4.0 I had learned the lesson and the new predictions field shipped as Option<>. The evolution inside a stable tool is doing gymnastics the stable-semver commitment never anticipated. I’d unwind half of it if I could.
API design has always been a product decision. What AI did was make every bad one visible, every permanent one expensive, and every shortcut compound — quietly, in the background.
The MCP walkback
About twenty months ago, Anthropic launched the Model Context Protocol as the answer to tool-design chaos. Through 2025 it consolidated fast — OpenAI, Google, Microsoft and GitHub all adopted it. By December 2025 Anthropic had donated it to the Linux Foundation’s Agentic AI Foundation, co-founded with Block and OpenAI. It had the arc of a standard that was going to define the next decade.
Then in March this year, at the Ask 2026 conference, Perplexity’s CTO Denis Yarats announced the company was shifting away from MCP internally, toward traditional APIs and CLIs, citing “high context window consumption and clunky authentication” as the core reasons. Apideck had already documented a production case where three MCP servers burned 143,000 of a 200,000-token context window — seventy-two per cent — before the agent had done any work. Cloudflare shipped a different kind of answer called Code Mode: instead of exposing their 2,500-endpoint API surface as thousands of MCP tools, they exposed it as two — search and execute — and let the agent write code against the API directly. 1.17 million tokens of tool definitions replaced by roughly a thousand. A ninety-nine-point-nine per cent reduction, delivered not by improving the protocol but by refusing to play the game the wrong way.
Some of this is MCP’s fault. Authentication ceremony, serialisation overhead, tool-definition verbosity — the protocol has real costs that good API design cannot fully eliminate. But the bulk of the pain is underneath it. A protocol amplifies the design it wraps. Good design, amplified, looks like productivity. Bad design, amplified, looks like a seventy-two-per-cent context tax. Birgitta Böckeler frames the broader problem as “harness engineering” in a recent martinfowler.com essay, and her point generalises: no amount of scaffolding around a weak API fixes the API.
The rules of good API design didn’t change with MCP. They just started getting graded in real time.
The rules were always right
Every complaint agents have about APIs in 2026 is a complaint good designers were making in 2016.
Name things as if units matter — because they do. amount_cents, not amount. customer_id, not id. The research on LLM tool-calling lands in the same place every time: precise parameter names and descriptions materially improve accuracy, and the gap is not subtle. Human developers worked around the same ambiguity with wrapper libraries and Stack Overflow answers for more than a decade. They could tolerate bad naming. Agents invent plausible nonsense and bill you for it.
When your API response can be more than one shape — a success payload or an error, a card payment or a bank transfer — you’d better be explicit about which one it is. Or else. But it’s also easy: add a type or kind field that says so. Don’t make the caller infer it from the fields present. Human developers could look at the shape and work it out. LLMs can’t — they guess, and across OpenAI, Anthropic, and Google’s tool-calling runtimes, they guess differently. A single explicit tag on the response is the only pattern that works reliably across all of them.
Put an idempotency key on every write endpoint. Stripe has been shipping them for about a decade. Without idempotency, an aggressive retry loop ships duplicate charges by architectural choice — and agents retry far more aggressively than any human developer ever did, because they have no social cost for doing so.
Return structured errors with recovery hints, not HTTP 400 and a sentence. The Berkeley Function Calling Leaderboard keeps publishing the same gap: frontier models score above ninety per cent on individual calls and degrade significantly on multi-turn tasks that require error recovery. Where the failures compound is retries, and where retries fail is when errors don’t tell the agent whether to retry at all.
Budget your tool count the way you’d budget any scarce resource. Chroma’s 2025 context rot study tested eighteen frontier models and found that adding semantically similar but irrelevant distractors systematically degrades accuracy, especially as context length grows. API sprawl was always bad. Now it breaks your caller’s reasoning.
None of this is new. Sam Newman has been writing about boundaries as products for a decade. Kent Beck has been teaching schema discipline since before REST. Patrick Collison, on the Dwarkesh Patel podcast in early 2024, put it this way: “When you get API design and architecture right, it can be so enduring over literally multiple decades.” He calls them multi-decadal abstractions. He cites Unix and iOS as examples of APIs that persist through a generation of technology change. That framing pre-dates LLMs by years, and it just became load-bearing for anyone shipping APIs into an agent ecosystem.
A small handful of obligations genuinely did emerge with agents. Tool descriptions are now a security surface — researchers testing forty-five live MCP servers from the MCPTox benchmark reported tool-poisoning success rates as high as seventy-three per cent under adversarial conditions, using adversarial instructions smuggled directly into tool metadata. Token budget is now a cost your API imposes on every caller the moment they read your schema. Those are new. But the bulk of what agents want is what good API designers have wanted for fifteen years.
The difference between 2016 and 2026 isn’t the rules. Human developers routed around bad APIs with wrapper libraries, client SDKs, and a Slack message to a colleague. Agents route around them too — system prompt injections, retrieval pipelines, custom orchestration layers. The routing works. It just costs tokens, latency, and a new failure surface every time it runs. The bill compounds until someone bothers to fix the API.
The bill, itemised
The customer changed first. The 2025 US holiday season hit a record $257.8 billion in online spending, according to Adobe. Salesforce reported that AI agents and generative AI tools influenced twenty per cent of all online retail sales globally — roughly sixty-seven billion dollars in influenced purchases during Cyber Week alone. Adobe separately measured a 693 per cent year-on-year surge in AI-driven traffic to retail sites. The customer who used to be a browser is now, for an increasing slice of commerce, an agent — and the agent reads your schema before it reads your marketing.
Postman’s 2025 State of the API survey puts the gap between adoption and readiness in concrete terms. Eighty-nine per cent of developers use generative AI in their daily work. Twenty-four per cent design APIs with agents in mind. Sixty per cent still design primarily for humans, and sixteen per cent haven’t considered agents as API consumers at all. Every API shipped into that gap is one that some agent, somewhere, is already trying — and usually failing — to consume.
Then the risk profile. Gartner predicts that by 2028, a quarter of enterprise breaches will trace back to AI agent abuse. Visa’s 2025 threat research documents a steep rise in AI-enabled fraud tooling on the dark web. CyberArk’s 2025 identity survey found that machine identities now outnumber humans by more than eighty to one — and still, the majority of organisations define only human identities as privileged users. The agents are in the estate. The governance isn’t.
And the permanence bill came due. Stripe is still the gold standard: date-based versioning, automatic account pinning, twice-yearly bundled breaking changes, dozens of API versions alive simultaneously, and none of them surprise anyone. The machinery is expensive — most teams cannot afford to run it at that scale. The principle to borrow is the shape, not the count. Predictable deprecation on a published calendar. Breaking changes bundled and announced. Callers never surprised.
Contrast with the walking wounded. Twilio Notify, deprecated and fragmented across three separate migration paths. Shopify’s forced REST-to-GraphQL march. OpenAI’s Assistants API, scheduled to sunset in August 2026, triggering refactors across every production system built on it. The gap between Stripe’s world and those worlds used to be reputational. Now it is a line item, and the agents are the ones reading it.
Back to cxpak
I started cxpak on the fifth of March with a simple thesis: spend CPU cycles so the LLM doesn’t spend tokens. Two commands, a tree-sitter index, a token budget. By the twenty-third of March I had shipped v1.0.0 with cxpak_auto_context as the capstone and committed to stable semver on the whole MCP surface. Six tools. By v1.4.0, three weeks later, I had added change impact prediction, architecture drift detection, security surface analysis, convention extraction, health scoring, risk ranking, workspace support, and co-change mining — most of it wired into auto_context’s response envelope. Fifteen versions. Nineteen MCP tools. Forty-two languages. Two months.
Every one of those additions had to make peace with shapes I’d committed to on day one.
The v1.0.0 API was the best I knew how to build at the time. What changed in six weeks wasn’t my skill — it was my visibility. Every time Claude Code ran against the index, I saw where the schemas I’d committed to were too narrow, too loose, or silently growing in directions I hadn’t planned. The agents told me what the API actually needed before any human user did. They read the schema on every invocation. They retried on every ambiguous response. They miscalled on every overloaded tool. The feedback loop on bad design shrank from months to minutes.
This is the difference AI makes. Feedback on a badly designed API used to come back in the form of support tickets, wrapper libraries on GitHub, and blog posts titled “Why We’re Migrating Away From X”. Now it comes back as retry loops in your telemetry and your own Claude instance hallucinating the old tool names for days after a rename.
You don’t change an instruction set. You design one that doesn’t need to be changed. That’s true at Stripe’s scale over years, and it turned out to be true on mine over six weeks.
The same spec, run through Claude and past a senior engineer, will fail in (mostly) the same places. The difference is that only one of them will tell you the cost. The other will bill you for it, quietly, every day, for as long as the API exists.
The rules didn’t change. The customer did. Name things like units matter. Ship idempotency keys on every write. Return structured errors with recovery hints. Version on a calendar, bundle your breaking changes, pin your callers by default. Budget your tool count. Deprecate like you mean it.
None of this is new. What’s new is who’s reading it.