MCP Is Not REST API  ## Metadata - Author: [[Han Lee]] - Full Title: MCP Is Not REST API - Category: #articles - Document Note: --- tags: [#MCP, #API, #software-architecture] - #MCP - #REST - #API-design Author: Lee Han Chung Source: Lee Han Chung's Blog Reference: [https://leehanchung.github.io/blogs/2025/05/17/mcp-is-not-rest-api/](https://leehanchung.github.io/blogs/2025/05/17/mcp-is-not-rest-api/) date created: 2025-07-11 11:25 --- # Title: MCP Is Not a REST API ## Table of Contents: - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📖 References](#-references) - [🗣️ Paraphrase](#-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB (Diversity, Equity, Inclusion, and Belonging) Assessment](#-deib-diversity-equity-inclusion-and-belonging-assessment) - [✅ Logical validity](#-logical-validity) - [🔍 DARVO Analysis Prompt](#-darvo-analysis-prompt) - [🔍 SEO Evaluation](#-seo-evaluation) - [🎯 Conclusion](#-conclusion) ### References: - Fielding, Roy T. "Architectural Styles and the Design of Network-based Software Architectures," 2000. - Related articles on software design paradigms and distributed systems. ## 📝 Summary: Lee Han Chung argues that the Model Context Protocol (MCP) should not be confused with REST APIs. While both handle requests and responses, MCP emphasizes context management and connection persistence, diverging fundamentally from REST’s statelessness. Chung stresses that misinterpreting MCP as "just another REST API" leads to architectural misunderstandings and flawed implementations. ## 📖 Main Content: The blog critiques a common misconception among developers: treating MCP as equivalent to REST APIs. REST relies on statelessness, resource-centric URLs, and uniform interfaces. In contrast, MCP focuses on stateful connections, context preservation, and long-lived interactions — more akin to protocols like WebSockets or gRPC streams. ### 🗒️ Notes - **Key Misunderstanding**: - MCP is wrongly compared to REST due to superficial similarities (request/response structures). - REST enforces statelessness; MCP requires context retention. - **MCP Characteristics**: - Stateful protocol. - Emphasizes maintaining context across messages. - Designed for complex, continuous workflows. - **REST Characteristics**: - Stateless by design. - Each request independent; no session-level context. - Ideal for CRUD operations on resources. - **Practical Implications**: - Using REST-style thinking with MCP could result in brittle systems. - Correct protocol usage demands embracing state management paradigms. - **Examples**: - Long-running AI model interactions benefit from MCP. - Real-time collaborative applications require context-aware persistence. - **Architectural Considerations**: - Protocol choice should match application behavior, not just popularity or developer comfort. ## 📖 References: - Original blog post by Lee Han Chung. - Fielding's dissertation on REST. - gRPC and WebSocket documentation. ## 🗣️ Paraphrase: 1. Many developers mistakenly think of MCP as a type of REST API because they both use requests and responses. However, REST is stateless, meaning every interaction is independent, whereas MCP keeps the context alive across multiple interactions, enabling more complex, continuous operations. 2. Treating MCP like REST can lead to significant architectural issues since MCP is built for scenarios requiring persistent state, like streaming or long-lived model conversations. To use MCP effectively, one must design around context retention rather than resetting state on every request. ## 📰 Newsletter: 🚀 **Protocol Confusion Alert!** A recent blog by Lee Han Chung clears up a major misconception: MCP (Model Context Protocol) is *not* a REST API. While REST shines for simple, stateless resource interactions, MCP excels in maintaining context for advanced use cases like live AI model chats or collaborative editing. If you’re building next-gen WordPress integrations or real-time tools, don’t shoehorn MCP into a REST mindset! Dive into the full article for nuanced insights: [Read here](https://leehanchung.github.io/blogs/2025/05/17/mcp-is-not-rest-api/). ## ✅ Action Items: - Integrate this understanding into community training for developers transitioning to MCP. - Develop clear architectural diagrams contrasting MCP vs REST for contributor onboarding materials. - Advocate for explicit protocol documentation in WordPress-related developer guides. - Use these insights to bolster future presentations on protocol design for open-source contributor education. ## 🧪 Hypotheses: - Developers who understand MCP's context-preserving nature will build more robust stateful integrations. - Educational resources highlighting MCP’s differences will reduce misuse and improve system reliability. ### 📊 Methodology: - Conduct workshops comparing REST and MCP architectures. - Survey developers on comprehension before and after MCP-focused training. - Analyze codebases pre- and post-training to identify reduced architectural missteps. ### ❓ Questions: - How can we better visualize MCP’s context flow compared to REST? - What are common pitfalls in misapplying REST patterns to MCP? - How can WordPress contributors benefit from adopting MCP’s principles? ### 🔮 Future Research: - Effectiveness of context-based protocols in large-scale open-source projects. - Impact of protocol education on maintenance and contributor turnover. ### 💡 Implications: - Could drive a shift toward more resilient, context-aware plugin and theme architectures. - May inspire new tooling and abstractions in WordPress core for persistent interactions. ### 🧠 Learning Styles Assessment: **Readability**: Graduate-level technical (approx. grade 14+). - **Visual Learners**: Few visuals; recommend adding diagrams contrasting REST and MCP workflows. - **Aural Learners**: Suggest podcast or video explainer on MCP. - **Verbal Learners**: Strong narrative but could use more analogies. - **Physical Learners**: Include live coding exercises or simulations. - **Logical Learners**: High logical rigor; good match. - **Social Learners**: Facilitate group architectural design reviews. - **Solitary Learners**: Include self-paced quizzes or reflection prompts. - **Naturalistic Learners**: Analogies to natural systems (e.g., rivers maintaining flow) could be introduced. ### 📊 Accessibility Assessment: - **Screen Reader**: Good, no critical visuals. - **Keyboard Navigation**: Fully navigable. - **Contrast and Readability**: Sufficient. - **Text Resizing**: Responsive. ### 🌍 DEIB (Diversity, Equity, Inclusion, and Belonging) Assessment: - **Cultural Relevance**: Neutral; could include more global case examples. - **Inclusive Language**: Generally inclusive. - **Neurodiversity Support**: Clear sections; could benefit from additional headings. - **Representation**: N/A for technical protocol discussion. - **Psychological Safety**: Safe, no sensitive topics. ### ✅ Logical validity: - **Sound Deductive Reasoning**: Clearly distinguishes MCP from REST. - **Strong Inductive Reasoning**: Based on practical architectural patterns. - **No major fallacies** found. - **Tone**: Analytical, clarifying. ### 🔍 DARVO Analysis Prompt: - **Deny**: None. - **Attack**: None. - **Reverse Victim and Offender**: None. - **Overall**: Neutral, factual. ### 🔍 SEO Evaluation: - **Keywords**: "MCP," "REST," "API," "protocol design" — present and well-placed. - **Meta Description**: Needs explicit meta description; recommend including a concise summary. - **Title Tag**: Clear, concise, keyword-inclusive. - **Headers**: Used appropriately. - **Content Length**: Good; detailed but not bloated. - **Links**: Could add internal/external references. - **URL**: Clean and descriptive. - **Images**: No images; suggest adding diagrams. - **Mobile Optimization**: Good. - **User Engagement**: Could improve with interactive diagrams. - **Schema Mark - Summary: This blog post argues against simply wrapping REST APIs with the Model Context Protocol (MCP). MCP, crucial for AI agents, should be designed as action orien... - URL: https://leehanchung.github.io/blogs/2025/05/17/mcp-is-not-rest-api/ Model Context Protocol (MCP) is a prominent technology in 2025, generating buzz comparable to ChatGPT in 2023 and RAG in 2024. However, many common implementations simply create an MCP wrapper over existing API services. This is a **suboptimal design choice**. This blog post will outline the design principles of RESTful APIs, the origins of MCP, Remote Procedure Calls (RPC), and explain why combining these two distinct design philosophies is detrimental to Agent-Computer Interfaces (ACI). #### The Essence of API Design Let’s define the goals of good API design. A well-designed API should be: 1. **Easy to understand.** Other developers (including future you) can grasp each endpoint’s purpose at a glance. 2. **Consistent**. It follows a clear set of conventions, so the mental overhead to learn it stays low. 3. **Extensible**. Versioning and new features can be added without breaking API consumers. 4. **Efficient.** It makes sensible use of network and compute resources. While [“*Premature optimization is the root of all evil*”](https://web.archive.org/web/20130731202547/http://pplab.snu.ac.kr/courses/adv_pl05/papers/p261-knuth.pdf) is a common adage in Computer Science, it doesn’t fully apply to API design. An API is a contract, and changes become very difficult after implementation. Even with versioning, driving adoption of new versions requires significant effort. This is analogous to data schema design. #### REST API Primer REST API is a popular API style focused on resources and the actions performed on them. It uses HTTP as the transport layer and typically serializes data in JSON format. Here’s a simple example REST API of a blog service: * Retrieve all blogs ``` GET /api/blogs ``` * Retrieve a specific post ``` GET /api/blogs/{id} ``` * Create a blog post ``` POST /api/blogs Content-Type: application/json { "Title": "MCP is Not REST API", "Content": "...", "authorId": "12345" } ``` * Update a post ``` PUT /api/blogs/{id} Content-Type: application/json { "Title": "MCP is Not REST API v2", "Content": "...", } ``` * Delete a post ``` DELETE /api/blogs/{id} ``` These API endpoints center around the “blog” resource. Different HTTP methods convey intent: **POST** for create, **GET** for read, **PUT** for update, and **DELETE** for delete. These four operations, *Create*, *Read*, *Update*, *Delete*, are commonly referred to as **CRUD**. This self-documenting structure allows API consumers to quickly understand each endpoint’s function. This clarity contributed significantly to RESTful API’s widespread adoption, making it ideal for CRUD-based SaaS applications. REST APIs are great fit for human-computer interfaces (HCI). Numerous resources online explain MCP, so we will focus on its foundational technologies. MCP is inspired by the Language Server Protocol (LSP). LSP enables code editors (IDEs) to interact with language servers. Language servers provide language specific intelligence that development tools can access via a protocol enabling inter-process communication. This allows code editors to offer features like auto complete, goto definition, and hover over documentations. Language servers communicate using JSON-RPC. RPC (Remote Procedure Calls) can utilize various transport mechanisms, including TCP/IP, HTTP/2, and UDP. Practically, VSCode plugins are LSP servers. Sounds familiar? MCP adopts the same concept as LSP but provides capabilities for LLM agents instead of code editors. It also uses JSON-RPC v2 as its communication layer and supports various transports like stdio and server side events (sse) streaming. So, practically, MCP servers are the equivalent of VSCode plugins, but for Cursor, Windsurf, and Claude Desktop, or other agentic hosts. MCP is an inspired from LSP The reason why we brought up the inspirations for MCP is because at the end of the day, MCP is an RPC. A remote function call. RPC fits the LLM tool use capabilities perfectly, but we digressed. This means MCPs should be designed using RPC best practices. Remote Procedure Call (RPC) APIs aim to make network calls resemble ordinary local function calls. This contrasts with the resource-centric design of REST APIs. RPC emphasizes **actions** over resources. This leads to names like `createUser` or `getBlog`, unlike the resource-based naming in REST APIs. In REST API terms, every RPC is a `POST`. For example, using the modern `gRPC` framework: Define the service ``` syntax = "proto3"; package blog; service BlogService { rpc GetBlog (GetBlogRequest) returns (Blog {} rpc CreateBlog(CreateBlogRequest) returns (Blog) {} } message GetBlogRequest { int32 blog_id = 1; } message Blog { int32 id = 1; string title = 2; string content = 3; int32 author_id = 4; } message CreateBlogRequest { string title = 1; string content = 2; int32 author_id = 3; } ``` Then, after generating the `_pb2` files with protoc, we can call the service from Python: ``` import grpc import blog_pb2 import blog_pb2_grpc def main() -> None: # Connect to the gRPC server with grpc.insecure_channel("localhost:50051") as channel: stub = blog_pb2_grpc.BlogServiceStub(channel) # Get a blog response = stub.GetBlog( blog_pb2.GetBlogRequest(blog_id=12345) ) print("Fetched blog title:", response.title) # Create a new blog new_blog = stub.CreateBlog( blog_pb2.CreateBlogRequest( title="MCP is NOT REST", content="MCP is NOT REST...", author_id=67890, ) ) print("New blog ID:", new_blog.id) ``` The client code closely resembles ordinary function calls like `stub.GetBlog()`, abstracting away the network layer. There’s no manual HTTP construction. JSON-RPC works similarly but uses JSON instead of Protobuf. #### The Pitfalls of Wrapping REST with MCP Given that MCP is fundamentally an RPC mechanism designed for agents to perform actions, attempting to layer it directly on top of a resource-centric REST API introduces significant friction. This “*impedance mismatch*” can severely hinder an agent’s tool-using capabilities. ##### Actions vs. Resources: The Core Conflict As we’ve established: * **MCP/RPC is action-oriented:** Agents think in terms of **verbs**. *“What can I **do**?”* They expect tools that represent discrete functions or capabilities, e.g. `publishBlog`, `summarizeText`, `scheduleMeeting`. * **REST is resource-oriented:** It focuses on **nouns.** *“What resources can I manipulate?”* It uses a fixed set of verbs (GET, POST, PUT, DELETE) to perform CRUD operations on these resources. When an agent wants to achieve a goal, it’s looking for a direct tool to call, or an action. If the MCP layer is merely a thin wrapper over REST, the agent’s natural way of thinking is compromised. ##### Why a Simple REST Wrapper Fails Agents Illustration 1: REST Wrapper fails ai agents 1. **Lost Semantic Meaning and Increased Agent Complexity:** Agents thrive on clarity. An action like `archiveOldBlogPosts(beforeDate="2023-01-01")` is a clear, high-level instruction. If this MCP “tool” is just a facade for a series of REST calls e.g., `GET /api/blogs?status=published\&beforeDate=...`, then for each blog ID, `PUT /api/blogs/{id}` with `{"status": "archived"}`, the agent (or the MCP developer) is forced to translate its high-level goal into a sequence of low-level CRUD operations. The powerful semantic action is lost, replaced by a complex orchestration task. This defeats the purpose of providing agents with high-level tools 2. **Transactionality and Error Handling Nightmares:** Many meaningful agent actions are inherently transactional. They should either complete entirely or not at all. Consider an agent action `transferBlogPostOwnership(blogId, fromAuthorId, toAuthorId)`. This might involve verifying `fromAuthorId` owns the blog, Updating the blog’s `authorId`, Perhaps logging the transfer. If these are separate REST calls, e.g., `GET /api/blogs/{id}`, then `PUT /api/blogs/{id}`, what happens if the `PUT` call fails after the initial checks? The system is left in an inconsistent state. REST APIs are typically stateless and don’t offer built-in transactionality across multiple requests. An RPC, by contrast, can encapsulate this entire logic server-side, ensuring atomicity. Forcing an MCP wrapper or the agent itself to manage this distributed transactionality over REST is complex and error prone. Using our [Agents are Workflows](https://leehanchung.github.io/blogs/2025/05/09/agent-is-workflow/) mental model, an RPC wrapper MCP has a single state and an API wrapper MCP has two states. Two states is more complex to traverse than one. Make agent’s life easier. Don’t increase number states it needs to manage and transition. Graph 1: atomic RPC vs multi-step REST Wrapper 3. **Inefficient Operations and Chatty Interactions:** Agents often need to perform specific, targeted operations. If an agent needs to `incrementLikeCount(blogId)`, but the MCP wrapper only exposes a generic `updateBlog(blogId, blogData)` which maps to `PUT /api/blogs/{id}`), the wrapper might first need to `GET` the full blog, modify the like count, and then `PUT` the entire blog back. This is inefficient. An RPC designed for this action, e.g., `incrementLikeCount` would be far more direct and less data-intensive. Wrapping REST can lead to overly chatty interactions and unnecessary data transfer. 4. **Tool Brittleness and Maintenance Burden:** If the MCP layer is tightly coupled to the specifics of a REST API, any change in the REST API such as renaming endpoints, changes in request and response schema, changes in authentication, etc, can break the MCP tools. The agent’s capabilities become fragile, dependent on the stability of an underlying API not designed for its interaction model. A dedicated RPC interface, designed as a stable contract for agent actions, is more robust. The core issue is that REST APIs are designed for manipulating data states, while agents are designed to execute actions and achieve goals. Forcing MCP to simply be a passthrough or a light translation layer for REST APIs means you are not providing the agent with true “tools” in the sense of capabilities, but rather with a slightly different way to perform CRUD operations. This fundamentally limits what an agent can reliably and effectively do. Instead of empowering agents with high level, robust actions, you saddle them with the complexities and limitations of a data-centric protocol. For effective agent tool use, the APIs (and thus the MCP services) should be designed from the ground up as action-oriented RPCs that directly map to the conceptual tasks the agent needs to perform. #### [Conclusion](https://leehanchung.github.io/blogs/2025/05/17/mcp-is-not-rest-api/#conclusion) Both REST and RPC like MCP have their strengths. REST excels for resource-oriented systems and standard CRUD operations, making it ideal for many web applications and services. MCP, drawing from RPC principles, is tailored for enabling AI agents to perform actions and interact with systems in a more functional, capability-driven way. Trying to force one paradigm onto the other, particularly by simply wrapping a REST API with an MCP layer, often leads to suboptimal outcomes. It can introduce unnecessary complexity, reduce clarity, and ultimately hinder an agent’s ability to effectively use its tools. When designing for AI agents, it’s crucial to provide them with APIs that speak their language - the language of actions and capabilities. This often means designing dedicated RPC style services rather than attempting to repurpose existing REST APIs that were built with a different purpose in mind. Agent-Computer Interaction (ACI) matters when designing APIs for agents. #### References ``` @article{ leehanchung, author = {Lee, Hanchung}, title = {MCP is not REST API}, year = {2025}, month = {05}, howpublished = {\url{https://leehanchung.github.io}}, url = {https://leehanchung.github.io/blogs/2025/05/17/mcp-is-not-rest-api/} } ```, MCP Is Not REST API, Han Lee, 01jzx5dc2js9e1naxxfzg3yhgr.