From REST to MCP: Redesigning APIs for the Agentic Era

Introduction

For two decades, REST was the default contract between services. You designed endpoints for human developers: predictable URLs, JSON payloads, OpenAPI docs, and SDKs in three languages.

In 2026, a second class of API consumer arrived: AI agents. They don't read your docs—they discover capabilities at runtime, invoke tools with probabilistic intent, and fail in ways REST was never designed to handle.

Model Context Protocol (MCP) has become the de facto standard for agent-to-tool communication, with SDK downloads crossing 97 million per month. OpenAI deprecated its Assistants API in favor of MCP-compatible patterns. If your APIs only speak REST, agents will either wrap them badly or bypass them entirely.

This is not a replacement of REST—it is an additional interface layer your architecture needs.

Section 1: Why REST Breaks Down for Agents

REST assumes a deterministic client:

the developer knows which endpoint to call,
the request shape is fixed,
errors are handled by application code with full context.

Agents invert these assumptions:

the model chooses which tool to call based on natural language,
argument schemas must be self-describing (name, type, description),
failures trigger retries, hallucinated parameters, and cascading side effects.

A REST endpoint like POST /api/v2/orders/{id}/refund is meaningless to an agent unless you expose it as a named tool with a JSON schema, clear description, and idempotency guarantees.

Section 2: The MCP Mental Model

MCP standardizes three capability types:

Tools: callable functions with typed arguments (write operations, computations),
Resources: read-only data accessible by URI (files, records, configs),
Prompts: parameterized templates the agent can invoke.

Your REST API maps to MCP like this:

REST pattern	MCP equivalent
`GET /users/{id}`	Resource: `users://{id}`
`POST /orders`	Tool: `create_order` with schema
Pagination, filtering	Tool: `search_orders` with query params as schema fields
Webhooks / events	Resource subscriptions or streaming

The key shift: descriptions become part of the contract. An agent reads tool metadata to decide what to call. Vague descriptions produce wrong calls.

Section 3: Designing Dual-Interface APIs

You do not need to throw away REST. The production pattern is a dual interface:

REST layer for human clients, mobile apps, and partner integrations (unchanged),
MCP server layer that wraps the same business logic with agent-native schemas.

Schema design rules

Every tool parameter needs a description field—the model uses it to fill arguments correctly,
Use enums and constraints aggressively; free-form strings are where agents hallucinate,
Return structured results, not prose. Agents parse JSON, not paragraphs.

Idempotency is non-negotiable

Agents retry. If your create_invoice tool is not idempotent, a transient network error becomes a duplicate invoice. Apply the same idempotency keys you use in payment APIs to every agent-callable write tool.

Section 4: Discovery and Versioning

REST versioning (/v2/) breaks agent discovery. MCP clients call tools/list at connect time and cache the result.

When you version:

expose versioned tools side by side (create_order_v1, create_order_v2),
deprecate old tools with clear descriptions ("deprecated: use create_order_v2"),
never remove a tool without a migration window—agents do not read changelog emails.

For resources, use URI versioning: orders://v2/{id}.

Section 5: Security Boundaries for Agent APIs

Agents operate with delegated authority. Your MCP server needs tighter controls than a typical REST API:

Scope-limited tokens: each agent session gets minimal permissions,
Human-in-the-loop gates for irreversible actions (payments, deletions, external communications),
Rate limiting per tool, not just per API key—agents can hammer a single tool in a loop,
Audit logging of every tool invocation with arguments (redacted where needed).

Conclusion

The agentic era does not kill REST—it adds a parallel interface contract. Teams that expose MCP servers alongside REST APIs get portable, discoverable integrations that work across Claude, Cursor, OpenAI, and custom agent runtimes.

Start with your highest-value write operations: the tools agents will call most often, with the highest blast radius if they fail.