Sub-grade spoke

Agent API Spec — can an agent call your service directly without driving a browser?

An agent API spec is the public, machine-readable description of your service — typically OpenAPI for REST, JSON Schema for payloads, and an MCP server for tool-using LLMs. It's the structured-action surface agents reach for before falling back to brittle browser orchestration. Sites that publish a clean spec get adopted by agent platforms; sites that don't get skipped. The work is mostly packaging — most modern services already have the API; few have done the documentation, auth, and MCP wiring that makes it agent-callable.

By Chris Mühlnickel · 2026-05-16

What is Agent API Spec?

Agent API Spec is whether your service publishes a complete, machine-readable contract — OpenAPI for endpoints, JSON Schema for payloads, declared auth scopes, machine-readable rate limits — that an agent can consume directly without screen-scraping the rendered UI.

By the numbers

Why it matters

Agents prefer structured action surfaces over rendered UIs. When an agent has a choice between calling a documented endpoint and orchestrating a browser session that drives the same workflow, the documented endpoint wins every time — it's faster, more reliable, cheaper in tokens, and less likely to break on a UI revision. The "agent API spec" check at the Usability layer is the single biggest determinant of whether your service participates in that preferred path or sits on the fallback path for sites without a published contract. Per Postman's 2025 State of the API Report, 93% of organizations already run a REST API in production. The work isn't building the API — it's the packaging that turns an internal endpoint into a public agent-callable surface.

The OpenAPI document is the contract that everything downstream depends on. Without a stable, hosted OpenAPI spec, agents have to reason about your API from documentation pages — slower, more error-prone, and brittle when docs drift from implementation. With one, every downstream piece composes: SDK generators emit clients automatically, MCP-server scaffolds bind tool descriptions directly to operation IDs, API gateways enforce schemas at the edge, and LLMs reading your docs cite endpoint signatures verbatim instead of paraphrasing them. The single artifact unlocks the entire stack. Most modern API frameworks (FastAPI, NestJS, Stripe-style schema-first design) emit OpenAPI as a build artifact for free — the work is publishing it at a discoverable URL.

MCP servers are becoming the canonical agent-distribution surface. Model Context Protocol servers package your API as a curated tool catalog that LLMs consume directly without reasoning steps in between. Claude.ai, ChatGPT, Cursor, Windsurf, and a growing list of agent runtimes natively load MCP servers; Stripe, Linear, GitHub, Notion, and dozens of other major SaaS products have shipped MCP servers in the last 12 months and are seeing material agent-driven traffic from them. The cost of building one against an existing OpenAPI document is hours, not weeks. The cost of not building one — per Postman, 73% YoY growth in AI-driven API traffic — is the share of that traffic you cede to platforms that did the work.

The "API designed for agents" investment is still rare and therefore disproportionately rewarded. Only 24% of developers design APIs with agents in mind, per Postman. That gap creates an unusual moment: the bar for being above-median on agent-API design is low (consistent error shapes, idempotency on writes, clear auth scopes, machine-readable rate limits), and the platforms doing the routing — ChatGPT, Claude.ai, Perplexity, the integration directories — actively elevate the sites that clear it. Sites that invested in clean OpenAPI design before agents existed are getting an unfair adoption advantage now. Sites that hand-wrote ad-hoc REST endpoints over the years have to pay catch-up.

Where it's heading

MCP servers move from optional to baseline within 18 months. The pattern in calibration corpora is clear: every major SaaS vertical has 1-3 leaders with shipped MCP servers and a long tail without. By 2027, lacking an MCP server is a hard signal that a service doesn't participate in agent-mediated workflows, the same way lacking a public OpenAPI document signaled "not API-first" by 2020. The cohort that ships MCP servers in 2026 captures the first-mover share of agent-routed traffic in their category.

API gateways add agent-aware policy as a first-class feature. Cloudflare, Kong, AWS API Gateway, and Apigee are converging on agent-specific gateway features: per-agent-platform quotas, signed-identity verification (HTTP Message Signatures + agent-platform certificates), and machine-readable policy disclosure via standardized headers. Sites with an OpenAPI document sitting behind a modern gateway will get most of this nearly free.

Spec drift becomes the new uptime metric. Today the question is "is your API up?" By 2027 it's "does your published spec match the deployed behavior?" CI-time contract testing against the OpenAPI document — already a maturity layer for the leading API teams — becomes the baseline expectation. Sites that wire this up never ship breaking spec changes by accident; sites that don't accumulate quiet drift that breaks agent integrations months after the regression.

Common mistakes

  • Documenting only some endpoints, not the contract. A docs site without a hosted OpenAPI document forces agents to reverse-engineer your API from prose. The result is brittle integrations that break the moment a parameter name changes.
  • Treating the API as developer-only. Auth flows that require human web-form login, examples written only in cURL with hardcoded API keys, no per-language SDKs generated from the spec. Each is a small friction; together they signal 'agents not welcome here.'
  • No idempotency on write endpoints. Agents retry under partial-failure. Without Idempotency-Key support, retries double-charge, double-book, or double-create resources — and the agent platform learns to route around your service.
  • Internal endpoints publicly reachable but undocumented. Agents find them anyway, depend on them, then break when you refactor. The clean split: document the public surface, gate the internal one at the network layer.
  • No published MCP server when one would take an afternoon. Most modern APIs already have an OpenAPI document. Wrapping it as an MCP server with curated tool names is the highest-leverage single move in the Usability sub-grade right now.

Frequently asked

Do I really need a separate agent API, or can my existing one work?

Your existing API is almost certainly the right starting point — agents call REST endpoints exactly the way mobile clients do. What's usually missing is the contract: a publicly hosted OpenAPI document, declared auth scopes, machine-readable rate limits, and an MCP server wrapper with curated tool descriptions for the LLM-as-reader. One underlying API, two surfaces — human developers consume the docs site, agents consume the spec + MCP tools. Run the Spekto audit to see what's already discoverable vs. what's hidden.

What's the minimum bar for an agent-callable API?

Four things: (1) a hosted OpenAPI 3.x document at a stable URL, linked from the marketing site, (2) declared securitySchemes with at least one machine-completable auth flow (OAuth client-credentials or scoped API keys — not session cookies), (3) idempotency support on write endpoints so agent retries don't double-charge or double-book, (4) HTTP status codes used correctly with structured error bodies. Each one of those four is well-defined; together they cover most of the gap between 'we have an API' and 'agents can actually use it.'

Does shipping an MCP server matter if I already have a great OpenAPI spec?

Yes, and the gap is widening. A clean OpenAPI lets an LLM with code-execution tools call your API after reasoning about it; an MCP server publishes pre-curated tool descriptions that the LLM consumes directly with no reasoning step in between. The MCP path is faster, cheaper in tokens, and less error-prone — and the major agent platforms (Claude.ai, ChatGPT, Cursor, Windsurf) all natively consume MCP. Sites with both win twice: developer integration via OpenAPI, agent integration via MCP.

Should I document internal endpoints or only public ones?

Only public ones. Documenting internal endpoints publicly invites traffic patterns you don't want to support and ties your hands on refactoring. The clean split: a stable, versioned, supported public API documented in OpenAPI + MCP, plus internal endpoints that stay undocumented and unsupported. Agents that hit the undocumented surface either get a useful 404 or hit auth — both are fine signals.

How should I expose rate limits to agents?

Two layers. First, in the OpenAPI document — describe per-endpoint quotas as x-ratelimit-* extension fields so the spec is self-describing. Second, in the HTTP response — return X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers on every response, especially 429s. Well-behaved agents honor Retry-After. The failure mode is rate-limit policies that exist but aren't surfaced anywhere agents can read — see the Spekto audit for which of your endpoints fail this check.

What about GraphQL — does the same Usability bar apply?

Yes, with one substitution: the introspection schema is your contract instead of OpenAPI. Publish the schema at a stable URL, support persisted queries for production traffic, expose auth scopes via directives. GraphQL has stronger native typing than REST but tends to be worse on idempotency conventions — be explicit about which mutations are safe to retry. Most major agent platforms can call GraphQL endpoints when the schema is published.

Where does WebHooks fit into the spec?

WebHooks are the inbound surface — agents call you. Outbound webhooks (your service notifies agents when something happens) belong in the spec too, but with stricter delivery semantics: signed payloads, idempotency keys, retry-with-backoff documented behavior. The OpenAPI 3.1 webhooks field exists for exactly this. Sites that ship both inbound and outbound surfaces compose into multi-step agent workflows cleanly.