REST → MCP: Architecture Transformation Guide

🧩 High-Level Goal

You're not just exposing endpoints anymore — you're exposing "capabilities" that an LLM can invoke, inspect, and reason about within an ongoing session.

🧱 Side-by-Side Architecture Map

Layer	REST API (Stateless)	MCP Server (Stateful)	Δ Transformation
Entry Point	`main.py` runs HTTP server	`server.py` runs message loop	🔁 Replace request/response with message dispatch
Router	`@app.route("/path")`	`@mcp.tool()`	🔁 Path routing → tool routing
Transport	HTTP verbs + routes	JSON-RPC methods	➕ Session persists; multi-step interactions
Schema	OpenAPI / code docs	Auto-extracted from type hints	➕ Machine-readable for LLMs
Context	Each request new (no memory)	Shared context across invocations	➕ Stateful (cache, auth, session)
Discovery	Humans read `/docs`	LLM queries `list_tools`	➕ Self-discoverable
Client	Browser, mobile app	LLM / AI Agent	⚡️ Programmatic reasoning

📁 File Structure Transformation

REST API — Classic Layout

api_server/
├── main.py           # HTTP server
├── routes/
│   ├── users.py      # @app.route('/users')
│   └── orders.py
├── models/
│   ├── user_model.py
│   └── order_model.py
├── services/
│   ├── db_service.py
│   └── cache_service.py
└── utils/
    ├── auth.py
    └── error_handlers.py

MCP Server — Transformed Layout

mcp_server/
├── server.py         # Message loop (stdio/ws)
├── tools/
│   ├── users.py      # @mcp.tool() get_user(id)
│   └── orders.py     # @mcp.tool() create_order()
├── resources/
│   ├── user://{id}   # dynamic URI resource
│   └── inventory://{sku}
├── schema/
│   └── generated.json # JSON-Schema
├── context/
│   ├── state.py      # Session context store
│   └── memory.py     # Persistent across calls
└── transports/
    ├── stdio.py
    └── websocket.py

🧭 Key Transformations:

→ /routes becomes /tools
→ /models becomes /resources (conceptual entities)
→ /services remain same (but injected into context)
+ /context added (state/session layer)

⚙️ Internal Code Transformation

Example 1: Basic Addition Handler

REST API (Flask)

@app.route("/add", methods=["POST"])
def add():
    data = request.json
    result = data["a"] + data["b"]
    return jsonify({"result": result})

MCP Server

@mcp.tool()
async def add(a: int, b: int) -> int:
    return a + b

Key difference: MCP uses tool name + schema routing instead of path + method. Input/output validation comes from type hints automatically.

Example 2: Stateful Context Handling

REST (Stateless)

@app.route("/cart", methods=["POST"])
def add_to_cart():
    user = request.headers["User"]
    cart = db.get_cart(user)
    cart.add(request.json["item"])
    db.save_cart(cart)
    return jsonify({"message": "ok"})

MCP (Stateful)

@mcp.tool()
def add_to_cart(ctx: Context, item: str):
    cart = ctx.session.get("cart", [])
    cart.append(item)
    ctx.session["cart"] = cart
    return {"cart_size": len(cart)}

Δ Transformation: Session is in-memory, persists across tool invocations — useful for reasoning and chaining.

🧠 REST → MCP Concept Mapping

REST Concept	MCP Equivalent	Remarks
Route	Tool	Invokable function, schema-aware
GET /resource/:id	read_resource("uri")	Accesses a resource handler
POST /data	invoke_tool("tool_name")	Calls a capability
Request.headers	Context.session	Holds user/session info
Middleware	Hook / Lifespan	Pre/post invocation wrappers
OpenAPI	MCP Schema	Generated from annotations
404	Error.code=32001	JSON-RPC error variant

⚖️ Summary of Trade-offs

Aspect	REST (+)	MCP (+)	Comment
Simplicity	✅ Very simple	⚠️ More complex	REST easier for humans
AI Integrability	❌ Hard (needs wrapper)	✅ Native	MCP made for LLMs
State	❌ Stateless	✅ Stateful	Enables tool chaining
Discoverability	🧍 Manual docs	🤖 Auto via list_tools	Self-describe
Security	Mature	Evolving	Requires trust boundary design
Performance	High (HTTP optimized)	Medium (RPC overhead)	But fine for tool calls
Purpose	Web & API apps	AI orchestration	Complementary layers

🧭 Big Picture

MCP doesn't replace REST; it wraps or extends it — turning traditional endpoints into introspectable, schema-aware, conversational tools.

"An RPC façade for LLMs, sitting on top of APIs that were originally built for humans."