Edward's BlogPost

From Agentic Programming to Loop Engineering

2026-07-10T22:07:05+08:00

The shift in one sentence</h2>
Loop engineering is the move from prompting an AI agent by hand to designing the system that prompts it for you. The leverage stops living in the quality of a single prompt and moves into the design of the wrapper that generates prompts, checks the result, and decides whether to run again.
The term crystallized in the second week of June 2026, off a couple of widely-shared posts. The one people keep quoting is Boris Cherny, creator of Claude Code at Anthropic:

I don't prompt Claude anymore. I have loops that are running. They're the ones that are prompting Claude and figuring out what to do. My job is to write loops. </blockquote>
That single reframing — my job is to write loops — is the whole idea. You stop being the conversationalist inside the turn-by-turn exchange and become the person who builds the runtime that runs the exchange without you.
A common misconception: "loop = a well-defined, harnessed automated flow"</h2>
A natural first read of the word is that a "loop" is just an automated flow — take agentic programming, make it repeatable, wrap it in a harness, done. That captures something real, but it undersells the actual claim in two ways.
First, it misses the inversion of control. The point isn't that the flow is automated; it's that the author of the prompts changes. The agent isn't waiting for your next message — the loop is. You supply a goal once, and the machinery iterates.
Second, "harnessed" is borrowed from the layer below. The community frames loop engineering as the fourth rung in a lineage:

prompt engineering → context engineering → harness engineering → loop engineering </blockquote>
Harness engineering is its own prior step: the harness is the tool surface, the sandbox, the scaffolding the agent acts through. "Well-defined and harnessed" is a precondition you inherit from that layer. Loop engineering sits above it and adds three things the harness doesn't have: a trigger, a verifiable goal, and — the part that's actually hard — the guardrails that decide when to stop.
Anatomy of an agentic loop</h2>
Stripped down, a loop needs only two ingredients:

A trigger — something that starts it (a PR opening, a schedule, a human saying "go").</li>
A verifiable goal — a defined end state the agent works toward (all tests pass, CI green, a /goal</code> condition graded by a separate model).</li> </ul> Given those, the agent runs a cycle: Observe the current state (read files, run a test, take a screenshot).</li> Evaluate the result against the goal.</li> Decide — continue, stop because it succeeded, or stop because it's blocked or out of budget.</li> Act — take one bounded step, then observe again.</li> </ol> It keeps going until the goal is met or a stopping condition fires. You give it a goal, not a prompt. The real work is on the stopping side</h2> Here's the counterintuitive part: the repetition scaffolding is trivial — it's a while</code> loop, one line any programmer can write. The engineering is almost entirely in halting well. The canonical production failures are not edge cases: Infinite loops — the loop never satisfies its exit condition.</li> Goal drift — the target quietly mutates across iterations until the agent is solving the wrong problem.</li> Token-cost explosions — an unbounded loop burns budget with nothing to show.</li> Mode collapse / "spinning" — a loop that retries the same action after the same error isn't learning; it's spinning.</li> </ul> As one field guide put it: the production version of the job is that you write the loops, and most of your work is making sure they halt. The archetype: Ralph, productized</h2> Everyone traces the pattern back to the Ralph loop. Ralph sidesteps context rot by making every iteration a fresh agent with a clean context that reads the current repo state and task list from disk, does exactly one unit of work, commits, and exits. The intelligence doesn't live in one heroic run — it lives in clear, granular specs and verifiable outcomes applied over and over against an external memory the model can't pollute. A tidy way to describe the current state of the art: Loop engineering is Ralph, productized. </blockquote> The while</code> loop becomes a scheduled automation, the context reset becomes a worktree plus a sub-agent, and the ALL TASKS DONE</code> grep becomes a /goal</code> condition graded by a separate model. Same shape, fewer sharp edges. That last detail — the grader being a different model from the generator — is the familiar critic-must-not-equal-generator principle, now baked into the loop's exit condition. The core distinction: goal-seeking, not routine</h2> So can we conclude the "loop" is not a routine but a process of goal-seeking? Yes — with one refinement that makes the conclusion stronger, not weaker. A loop is implemented as a routine but is not essentially one. The word borrows from control flow — there's a literal while</code> underneath — but that repetition is the dumb, deterministic part. The substance is the goal-seeking: observe, evaluate against a verifiable goal, decide, halt or continue. The cleanest way to state the difference: A routine repeats the same actions. A loop repeats the same question. </blockquote> The actions differ every iteration — different file, different fix, different test — but the question is constant: "Is the goal met, and if not, what's the best next move?" A cron job or an RPA script is a genuine routine: fixed steps, no evaluation, no adaptation. If the environment shifts, it either breaks or blindly repeats. The agentic loop is defined precisely by not being that. And here's what vindicates the framing hardest: when a loop degenerates into a routine, that's the bug. "Spinning" and mode collapse are exactly the case where the loop stops asking the question and just repeats an action. Collapsing into a fixed routine is the canonical failure of loop engineering — not its definition. So the sharpest conclusion isn't merely "loop = goal-seeking, not routine." It's that goal-seeking and routine are the two poles, and loop engineering is the discipline of keeping the process pinned to the goal-seeking pole — via the verifiable goal and the halt conditions — so it never decays into a spinning routine on one side or an unbounded wander on the other. The routine is what you get when the loop stops thinking; the goal is what keeps it a loop. Where this meets a real orchestration stack</h2> Most of the current writing implicitly assumes a single cloud coding agent (Claude Code, Codex) driving the loop. But the pattern generalizes cleanly to formal orchestration and heterogeneous fleets: Escalation ladders, hard retry ceilings, and human gates at requirements / architecture / pre-merge are the halt conditions and guardrails the blog discourse is now naming. A Temporal-style workflow is loop engineering with a rigorous orchestrator underneath — the opposite end of the rigor spectrum from a while true</code> + grep</code>, but the same shape.</li> Heterogeneous fleets sharpen the "who prompts whom" inversion: when the loop driver and the loop workers are different models on different silicon (e.g. a strong orchestrator model dispatching to local executor models), the halt-condition grading may want to live on a specific tier — and the critic-must-not-equal-generator rule can be enforced at the hardware level, not just the prompt level.</li> The academic framing (see the arXiv paper Agentic Software Engineering: Foundational Pillars and a Research Roadmap, 2509.06216) proposes Agentic Loop Engineering (ALE) as disciplined, DevOps-lineage orchestration — a declarative LoopScript</code> producing a "Merge-Readiness Pack." It's a useful vocabulary for anyone already hand-rolling this in a workflow engine.</li> </ul> TL;DR</h2> Loop engineering = designing the system that prompts, checks, remembers, and re-runs an agent — instead of typing each instruction yourself.</li> It's the fourth layer: prompt → context → harness → loop. "Harnessed and automated" is a precondition it inherits, not what makes it a loop.</li> A loop = trigger + verifiable goal + iteration + halt conditions. The hard engineering is the halting.</li> The "loop" is goal-seeking, not routine. A routine repeats actions; a loop repeats a question. When it collapses back into a routine ("spinning"), that's the failure mode — which is exactly why the goal-seeking reading is the right one.</li> </ul> Written from a working conversation, July 2026. Sources for the June 2026 framing include commentary from Boris Cherny (Claude Code), the Ralph loop pattern, and the arXiv "Agentic Software Engineering" roadmap (2509.06216).



Plain RAG vs. Agentic RAG: It's the Control Flow, Not the Plumbing
2026-07-10T21:08:38+08:00
</p>
Retrieval-Augmented Generation gets discussed as if "RAG" and "agentic RAG" were two different architectures. They mostly aren't. They're two different control flows</em> over the same parts. Getting that distinction right changes how you build, and — as we'll see — it means the same retrieval tool can be plain RAG one day and agentic RAG the next, with nothing changed but the loop around it.</p>
</p>
Plain RAG: retrieval wired into generation</h2>
Plain RAG is a linear, one-shot pipeline:</p>

query → embed → vector search → top-k chunks → generate → answer</p>
</blockquote>
The retrieval step is deterministic and happens exactly once, orchestrated by your</em> code rather than by the model. The LLM never decides whether to retrieve, what to retrieve, or whether what came back was any good. It consumes whatever the pipeline hands it and composes an answer.</p>
Two things are worth stating precisely, because the casual mental model ("similarity fetches the relevant content, the model just stitches it together") oversells both halves.</p>
First, vector search returns semantic proximity in embedding space</strong> — nearest neighbours by cosine or dot-product. That is not</em> the same thing as relevance. Chunks can sit close to the query vector and still be useless, and the genuinely relevant chunk can fall just outside your top-k. Similarity is a lossy proxy for "actually answers the question." What you retrieve is plausibly related</em> content, not guaranteed-relevant content.</p>
Second, the model is doing more than concatenation. It reads the retrieved chunks as grounding, resolves conflicts between them, decides what to ignore, and synthesises. But the intuition underneath is correct and important: in plain RAG the retrieval is dumb and the generation is where the intelligence sits</strong>. That asymmetry is the whole reason the agentic variant exists.</p>
Agentic RAG: retrieval governed by generation</h2>
Agentic RAG promotes retrieval from a fixed pipeline stage to a tool the model invokes inside a reasoning loop</strong>. Now the model exercises judgment over retrieval. It can:</p>

decide whether retrieval is needed at all,</li>
decompose a complex question into sub-queries (multi-hop),</li>
rewrite a query that returned weak results and try again,</li>
route between multiple sources — a vector store, SQL, a graph index, the web,</li>
and — the crucial one — grade what came back and re-retrieve</strong> before committing to an answer.</li>
</ul>
This is the family that includes patterns like corrective RAG and self-RAG: the model checks its own grounding and corrects course. In the animation above, that's the amber loop — the pulse reaches Grade</em>, judges the evidence thin, and arcs back to Retrieve</em> to rewrite and try again, twice, before it finally answers. The plain-RAG pulse, meanwhile, has long since finished and is just waiting.</p>
The comparison</h2>
Dimension</th> Plain RAG</th> Agentic RAG</th></tr></thead>

Control flow</td> Static pipeline (fixed DAG)</td> Dynamic, model-driven loop</td></tr>
Who orchestrates</td> Your code</td> The model</td></tr>
Query handling</td> Single embedded query</td> Decomposition, multi-hop, rewriting</td></tr>
Sources</td> Usually one vector store</td> Many tools, routed between</td></tr>
Self-correction</td> None</td> Grading + re-retrieval</td></tr>
Cost & latency</td> Low, predictable</td> Higher, variable</td></tr>
Best for</td> Straightforward lookup</td> Ambiguous or multi-hop queries, heterogeneous corpora</td></tr>
</tbody></table>
A one-line way to hold it: plain RAG is retrieval wired into</em> generation; agentic RAG is retrieval governed by</em> generation.</strong> The tradeoff is exactly what you'd expect — robustness on hard queries in exchange for determinism, latency, and token spend. For a lot of everyday lookup workloads, plain RAG is still the right call. The agentic layer earns its cost when queries genuinely need planning or the corpus is heterogeneous.</p>
Building RAG as an MCP tool</h2>
A natural instinct is to expose retrieval as an MCP tool — something like search_knowledge_base(query, k, filters)</code> returning ranked chunks with metadata — and let an agent call it. This is arguably the cleanest way to express agentic RAG, because it is</em> the "retrieval as a tool the model governs" pattern made concrete.</p>
But here's the subtlety that trips people up: the transport doesn't determine the category — the control flow does.</strong></p>
If the agent calls the retrieval tool once, takes whatever comes back, and composes it into an answer, that's plain RAG. It's plain RAG that happens to be plumbed through</em> MCP. Wrapping retrieval in a tool interface doesn't make it agentic. The loop still collapses to a straight line — call → compose — the same shape as query → search → generate, just with an MCP hop in the middle.</p>
Agentic-ness is a property of the trajectory</strong>, not the architecture. The very same MCP tool behaves either way depending on what the agent does with it:</p>

Always calls it once, regardless of the query, never re-examines → plain RAG</strong>.</li>
Decides per-query whether to call it, rewrites and re-calls on weak results, routes between tools, grades before answering → agentic RAG</strong>.</li>
</ul>
So you can ship one search_knowledge_base</code> tool and have it be "normal RAG" on Monday and "agentic RAG" on Tuesday, purely by changing the orchestration prompt and the loop around it. The tool is identical; the behaviour is what moves it across the line.</p>
Design notes if you go the MCP route</h3>

The tool description is the contract.</strong> In MCP, the tool description is runtime model input</em>, not just documentation — it's what the agent reads to decide when to call the tool and how to phrase the query. A vague description means the agent retrieves at the wrong times, or collapses to a single blind call. This is the highest-leverage thing to get right. If your intent is agentic behaviour but the agent keeps doing one unconditional call, that's usually a description-or-prompt problem, not an architecture problem: the model wasn't given the signal (or the permission) to retrieve conditionally, rewrite, and re-check.</li>
Return structure matters more than in plain RAG.</strong> Because the agent may re-retrieve, return scores, source IDs, and chunk provenance — not just concatenated text — so the model can grade relevance and decide whether to go again.</li>
Granularity is a real fork.</strong> One generic search</code> tool vs. several typed tools (search_code</code>, search_docs</code>, search_graph</code>) is a genuine design decision. Multiple typed tools hand the agent a routing signal for free; a single generic tool pushes that routing logic into the query. If you have more than one retrieval primitive</em> — say embedding similarity and</strong> a graph-expansion method like Personalized PageRank — exposing them as separate tools lets the agent do a "seed then expand" pattern: similarity to find entry points, graph expansion to grow the neighbourhood. Neither primitive does that alone, and the agent combining them is exactly the kind of judgment that makes RAG agentic.</li>
</ul>
Takeaway</h2>
Don't reach for "agentic RAG" because it sounds more capable. Reach for it when the trajectory</em> your queries need — conditional retrieval, rewriting, grading, multi-source routing — actually justifies the extra round-trips. If a single retrieval pass answers the question, a single retrieval pass is the correct design, MCP tool or not. The intelligence you're paying for in agentic RAG isn't the retrieval; it's the model deciding how to retrieve</em>.</p>


MCP Is Not a New Paradigm: What It Actually Standardizes, and How to Design For It
2026-07-10T13:30:00+08:00
TL;DR</h2>
The Model Context Protocol (MCP) is best understood not as a new kind of API but as a standardized profile of existing API patterns</strong> — JSON-RPC 2.0, plus mandatory runtime introspection, plus Backend-for-Frontend–style aggregation — specialized for one unusual consumer: a stochastic, forgetful model that self-discovers your capabilities and re-reads your interface on every turn.</p>
Almost all the mechanics transfer from ordinary API design. What is genuinely MCP-specific is narrow: enforced uniform discovery (so a generic client works against a server it has never seen), a few LLM-native semantics (sampling, elicitation, the tools/resources/prompts trichotomy), and the fact that your tool descriptions stop being documentation and become runtime input that steers model behavior.</p>

1. What MCP is, mechanically</h2>
Strip the branding and MCP is:</p>

JSON-RPC 2.0</strong> as the wire format.</li>
A fixed, standardized method vocabulary</strong>: initialize</code>, tools/list</code>, tools/call</code>, resources/read</code>, prompts/list</code>, and so on.</li>
A mandatory discovery handshake</strong>: a client connects knowing nothing, calls tools/list</code>, and receives the full menu with machine-readable JSON schemas.</li>
</ul>
Your add(a, b)</code> function is not reachable at some URL you chose. It is reachable via tools/call</code> with {"name": "add", ...}</code>. The consumer is an LLM/agent that does not know your API in advance: it connects, enumerates capabilities, reads the schemas, and decides at runtime what to invoke.</p>
MCP exposes three primitives:</p>

Tools</strong> — actions the model can invoke.</li>
Resources</strong> — read-only context the model or client can pull.</li>
Prompts</strong> — reusable templates/instructions.</li>
</ul>
Transport can be stdio, streamable HTTP, or SSE. HTTP is just one option; MCP is not "an HTTP API."</p>

2. MCP vs REST: who is the caller?</h2>
Both speak over a transport. They answer different questions.</p>
</th> REST / OpenAPI</th> MCP</th></tr></thead>

Standardizes</td> Exposing resources</strong> to programs</td> Exposing capabilities</strong> to models</td></tr>
Consumer</td> A developer who reads docs, holds state, orchestrates deliberately</td> A model that sees a flat menu, picks under token pressure, has no memory of your workflow</td></tr>
Contract delivery</td> Out-of-band</strong> — you must already hold the endpoints/shapes before you can call</td> In-band</strong> — the contract travels with the connection; discovered through the communication itself</td></tr>
Discovery</td> Optional, heterogeneous (some ship OpenAPI, some don't)</td> Mandatory and uniform</strong> — the reason a generic client can connect to any server</td></tr>
Granularity unit</td> One resource operation (POST /carts/{id}/items</code>)</td> One unit of user intent (place_order</code>)</td></tr>
</tbody></table>
The relationship is clearest in one fact: FastMCP can generate an MCP server from a FastAPI app or an OpenAPI spec.</strong> MCP sits a layer up. FastAPI is how you expose an API to programs you control; MCP is how you expose capabilities to an agent you don't, in a form it can enumerate and reason about.</p>
Rule of thumb:</strong> if a service is called by code you write, plain REST/gRPC is simpler and faster. Reach for MCP when the caller is a model that needs to discover and choose</em> tools. For deterministic plumbing between machines you control, MCP adds protocol overhead you don't need.</p>

3. The in-band vs out-of-band distinction</h2>

MCP is self-describing.</strong> A caller with zero prior knowledge can obtain the full capability set purely through the communication. Discovery is part of the required method set.</li>
Plain REST is prior-knowledge.</strong> Nothing in the wire format obligates the server to describe itself, so the caller must already possess the contract. OpenAPI exists, but it's a separate document a human fetches and wires up ahead of time — bolted on, aimed at humans and build-time codegen, not intrinsic to the call vocabulary.</li>
</ul>
Important correction to a common overstatement:</strong> in-band runtime discovery is not</em> unique to MCP. GraphQL introspection queries the schema at runtime through the same endpoint. gRPC server reflection enumerates services and methods without prior stubs. Both are self-describing and discovered through the communication itself. The property is a general</em> API capability that MCP happens to require</strong>. gRPC can</em> do reflection; MCP mandates</em> it. That mandate — not the capability itself — is what lets a generic client work everywhere.</p>

4. The dominant pattern (wrap an existing API) and its failure mode</h2>
Most MCP servers in the wild wrap an existing API. That's not wrong. The failure mode is doing it too literally</strong>: a 1:1 mapping where every REST endpoint becomes one tool.</p>
The temptation is natural because REST endpoints and MCP tools are both "callable operations," and OpenAPI-to-MCP generators produce exactly this. It's a great starting point</em> and a fine way to see what a model actually reaches for. But an API contract is designed for a programmer who reads docs, holds state, and sequences calls deliberately. An MCP tool is consumed by a model that sees a flat menu, picks under token pressure, and has no memory of your intended workflow. Different audiences.</p>
Where the thin wrapper goes wrong:</p>

Granularity mismatch.</strong> A workflow that a human chains correctly (create cart → add items → apply coupon → checkout) becomes a call-ordering puzzle the model fumbles. Often the right tool is one that hides the choreography.</li>
Schema noise.</strong> Auto-generated tools inherit every optional field, pagination param, and internal ID. That's schema the model must read and reason over every turn — token cost and a source of wrong calls.</li>
Return shape.</strong> APIs return complete objects; a model usually needs a compact projection, not the raw payload.</li>
Tool-count blowup.</strong> 60 endpoints → 60 tools degrades selection accuracy. Curation and tag-based filtering matter.</li>
</ul>
Better framing:</strong> the API is the transport layer underneath</em> your MCP server, not the design of it. Wrap the API, but redesign the surface</strong> — task-oriented tools, trimmed schemas, projected outputs — treating the model as the user you're doing UX for.</p>
Gut check:</strong> if a competent teammate would need your API docs open to use the tool correctly, the model will struggle too.</p>

5. Worked example: order management</h2>
The underlying REST API</h3>
POST /carts                      → {cart_id}</span></span>
POST /carts/{id}/items           → add one line item</span></span>
GET  /catalog/products?q=...     → search, paginated</span></span>
POST /carts/{id}/apply-coupon    → {discount}</span></span>
GET  /carts/{id}                 → full cart w/ totals</span></span>
POST /carts/{id}/checkout        → requires payment_method_id</span></span></code></pre>Thin 1:1 wrapper (the tempting mistake)</h3>
@mcp</span>.</span>tool</span></span>
def</span> create_cart</span>()</span> -></span> dict</span>:</span> ...</span></span>
</span>
@mcp</span>.</span>tool</span></span>
def</span> add_item</span>(</span>cart_id</span>:</span> str</span>,</span> product_id</span>:</span> str</span>,</span> qty</span>:</span> int</span>,</span></span>
             gift_wrap</span>:</span> bool</span> =</span> False</span>,</span> warehouse_hint</span>:</span> str</span> |</span> None</span> =</span> None</span>,</span></span>
             price_override_cents</span>:</span> int</span> |</span> None</span> =</span> None</span>)</span> -></span> dict</span>:</span> ...</span></span>
</span>
@mcp</span>.</span>tool</span></span>
def</span> search_products</span>(</span>q</span>:</span> str</span>,</span> page</span>:</span> int</span> =</span> 1</span>,</span> page_size</span>:</span> int</span> =</span> 20</span>,</span></span>
                    sort</span>:</span> str</span> =</span> "relevance"</span>,</span> locale</span>:</span> str</span> =</span> "en-US"</span>)</span> -></span> dict</span>:</span> ...</span></span>
</span>
@mcp</span>.</span>tool</span></span>
def</span> apply_coupon</span>(</span>cart_id</span>:</span> str</span>,</span> code</span>:</span> str</span>)</span> -></span> dict</span>:</span> ...</span></span>
</span>
@mcp</span>.</span>tool</span></span>
def</span> get_cart</span>(</span>cart_id</span>:</span> str</span>)</span> -></span> dict</span>:</span> ...</span></span>
</span>
@mcp</span>.</span>tool</span></span>
def</span> checkout</span>(</span>cart_id</span>:</span> str</span>,</span> payment_method_id</span>:</span> str</span>)</span> -></span> dict</span>:</span> ...</span></span></code></pre>
To buy two items with a coupon, the model must: create a cart, thread the returned cart_id</code> into search, parse a paginated result to pick a product_id</code>, add each item, apply the coupon, then check out with a payment_method_id</code> it has to source from somewhere. Six-plus turns, strict ordering, hand-carried state. Every schema carries noise (warehouse_hint</code>, price_override_cents</code>, locale</code>, pagination) the model must read past. And get_cart</code> returns the whole object when the model wanted one number.</p>
Redesigned surface (task-oriented)</h3>
@mcp</span>.</span>tool</span></span>
def</span> find_products</span>(</span>query</span>:</span> str</span>,</span> max_results</span>:</span> int</span> =</span> 5</span>)</span> -></span> list[</span>dict</span>]:</span></span>
    """Search the catalog. Returns [{product_id, name, price}]."""</span></span>
    raw</span> =</span> api</span>.</span>get</span>(</span>"/catalog/products"</span>,</span> params</span>=</span>{</span>"q"</span>:</span> query</span>,</span> "page_size"</span>:</span> max_results})</span></span>
    # projection: drop everything the model doesn't need to decide</span></span>
    return</span> [{</span>"product_id"</span>:</span> p[</span>"id"</span>]</span>,</span> "name"</span>:</span> p[</span>"name"</span>]</span>,</span></span>
             "price"</span>:</span> p[</span>"price_cents"</span>]</span> /</span> 100</span>}</span> for</span> p</span> in</span> raw[</span>"items"</span>]]</span></span>
</span>
@mcp</span>.</span>tool</span></span>
def</span> place_order</span>(</span>items</span>:</span> list[OrderItem]</span>,</span> coupon</span>:</span> str</span> |</span> None</span> =</span> None</span>,</span></span>
                payment_method_id</span>:</span> str</span> =</span> Depends</span>(get_default_payment))</span> -></span> dict</span>:</span></span>
    """Create a cart, add all items, apply an optional coupon, and check out</span></span>
    in one call. items = [{product_id, quantity}]. Returns {order_id, total, status}."""</span></span>
    cart</span> =</span> api</span>.</span>post</span>(</span>"/carts"</span>)[</span>"cart_id"</span>]</span></span>
    for</span> it</span> in</span> items</span>:</span></span>
        api</span>.</span>post</span>(</span>f</span>"/carts/</span>{</span>cart</span>}</span>/items"</span>,</span></span>
                 json</span>=</span>{</span>"product_id"</span>:</span> it</span>.</span>product_id</span>,</span> "qty"</span>:</span> it</span>.</span>quantity})</span></span>
    if</span> coupon</span>:</span></span>
        api</span>.</span>post</span>(</span>f</span>"/carts/</span>{</span>cart</span>}</span>/apply-coupon"</span>,</span> json</span>=</span>{</span>"code"</span>:</span> coupon})</span></span>
    result</span> =</span> api</span>.</span>post</span>(</span>f</span>"/carts/</span>{</span>cart</span>}</span>/checkout"</span>,</span></span>
                      json</span>=</span>{</span>"payment_method_id"</span>:</span> payment_method_id})</span></span>
    return</span> {</span>"order_id"</span>:</span> result[</span>"id"</span>]</span>,</span> "total"</span>:</span> result[</span>"total_cents"</span>]</span> /</span> 100</span>,</span></span>
            "status"</span>:</span> result[</span>"status"</span>]}</span></span></code></pre>
Two tools instead of six. The moves that mattered:</p>

Collapsed the workflow</strong> into one tool so call-ordering can't be gotten wrong.</li>
Depends(get_default_payment)</code></strong> injects the payment method server-side, so it never appears in the schema and can't be hallucinated or leaked.</li>
Projected outputs</strong> — three fields, not the raw paginated payload; a 3-key summary, not the full order object.</li>
Dropped internal knobs</strong> (warehouse_hint</code>, price_override_cents</code>) from the model-facing surface. They still exist in the API; the model just doesn't see them.</li>
</ul>
In FastMCP 3.0 you express this without hand-writing every wrapper: source the raw tools from the OpenAPI spec via a Provider</strong>, then apply Transforms</strong> — place_order</code> is a custom tool, find_products</code> is the raw endpoint with an output transform plus hidden params, and internal endpoints get filtered out by tag. The API stays the transport; the Transform chain is where the model-facing UX lives.</p>

6. Does this violate Single Responsibility?</h2>
No — it relocates</strong> it. SRP is about one reason to change, not one HTTP call. place_order</code> has a single responsibility: "fulfill the intent of ordering." Making four API calls internally is an implementation detail, exactly like a service-layer OrderService.placeOrder()</code> that touches carts, coupons, and payments. Nobody calls that an SRP violation.</p>
The unit SRP applies to differs by layer:</p>

REST endpoint:</strong> one responsibility = one resource operation.</li>
MCP tool:</strong> one responsibility = one unit of user intent.</li>
The thin 1:1 wrapper</strong> actually has worse</em> cohesion — it spreads one responsibility (placing an order) across six tools plus the model's reasoning, forcing the model to become the orchestrator. That's the real SRP smell.</li>
</ul>
SRP is defined relative to the consumer. The consumer changed, so the grain got coarser. Same principle.</p>

7. Is MCP "a standard for API design"?</h2>
It's a wire protocol standard</strong>: it standardizes the transport, the method vocabulary, and the discovery handshake. It does not</strong> standardize how you design the tool surface. No spec clause says "collapse workflows" or "project outputs." All the design advice above is convention and emerging best practice, not protocol. MCP standardizes the envelope, not the content.</strong></p>
Consequence: a 1:1 REST-wrapping server is fully protocol-compliant and</em> often badly designed — the same way a REST API with 40 endpoints named /doStuff1</code>, /doStuff2</code> is valid HTTP and bad design. Compliance and good design are orthogonal.</strong></p>

8. So are MCP's design patterns just general API design?</h2>
Largely, yes — this is the key realization.</p>
The design advice (collapse workflows, project outputs, coarse task-level granularity) is the Backend-for-Frontend (BFF)</strong> pattern. An MCP server is essentially a "Backend for Model"</strong>: an aggregation/adaptation layer shaped for one specific consumer, exactly like a BFF aggregates chatty microservice calls into one endpoint tuned for a mobile client. place_order</code> isn't an MCP idea; it's good API design that a forgiving human developer will tolerate you skipping and a model won't.</p>
What is genuinely</em> MCP-specific is narrow:</p>

Standardization / universality.</strong> REST discovery is optional and heterogeneous. MCP mandates one uniform discovery handshake — the whole reason a generic client can connect to any server it's never seen. A property of the standard</em>, not the pattern.</li>
A few LLM-native semantics.</strong> Sampling</strong> (the server asks the client's LLM to generate mid-call) and elicitation</strong> (the server asks the client to prompt its user) have no clean equivalent in a normal API. Even these are callback patterns underneath, but the tools/resources/prompts trichotomy is a deliberate semantic layer aimed at a model.</li>
Descriptions become runtime input, not docs.</strong> The subtle one. In a human API, a field description is documentation — read once, then ignored at runtime. In MCP, the tool description and schema are injected into the model's context and steer selection on every call</em>. Your naming and docstrings stop being annotation and become part of the program's behavior. No conventional API has this property, because human consumers don't recompile their intent from your docstring each turn.</li>
</ol>

9. The one-liner to remember</h2>

MCP is a standardized profile of existing API patterns (JSON-RPC + mandatory introspection + BFF-style aggregation), specialized for a stochastic, forgetful, self-discovering consumer.</strong></p>
</blockquote>
The mechanics transfer almost entirely. What doesn't reduce is the enforced uniformity</em> (so a generic client works everywhere) and the fact that your interface copy is now runtime input rather than reference material.</p>
Push it one step further and most of "MCP design" is really just "API design where the consumer can't read your docs, won't hold state for you, and re-reads the menu every turn."</strong> Constraints, not a new discipline.</p>

Design checklist for an MCP server</h2>


Are tools shaped around units of intent</strong>, not units of REST?</li>

Have you collapsed multi-step choreography</strong> so the model can't mis-order calls?</li>

Are schemas trimmed</strong> to only what the model should decide on? Internal knobs hidden?</li>

Are outputs projected</strong> to the relevant fields, not raw payloads?</li>

Is the tool count</strong> small enough to preserve selection accuracy? (Curate / tag-filter.)</li>

Are secrets/credentials/IDs injected server-side</strong> (e.g. dependency injection) rather than exposed in schemas?</li>

Do tool names and descriptions</strong> read as clear instructions to a model, given they're runtime input?</li>

Gut check: could a teammate use each tool without your API docs open</strong>?</li>
</ul>