Designing Agent-Ready APIs for AI Agents and MCP
AI agents and the Model Context Protocol are changing what counts as a well-designed API. Here's how engineering teams should approach authentication, rate limiting, documentation and observability so agent traffic can be safely integrated.

Why do APIs need to change for AI agents?
APIs built for human-driven applications assume a predictable client: a browser or mobile app making requests at human speed, with a developer reading the error message when something breaks. AI agents are a different kind of client. They call APIs autonomously, in bursts, sometimes in loops, and they cannot always tell the difference between a transient failure and a permanent one. Designing for agent traffic means designing for a client that is fast, persistent, and occasionally wrong.

This matters now because of the Model Context Protocol (MCP), an open standard that lets AI models discover and call external tools and data sources through a consistent interface. MCP is becoming a common way for agents to connect to business systems, which means the APIs behind your product are increasingly likely to be called by something other than a person.
What is the Model Context Protocol, and why does it matter?
Model Context Protocol (MCP) is an open standard that defines how AI applications connect to external tools, data sources, and systems through a uniform interface, rather than a custom integration per model or vendor. Instead of writing bespoke glue code for every AI assistant that wants to query your platform, you expose a defined set of capabilities — tools, resources, and prompts — that any MCP-compatible agent can discover and use.
For engineering teams, MCP matters because it shifts API design from "build an endpoint and write a README" to "build an endpoint and describe it well enough that a model can use it correctly without a human in the loop." That changes what good documentation, error handling, and scoping look like. It's a similar shift to the one teams went through when exposing internal services as public REST APIs for the first time — except the consumer now reasons in natural language rather than reading your docs page by page.
How should you design authentication for agent traffic?
Agent authentication should separate the identity of the agent from the identity of the human (or system) it is acting on behalf of, using scoped, short-lived credentials rather than long-lived API keys shared across every call. Treat each agent integration as its own client application with its own audit trail, not a shared service account.
In practice this means a few concrete decisions. Use OAuth 2.0 with fine-grained scopes rather than a single all-access key, so an agent that only needs read access to inventory data can't also modify billing records. Prefer short-lived tokens with refresh flows over static keys, so a leaked credential has a limited blast radius. Where an agent acts on behalf of a specific user, pass through that user's identity and permissions rather than elevating to a service account — this keeps authorisation decisions consistent with what a human would be allowed to do manually, and keeps your audit log meaningful. The OWASP API Security Project's guidance on broken object-level authorisation is a useful reference point here, because agents that are given broad scopes will eventually probe the edges of them, intentionally or not.
How does rate limiting need to change for agents?
Rate limiting for agents needs to account for burstier, less predictable traffic patterns than typical human usage, and needs to communicate limits in a way an agent (or the framework calling on its behalf) can act on automatically. A 429 response with a clear retry-after header is far more useful to an agent than a generic error string.
Human users click a button, wait, and click again. Agents can call an endpoint dozens of times in a few seconds when working through a multi-step task, especially if they're retrying after an ambiguous response. Static per-minute limits that were generous for human traffic can be exhausted quickly by a single agent session. Consider tiered limits — a lower ceiling for exploratory or read-heavy calls, a stricter one for write operations — and make sure your rate-limit responses include machine-readable detail: how many requests remain, when the window resets, and ideally a structured error code rather than just an HTTP status. This lets well-built agent frameworks back off gracefully instead of hammering the endpoint or giving up and reporting a false failure to the user.
What does good documentation look like for agent consumption?
Agent-ready documentation describes not just what an endpoint does, but what it should and shouldn't be used for, what valid inputs look like, and what failure looks like — written clearly enough that a language model can parse it without inferring intent from prose written for humans. Structured schemas matter more here than narrative explanation.
This means investing in machine-readable specifications — OpenAPI 3.x definitions, JSON Schema for request and response bodies, and for MCP specifically, clear tool and resource descriptions with explicit parameter constraints. Ambiguous field names (type, status, value) that a human developer would resolve by reading surrounding code become a real problem for an agent working from the schema alone. Err on the side of verbose, consistent naming and explicit enums over free-text fields wherever the domain allows it. If you're modernising an older API as part of this work, the application modernisation teams we work with often find that tightening up API contracts is a natural first step before any agent integration is attempted.
How do you observe and audit agent behaviour in production?
Observability for agent traffic needs to go beyond standard request logging to capture intent — which agent, acting for which user, called which tool, with what reasoning context, and what it did with the response. Without this, a misbehaving agent looks identical to a misbehaving script, and debugging either becomes guesswork.

Practically, this means tagging agent traffic distinctly in your logs and metrics (separate from human API traffic), capturing the full tool-call sequence for a given agent session rather than just individual requests, and setting alerts on patterns that are specific to agent failure modes — repeated retries on the same endpoint, calls that fall outside an agent's expected scope, or sudden spikes in write operations. This is as much a data infrastructure problem as an API design one: you need a pipeline that can correlate agent sessions across services, not just tail a single service's logs.
REST API design vs agent-ready API design
| Consideration | Traditional REST API design | Agent-ready API design |
|---|---|---|
| Authentication | Long-lived API keys, broad scopes common | Short-lived tokens, fine-grained scopes per capability |
| Rate limiting | Simple per-minute thresholds | Tiered limits with machine-readable retry guidance |
| Documentation | Prose-heavy README, implicit conventions | Structured schemas (OpenAPI, JSON Schema, MCP tool definitions) |
| Error handling | Human-readable error messages | Structured, consistently coded errors an agent can act on |
| Observability | Request/response logging | Session-level tracing of agent intent and tool-call sequences |
| Discovery | Manual integration per client | Standardised discovery (e.g. via MCP) |
Where should engineering teams start?
Most teams don't need to rebuild their API surface to support agents — they need to audit it. Start by identifying which endpoints are realistic candidates for agent access (usually read-heavy, well-bounded operations before anything that writes or deletes), and work through authentication scoping, rate limit messaging, and schema clarity for those first. Treat it as an incremental hardening exercise rather than a parallel API project.
This is also a reasonable point to bring in outside technical judgement. Deciding which endpoints are safe to expose to autonomous agents, and how much authority to grant them, is as much a risk and architecture question as an engineering one — which is where AI product strategy work and hands-on AI engineering tend to intersect. We've written more on related groundwork in our insights, including how to think about data foundations before any AI integration.
If you're exploring how to make your platform safely accessible to AI agents or MCP-based integrations, we can help — starting with a straightforward review of what's safe to expose and what needs work first.
Chris Kerr
Partner at Horizon Labs, an AI product consultancy and venture studio. A commercially focused product and technology leader with 20+ years building and scaling digital platforms, teams, and businesses across SaaS, travel, eCommerce, logistics and transport, and digital marketing — operating at the intersection of product, engineering, and data. Writes about platform strategy, AI transformation, modern data ecosystems, and the operational discipline that separates AI demos from AI products.


