A facade for MCP tools.

"Summarize the latest sales report and email it to the sales team" is one sentence to a person and four tools to a model: find_document, read_file, get_team_members, send_email. If the model drives, that is four round trips, and each one is a chance to pick the wrong tool, mangle an argument, or lose the thread between the second call and the third. The alternative is one tool, summarize_and_email_report(topic), whose body makes the four calls in code and hands back a confirmation. The model sees one verb.

That is the whole pattern. The Gang of Four called it a facade thirty years ago; the only new thing is where it sits. In the year since I first drafted this, the industry agreed the model should not be driving four tools, then settled on a fix that leaves it driving anyway. This post is about why that fix is a starting point and how to get from it to something you can test.

Problem

Tool noise

MCP did what it promised: one wire format, and an agent can reach any tool, database or API that speaks it. The trouble starts when you hand the model everything it can reach. A dozen granular tools is already noticeable and a hundred is chaos, and the failure has three parts that compound.

The first is context. Every tool definition (name, description, parameter schema) is tokens in the window before the user has said a word. A year ago I had to hedge the threshold. Now there is data: Anthropic has described setups where tool definitions alone pass 50K tokens before the first request, and production telemetry published this year, bucketing tool counts from 1 to 50 on current Claude models, puts the recommended ceiling at ten tools per context. Past that, tool selection gets worse, and so do the arguments.

The second is the round trip. A chain is model, tool A, result, model, tool B, result, and every hop is another prefill, more latency, more spend, and one more place to go wrong.

The third is that the model is a sampler, not an executor. It will hallucinate a parameter, call tools out of order, or handle an error by narrating it. Business logic that lives in the reasoning loop cannot be unit tested, because there is no unit. There is a prompt and a temperature.

Seen from the engineering side, all three are one objective: reduce what the model has to look at and decide on each turn. Call it tool noise. Everything below is a way of spending a noise budget.

This is the workflow-versus-agent choice Anthropic drew in "Building effective agents": either code decides the steps or the model does. The systems that survive production are hybrids, and there are now two of them.

Detour

The answer everyone shipped

Two months after my first draft, Cloudflare published Code Mode and Anthropic published Code execution with MCP, and within a quarter both were product. The idea is the same in both: instead of a catalogue of tools, give the model one tool that runs code, and expose the MCP servers as typed functions the code can call. The model writes a short script, the script runs in a sandbox, and only the result comes back. Anthropic's worked example went from roughly 150K tokens to 2K. Cloudflare's API server exposes 2,500 endpoints through search() and execute() in about a thousand tokens.

If you are still handing the model raw tool lists, stop; this is better. It removes the first problem and most of the second. It does not touch the third.

The model still decides the sequence, per request, at runtime. The script is never reviewed or versioned; it exists for one invocation and is gone. "Check the account has been inactive for 90 days before you archive it" is still a sentence in a prompt, and every destructive function in the sandbox is one line of model-written code away. Cloudflare's docs say as much: code execution does not replace authorisation.

Code mode is a better way to give the model the raw tools. It is not a way to stop the model composing them.

Pattern

The local tool facade

For anyone who has not opened the Gang of Four book in a while: a facade gives a complex subsystem one simplified interface, so the client never touches the internals. The client is the model. The subsystem is the pile of low-level tools across one or more MCP servers. The facade is a tool you write inside the agent's own code, with a task-shaped signature, that runs a fixed sequence against the MCP tools underneath.

Back to the sales report. The model sees summarize_and_email_report and calls it once. The facade finds the document, reads it, resolves the team, sends the mail, handles whatever fails along the way, and returns one line. The model's job shrinks from micro-manager to delegator, which is the job it is good at.

DiagramOne call from the model, four underneath

expandcopy

The difference from code mode is one word: who. In code mode the model composes the sequence and code executes it. With a facade you compose the sequence and code executes it. Both are deterministic when they run. Only one is deterministic before it runs.

The book also says something people forget: a facade does not stop a client from reaching the subsystem directly when it needs to. You trade ease for generality per client. So a code-execution tool sitting next to the facades is not a compromise of the pattern; it is the pattern as written. The model gets summarize_and_email_report for the case you understand and execute(script) for the one you don't.

Layers

Promoted, not designed

A facade written on day one is a guess about the workflow dressed up as an interface. The pattern works as an optimisation over something already understood, and you get there in layers, each promoted from observed use of the one below.

Leaf tools first: the smallest units that are safe, idempotent and unambiguously described. A facade over noisy leaves hides the noise from the model but not from your tests. Most of Anthropic's advice on writing tools is about this layer, and most teams skip it.

Capability facades next: archive_inactive_user, summarize_and_email_report. One business capability, one function, a handful of leaves underneath.

Workflow facades last, if at all: onboard_new_customer calling create_account, provision_workspace and send_welcome_sequence. Two levels is usually where this stops. Three deep means you are modelling the org chart rather than the traffic.

Promotion from one layer to the next needs three things, and you need all of them:

1. The objective is clear. Someone can say what "done" means without saying how.
2. The path is enumerable. You can list the branches, and the list is short. If the next step depends on judgement about an intermediate result (the document turned out to be a spreadsheet; the lookup returned two teams), the model should still be driving that step.
3. The chain recurs, with the same shape, in real traffic.

Miss one and stay a level down. A clear objective with a fuzzy path is a code-mode job. A recurring chain with a fuzzy objective is a product question.

Payoff

What you get

Testability, and it is the one thing code mode cannot give you. The sequence moves out of a sampled reasoning loop and into code you can put under unit and integration tests, and from then on it runs the same way every time.

Cost and latency drop because a multi-turn conversation collapsed into one call, which code mode also gives you. A backend API change touches the facade's body and nothing the model knows about. Tracing one named call beats reconstructing a twelve-step conversation from logs.

And the facade is where policy goes. Exposing delete_database_record to a model is a bad idea, whether as a tool definition or as a function in a sandbox. Exposing archive_inactive_user(user_id) is not, when the facade checks the 90 days before it touches the destructive tool underneath. The model gets least privilege without knowing about it, and the destructive tool is unreachable from anything the model writes.

Cost

What it costs

Start with the cost nobody lists. Criterion three says "recurs in real traffic", and you cannot promote what you cannot see. The default agent loop gives you a transcript, not a sequence. Each tool call needs to be a span with its arguments and result shape, grouped by request, so a recurring chain is a query and not a hunch. If you don't have that, the answer is not "write facades anyway". It is instrument first.

Code mode helps here more than its token savings do. A model-written script is a sequence with its reshaping and error handling already explicit. It is a draft of the facade. Log the scripts, cluster them by shape, and the ones that keep coming back are your promotion list.

Then the code. You write more of it, and before you know which sequences deserve it. That is why the pattern is wrong for a prototype and why the layering exists. The failure on one side is what Fowler calls speculative generality: a facade for the workflows you imagine, with parameters for cases nobody has hit. summarize_and_email_report(topic) is a facade. summarize_and_email_report(topic, audience, format, include_charts, cc_manager, ...) is a DSL the model has to learn, and you have rebuilt the argument-hallucination problem one level up. The failure on the other side is the god facade: one function for twenty unrelated workflows, the file everyone is afraid to touch. Both come from writing the facade before the evidence. One facade per capability, named for the goal: onboard_new_customer, not crm_and_email_api_wrapper.

Determinism cuts the other way too. A facade runs the one workflow it encodes, so a request that needs a combination nobody anticipated fails. That is what the code-execution tool next to it is for.

Fit

Who this is for

The teams who need this most are wrapping existing systems. An MCP server generated from an OpenAPI spec is one tool per endpoint, and it is the biggest source of tool noise in the ecosystem; Cloudflare's 2,500-endpoint server exists because that is what naive wrapping produces. If you own the system, the endpoints are the subsystem, not the interface, and the fix is to write the MCP server at the capability level in the first place. That is the facade living server-side, where it belongs when the server is yours. The in-agent facade is for when the servers underneath are someone else's.

Table

copy

Facade	Code mode
Multi-step business processes: an insurance claim, an employee onboarding	Prototypes, while you are still finding out which chains matter
Anything with real consequences: money movement, writes to a critical database	General assistants and research agents, where the model should pick the sequence
Several agents over shared servers: a FinanceAgent with generate_quarterly_earnings_report and a SalesAgent with create_client_proposal, both over the same GoogleDrive MCP server	One-off compositions that will never recur
The reshaping between tool A and tool B is a business rule	The reshaping is data munging and safe to get wrong
It runs often enough to amortise the code	It runs twice a month and is reversible

Treat the facades as application code, because that is what they are: tests, documentation, error handling, and the same review as anything else on the path to production. The order of work is instrument, clean the leaves, watch, promote. If a sequence is worth running twice it is worth a function. Code mode made rediscovering a sequence cheap. It did not make it correct, and a model that rediscovers it on every request is still doing your job, badly.

Sources

What this leans on

1. Gamma, Helm, Johnson and Vlissides, Design Patterns (1994), for the facade and for the line about clients reaching the subsystem directly. DigitalOcean's Gang of Four explainer is a serviceable refresher.
2. Anthropic: Building effective agents (December 2024), for workflow versus agent; Writing tools for agents (September 2025), for the leaf layer; Code execution with MCP (November 2025) and Advanced tool use, where it shipped as Programmatic Tool Calling.
3. Cloudflare: Code Mode: the better way to use MCP (September 2025), Code Mode: give agents an entire API in 1,000 tokens (February 2026), and the server patterns docs for the authorisation note.
4. MCP server architecture patterns for LLM-integrated applications (2026), for the production tool-count telemetry and the ten-tool ceiling. RAG-MCP (May 2025) for the 13.62% selection baseline at large catalogue sizes.
5. IBM ContextForge, virtual servers, the gateway-side form of the wrapper.
6. Fowler and Beck, "speculative generality", in Refactoring (1999).
7. MCP has been governed by the Agentic AI Foundation under the Linux Foundation since December 2025. The pattern is indifferent to that; the "Anthropic's MCP" framing of the original was not.