Skip to main content

MCP Is Not Your REST API: 5 Principles

· 6 min read
Agent Interviews Team
Agent Interviews Team

Most “MCP integrations” ship as thin wrappers over existing REST endpoints because it’s the fastest way to get something working, but that convenience often fights how agents actually reason and act. If you want MCP that agents can use reliably, design it like an action‑oriented RPC interface rather than a collection of CRUD‑style endpoints.

A helpful way to think about this shift is that one tool should correspond to one meaningful task a human would ask an assistant to perform; by encapsulating orchestration, validation, and transactional guarantees inside that tool, you remove brittle multi‑step planning from the agent’s loop and you dramatically reduce the error surface. This “verbs over resources” mindset is exactly what makes MCP feel different in practice from REST wrappers, a point that comes through clearly in comparisons like MCP vs API — Glama and in the argument that MCP revives hypermedia‑style self‑discovery rather than hard‑coded contracts, as discussed in MCP: REST reborn?.

1) Design tools as actions, not CRUD​

Treat tools as verbs with a purposeful outcome—think publishReport, transferOwnership, or archiveOldPosts—and put the orchestration and transactionality inside the server so the tool either completes or it doesn’t, without leaving partial state behind. This aligns with agents’ verb‑first planning and avoids pushing them to assemble fragile sequences of GETs and PUTs. The approach mirrors guidance in Glama’s comparison that favors task‑level tools, and it dovetails with the self‑describing, discoverable ethos highlighted by Richard Marmorstein’s piece.

The main limitation with this approach for the current generation of LLMs is that too many tools limits the ability of the AI to work with them accurately. Currently 40 tools is the guide, down from 60 or so only a few months ago. The issue is that if you have dozens of actions for any given model then pretty soon the AI is going to be overwhelmed.

2) Provide a single, high‑quality search endpoint to reduce list sprawl​

Instead of exposing a proliferation of narrowly scoped list endpoints (e.g., listProjects, listTeams, listDocs, each with bespoke filters), offer one carefully designed search tool that unifies discovery across your domain. Accept a natural‑language query alongside structured filters, support typed facets and pagination cursors, and return ranked, typed results with stable identifiers and minimal, well‑chosen metadata so the agent can choose precisely what to load next. By consolidating discovery into one capability, you reduce the cognitive load for the model, make capabilities easier to learn through runtime introspection, and retain server‑side control over relevance, authorization, and result shaping. This complements MCP’s runtime discovery primitives (for example, resources and tools listing in the spec architecture) and preserves the “few, powerful verbs” guidance seen in API comparisons like Glama’s analysis while avoiding a long tail of redundant list operations.

3) Prefer runtime discovery and self‑describing schemas​

Rather than shipping static client code and versioned docs, expose capabilities at runtime through tools/list, resources/list, and prompts/list, and make each tool legible to a language model: include a natural‑language description that explains when to use it, a strict JSON Schema that defines valid inputs, and a brief note about side effects or constraints. With that foundation, agents adapt to what exists now instead of guessing from stale documentation, which is precisely the contrast drawn in “Traditional APIs vs. MCP” style write‑ups such as this overview and in the official Anthropic MCP documentation.

4) Use stateful, bidirectional sessions instead of stateless requests​

MCP’s JSON‑RPC over stdio or SSE isn’t an accident; it enables sessions that carry context, server‑initiated notifications, streamed progress, and multi‑turn coordination without forcing the client to resend everything on each call. When a long‑running task needs to report partial results, ask for a missing argument, or publish an intermediate artifact, the transport supports that conversational rhythm, which is why the MCP specification’s architecture centers sessions and capability negotiation and why technical deep dives like this one emphasize bidirectional messaging patterns.

An alternative architectural choice is to lift long‑lived task state, cross‑agent context, and collaboration into an Agent‑to‑Agent coordination layer that sits above your MCP servers, so MCP can remain focused on immediate request/response tool calls while the higher‑level workflow, negotiation, and memory live one layer up. The open Agent2Agent (A2A) protocol specifies discovery, negotiation, and streaming over JSON‑RPC 2.0; using A2A for coordination lets MCP act as a simple local/remote execution surface while durable state and multi‑agent handoffs are handled in the A2A tier. There is a potential long term vision where A2As are the agent layer handing discovery and context above a bunch of highly efficient MCPs, without the need for any web app at all.

5) Make execution deterministic and validated on the server​

Let the agent decide which tool to call, but make the execution path predictable: validate inputs against JSON Schema, enforce authentication and quotas, handle pagination and provider rate limits internally, and ensure idempotency and atomic side effects (or provide explicit compensations). That way, correctness lives in code you can test rather than in LLM‑generated HTTP strings, echoing the recommendation in Glama’s MCP vs API and the practical framing in IBM’s “What is MCP?” around tools, resources, prompts, and transports.

Designing your MCP server with these principles yields an interface that matches how agents plan and act: they discover tools at runtime, choose a single purposeful action, find items through an expressive search rather than wading through dozens of lists, receive progress and results over a live session, and rely on the server to enforce validation, guardrails, and transactional guarantees. Build that way, and your MCP becomes a real agent‑computer interface rather than a REST mirror wearing new clothes.