If you've spent years building REST APIs, your instincts are going to betray you when you start working with MCP (Model Context Protocol). That's the core argument in part two of Ibrahim Mohammed's series on transitioning from REST to MCP, and it's a wake-up call the ecosystem needed.

The Core Problem: Different Environments, Different Rules

REST was designed for web services where clients and servers are relatively symmetric—both sides understand HTTP, resources have stable URLs, and state is either stateless or managed explicitly. MCP throws that assumption out the window. When your 'client' is an AI agent with evolving context and tool-calling capabilities, you're operating in a fundamentally different environment. The article argues convincingly that design patterns optimized for REST actively work against you in this new paradigm.

What Actually Changes

The shift isn't cosmetic. In REST, you're modeling resources and operations; in MCP, you're modeling capabilities and conversations. Your endpoints don't map to CRUD operations—they map to tools the agent can invoke. Your error handling can't assume retry logic because an LLM might interpret errors differently than a HTTP client would. The article walks through several design principles that flip traditional API thinking: think in terms of what the agent needs to accomplish, not what data your system exposes.

Practical Design Implications

One key insight: MCP favors coarse-grained operations over fine-grained endpoints. Instead of exposing every possible data mutation as a separate call, you bundle related capabilities into tools that make sense for an AI workflow. The article provides concrete examples showing how the same functionality might look radically different depending on whether you're designing for REST or MCP. It's not about being right or wrong—it's about recognizing the context shift.

State Management Gets Weird

Perhaps the biggest mental leap is around state. REST prides itself on statelessness, but MCP often operates with persistent conversational context. The agent carries memory across interactions in ways that traditional APIs never had to consider. Your design needs to account for this context lifecycle—which information persists, what triggers resets, how to handle conflicting implicit states.

Tool Discovery and Schema Design

MCP requires explicit tooling contracts that go beyond OpenAPI specs. Tools need rich descriptions because the agent is reading them to decide when and how to invoke them. This means your schema design isn't just about data validation—it's about communication with an AI that needs clear intent signals. The article emphasizes that poorly described tools lead to unpredictable agent behavior.

Key Takeaways

  • MCP requires rethinking error handling for AI-native consumption, not HTTP status codes
  • Design tools as capability bundles rather than resource mappings
  • Schema descriptions are critical—they're how the agent understands your API's purpose
  • Context lifecycle management replaces statelessness assumptions
  • The environment difference between REST clients and LLM agents demands architectural rethink

The Bottom Line

The industry is going to ship a lot of bad MCP implementations by developers who couldn't resist importing their REST instincts. Don't be that person. Read the full series, internalize the paradigm shift, and accept that good MCP design looks strange to anyone still thinking in HTTP verbs.