Every API Will Be Rebuilt for Agents

MCP solves the plug. It doesn't solve the verb gap.

Hand a coding agent a beautifully documented REST API — versioned, OpenAPI'd, the kind a human developer would happily build against — wrap it in MCP in an afternoon, and watch it still fumble. It picks the wrong endpoint. It calls three when one would do. It does a destructive write it should have asked about. The API isn't bad. It's built for the wrong consumer.

MCP is winning the part that was always going to be solved — the plug. And winning is what exposes the uncomfortable part: almost every API we have is built for a consumer that's no longer the only primary consumer. For twenty years that consumer was a human developer who showed up with intent and a mental model. Now it's an agent that has neither and has to reconstruct both from your surface. When the primary consumer of an interface changes that completely, the interface gets rebuilt. It always has.

So, here's the claim I'll commit to: the serious product surfaces agents operate against will be rebuilt around agent-native operations. Not wrapped. Rebuilt. These are still one person's notes, not advice — and intentionally directional, not a migration plan. The direction isn't what I'm unsure about. Only the timeline is.

When I say every API, I don't mean every endpoint gets replaced or every protocol disappears. I mean the product-level operations an agent is trusted to execute move from resource-shaped APIs to intent-shaped contracts — redesigned around goals, state, side-effects, approval, and recovery.

MCP standardizes the plug, not the operations

Give MCP its due: it's now a genuine cross-client standard — Claude, ChatGPT, VS Code, Cursor, Codex, Copilot. Connection, auth, transport, human-in-the-loop, long-running Tasks: all getting standardized, steadily.

But in the spec, a tool is just a function — a name, a description, a schema. MCP deliberately doesn't decide what state transitions your domain has, what order tools go in, which operations are dangerous, or which need approval. That's the right scope for a protocol. It also means MCP gives you a clean way to expose whatever your API already is — and what it already is, is a thing designed for a developer who brings the plan.

Call the failure the verb gap: APIs hand agents nouns and CRUD; agents need verbs that carry intent. No protocol closes that gap, because the gap is in the API, not the wire. MCP solves the plug. It does not solve the verb gap.

The wrapper ceiling is already visible

The tell is that the most API-mature companies are walking the wrapper back, in public.

GitHub's official MCP server is excellent — and GitHub is narrowing its default toolset and consolidating PR tools into fewer, more capable ones, explicitly to cut tool bloat and improve agent reasoning. The implication is hard to miss: even one of the best API companies on the planet is learning that a 1:1 mapping from product API to agent tools isn't the right shape.

Research points the same way. AutoMCP generated MCP servers from OpenAPI specs: across 50 real APIs and ~5,000 endpoints, tool-call success went from 76.5% to 99.9% — but only after fixing the underlying spec. A 2026 study on agent-ready OpenAPI docs found agents failing systematically at planning and tool selection, with defects in essentially every operation. Their line is the one to underline: an API can be structurally valid and still not be semantically ready for an agent.

Every "just wrap it" path ends at the same wall — the contract is wrong for the new consumer, and you can't wrapper your way to a different contract. Wrapping buys a demo. Rebuilding buys a product.

What "rebuilt for agents" looks like

An agent-native API isn't an API an agent can call. It's an API whose operations carry enough intent, state, and safety for an agent to know what it's doing.

Not a few coarse endpoints bolted on. A different default shape for every operation — one that answers more than "what do I return." It answers: what's the goal, what state am I in, what are the side-effects, do I need approval, how do I recover.

inspect_pull_request        → state + what's relevant, not the raw blob
find_merge_blockers         → the global fact, computed, not re-derived
preview_write_action        → dry-run: here's what WOULD happen
commit_approved_action      → the write, gated behind explicit approval
explain_missing_permissions → why it can't, in actionable terms
rollback_last_action        → recovery as a first-class verb

Agent-native doesn't just mean coarse-grained. A coarse endpoint can still be unsafe, opaque, and impossible to undo. The difference is that an agent-native operation exposes its preconditions, expected effects, uncertainty, required approvals, and recovery path as part of the contract. preview / commit split intent from effect, so a dangerous write becomes a two-step you can reason about. rollback makes recovery part of the surface, not an afterthought.

There's a hint here about how these get built. Today we usually grow REST outward from the database — tables become resources, columns become fields, CRUD becomes the default. But an operation that knows its preconditions and its legal next moves is really a state machine wearing an API. It's not a stretch to imagine the mainstream flipping: generating the surface from an explicit state model — transitions, guards, and valid next-actions as the source of truth — with storage downstream, instead of the other way around. That's the version of this I'd most want to build.

And here's why it's one API, not two: developers want all of this too. Preview-before-commit, blast radius, clear permission errors, rollback — that's not an "agent edition," it's just a better API whose main consumer happens to be an agent. You don't want to maintain a human API plus an agent API forever. Over time, the agent-native design should subsume the human one.

This connects to the last post: a good operation collapses a risky multi-step workflow into one confident verb, the way a rigorous fact collapses a hedge into a flat statement. Rigor compresses; so does a good operation.

It's not just APIs — CLIs are the same surface

This was never really about REST. It's about any surface an agent operates against, and the CLI is the other big one. A coding agent lives in a terminal — it runs git, kubectl, your build and deploy scripts — and hits the same verb gap: tools that assume a human who already knows the flags.

CLIs add a second problem the API case hides: output. Most CLIs print for a human — colors, progress bars, free-form logs, a summary line you're meant to eyeball. The agent has to scrape that, which is the verb gap again, moved to the return path. So an agent-native CLI prioritizes machine-readable output — --json, structured logs, stable exit codes, errors that name the next action — over pretty terminal formatting. When you can't have both, the default flips: readable for the agent beats readable for the eye.

That's the same coin as the verb gap, both sides of it. Calling side: verbs that carry intent. Return side: state the agent can parse, not prose it has to interpret. And the shift is bigger than APIs: every interface we built assuming a human on the other end — APIs, CLIs, logs, output formats — is up for reconsideration once the other end is an agent.

Security is what makes it "must," not "nice"

MCP clients put tool name, description, and schema straight into the model's context — so a malicious description can steer the model (tool poisoning, confused-deputy, over-broad scopes). And agents use configured tools autonomously; GitHub's own docs recommend allowlisting read-only tools for exactly this reason.

You can't allowlist your way to safe writes on a human-shaped API. You rebuild writes as preview → approve → commit, with permission errors that explain themselves. Safety isn't a wrapper you add; it's a property you design into the operations.

Three layers now, one contract later

This won't happen overnight. Near term, three things coexist — but only one is the endgame.

The wrapper is useful as a transition — it connects what exists today — but it carries the legacy contract underneath, and that contract is the problem. Over time the core gets rebuilt and the wrapper dissolves, the same way mobile BFFs gave way to redesigned APIs instead of living forever as shims.

Practically: greenfield should start agent-native now — no reason to ship a human-only contract you'll rewrite. Brownfield wraps as a bridge, then rebuilds the operations that matter most first. Either way the arrow points one direction.

Objections I'd raise myself

• "You can't rewrite every API; legacy is forever." Legacy persists — but "persists" isn't "is what you'd build." SOAP still runs; nobody starts there. Human-shaped APIs become the thing you wrap and migrate off, not the thing you design.
• "This is just BFFs rebranded." The technique isn't new; the consumer is. A BFF serves a fixed UI flow a human designed. An agent-native operation has to surface its own preconditions, danger, and recovery, because the agent is forming the plan — and it applies to the whole surface, not one frontend.
• "Models will get good enough to use raw APIs." Maybe for reads. But capability makes the security case worse — a more capable agent doing an unguarded destructive write is the nightmare, not the fix.
• "Rebuilding every domain doesn't scale." The load-bearing worry. The bet is that AI dropped the cost of domain-specific implementation enough that it finally pencils out. If that's wrong, the timeline stretches. The direction doesn't change.

Where this is going

The contract at the center of interface design is flipping. Old: the human holds the intent; the API returns materials. New: the agent holds the goal; the API returns state, constraints, the next safe action, and a way back. The competitive axis stops being endpoint count and becomes whether an agent can safely accomplish a goal against your surface.

We probably don't have the right format for this yet. I doubt it's REST or GraphQL; both were shaped for consumers that aren't the agent. For now, OpenAPI and Zod are still the right place to stand: precise schemas reduce mistakes, and AutoMCP's jump from 76.5% to 99.9% is evidence of that. But implementer correctness and agent operability are different axes, and the second one will likely grow its own format. That part I'm looking forward to.

These days I keep tacking defensive lines onto prompts: "preview before you write," "ask before anything destructive," "explain why you can't." It's not that I distrust the agent — it's that the operations I hand it are the vague part, so reminders are the only patch I have. Rebuild the operations to carry their own preview, approval, and rollback, and those lines stop being necessary.

If the operation is safe by design, you don't have to ask the agent to be careful with it.