DEV Community: David Golverdingen

What Is an MCP Server? A Production Guide for Agentic AI

David Golverdingen — Sun, 20 Sep 2026 13:42:27 +0000

An MCP server is a standard way to give an AI application access to outside systems. It exposes tools, data and context that the application can discover and use through the Model Context Protocol. That is the textbook answer, and it is the easy half.

Here is the half the textbook leaves out.

A project manager asks the agent which of last quarter's projects lost money. The agent is connected to the ERP through exactly such a server. It comes back with a short, confident list of projects, and the list is wrong.

Nothing was broken. The connection worked, the query ran, the data came back. What the agent did not know is that this company books retail projects without a fiscal year, so the "last quarter" filter quietly dropped a whole class of them; that the margin field it sorted on is calculation-internal and not what the customer actually paid, so projects surfaced as losses that were never losses at all; and that a project code starting with R means something different from one starting with G. The values are in the database. The rules for interpreting them are not. They live in the heads of the four people who have worked here longest.

The connection did its job. What was missing was the meaning, and that is the difference between an MCP server that works in a demo and one that holds up in production. Reaching the data is the part the protocol standardises. Carrying the meaning is the part that falls to you, and it is the half most MCP explainers barely mention.

I run twelve of them in production at a roughly 350-person HVAC company, 97 tools across the estate, used on a given day by around twenty project managers and back-office staff and by more than a hundred people over the past few months. Most of them have never written a line of code. Some of the numbers in this post are unflattering, and they are the reason it is worth writing another explainer at all: every other one paraphrases the spec, and the spec cannot tell you what happens when non-developers ask real questions of real business data.

The half the protocol handles, and the half it doesn't

For this post, I use agent for a model-driven system that can choose and invoke actions, rather than only generate a response. To do anything useful it needs two things: a way to reach a system, and a way to know what it is looking at.

Before MCP, reaching a system often meant bespoke integration work, one connector per tool per client, rebuilt each time the client changed. MCP standardised that boundary. A server exposes tools, any compatible client can call them, and the same server can be reused across compatible clients instead of rebuilding the integration around every model or application. The protocol handles that half well, which is why it spread as fast as it did. Not everything around it is settled, auth and discovery and deployment are still real engineering, but the protocol surface is standardised now.

The second half was getting far less attention when I started, and it is the one the opening turns on. Reaching the ERP was never the problem. Knowing that R and G mean different things was.

What an MCP server actually is

An MCP server can expose several things to a client: tools it can call, resources it can read, and prompts it can reuse. For the production work in this post the surface that matters most is tools. Each tool carries a name, a schema for its arguments, and a description. The model is presented with those signals and uses them to decide whether a tool fits the question, then calls it.

AI application  →  MCP client  →  MCP server  →  business system

MCP standardises the boundary between the AI application and the server. It does not supply the business semantics behind the server, and that is the part the rest of this post is about.

The description is the part that gets treated as an afterthought and is actually one of the most important parts of the interface.

The description is not documentation for a human who got stuck. It is part of the interface the model reasons over.

Take a single field, energielabel, that comes back as null. That null can mean four different things: the building has no label, one was never registered, a label does not apply to this building type, or the data has simply not loaded yet. Expose the field with a one-line description and the agent reports "no energy label", confidently, when the truth might be any of the other three. Write those four cases into the description, with how to tell them apart, and the agent stops guessing and says which one it is actually looking at. Same data, same tool, same model. The only thing that changed was how much meaning travelled with the field, and it was the difference between a right answer and a fluent wrong one.

Why most of them do not work

Many MCP servers begin as wrappers, and there is nothing wrong with that as a starting point. A wrapper is a perfectly good scaffold; the mistake is treating the scaffold as the finished interface. Someone points a generator at an existing API, every endpoint becomes a tool, and in an afternoon the agent can reach the whole system. The trouble is that reach is all it gets. A wrapper hands the agent every endpoint and no understanding, so it can call everything and answer almost nothing correctly, which is exactly the failure in the opening. It is the emptiness I keep coming back to: access without meaning.

It is not rare. Across 856 tool descriptions on 103 public servers, 97% carried at least one critical smell: a name that says nothing, an enum with no meaning attached, a field whose null could mean four different things. And the failure is quiet. A thin description does not raise an error. It produces a well-written answer that happens to be false, which is worse, because no one goes looking for the bug behind a fluent reply. If you want the shape of the whole spectrum, from hollow wrapper to server that writes back, I laid it out as six levels.

What a good one looks like

The move is not clever. Bind the domain meaning to the capability, close to the data and operation it describes, rather than leaving it in a wiki nobody reads or in the head of the colleague who is on holiday. Tool descriptions and schemas are the first place to start, but the principle is broader: the meaning should travel with the capability.

The question is where that knowledge comes from without it becoming a second full-time job, and the workflow that ended up working for us was to let the model do the first pass. Point it at the real data, let it explore and flag the patterns it is unsure about, and hand a domain expert the shortlist. They confirm or kill the uncertain ones in an afternoon. In our own server-building, roughly 90% of the candidate semantics the model surfaced survived domain-expert review. The roughly 10% it got wrong is precisely the part that would otherwise have shipped as confident and wrong, so the expert's afternoon is spent exactly where it pays. Everything countable, you count yourself; the expert's time goes only on what the data cannot answer.

That is the cost, and it is worth stating plainly because people assume it is larger. For us the initial review has been closer to an afternoon per server than a design cycle.

What it looks like in production

The estate is twelve servers and 97 tools. On a given day around twenty people use these capabilities; over a hundred have used them in recent months. This is a 350-person HVAC company, not a tech giant, with a small IT team and no prior AI in the building.

I want to be honest about the shape behind that number, because a single figure flatters. Some people use it daily, some rarely, some have only just started. The total hides all of that, and the honesty is the point of quoting both numbers rather than one. What it took was not a new AI platform or a big budget. It was making the capabilities understandable enough to trust, and a good deal of quieter work around them.

One word on security, because it is the deep question with real search volume and it deserves a real answer rather than a shrug. Access is bound to the identity provider the company already runs, and every tool enforces the same roles every other system already enforces. The agent cannot reach anything the person behind it could not reach on their own. That is a post of its own, not a paragraph, but the paragraph is true.

Where to go next

If there is one thing to take from this, it is the move, not the protocol: make the meaning travel with the capability. The protocol can standardise the connection. It cannot hand you the meaning, and that meaning has to come from the organisation itself.

Once meaning travels with the capabilities, the next question is how many to expose and when an agent is even the right shape, which is where I would send you next: scale capabilities before you scale agents.

This post is one piece of a longer argument. Production MCP: A Practitioner's Guide puts all of them in order, from understanding your data through to identity-bound deployment.

Go deeper: read the full practitioner report, The Missing Layer, or explore the mcp-metadata-demo server, an open-source extract of these patterns, since the production servers run on private business data.

Don't Generate the UI. Let AI Compose It.

David Golverdingen — Sat, 12 Sep 2026 15:49:10 +0000

Ask which of the buildings we maintain around Utrecht have an expired energy label, and the model answers with a map. Ask which installations at one of the sites we maintain are getting expensive, and it answers with a table. Ask how energy moves through a building, and a Sankey diagram appears. Say you want to update the assumptions on three of those projects, and it opens a small form with the fields it already knows filled in.

None of those four screens was designed as that workflow. There is no bespoke company assistant here and no screen built for any of those four questions. There is a general model, in a normal chat, with a set of tools behind it, and it picked each representation and configured it around the conversation out of a handful of generic interaction primitives that run behind one MCP server. That is the whole idea I want to argue for, and it starts with a distinction that is easy to skip past.

Two ways to give an agent a real interface

Chat is a fine interface for ambiguous conversation. It is a poor one for structured input, for dense comparison, for anything spatial. Once an agent has to collect structured input or explain rich data, chat alone starts to be the wrong interface, and there are two ways past it.

The tempting one is to let the model generate the frontend. Hand it a canvas and let it write HTML, or a component, or a whole page. That gives you enormous flexibility, and it moves far too much into a probabilistic system. The model is now on the hook for component correctness, accessibility, validation, responsive behaviour, error handling, write confirmation and browser quirks. None of that is where a model earns its keep.

The other way is to let the model compose the interface from primitives it did not write. It chooses which one fits the intent and how to configure it. A deterministic application still owns rendering, interaction validation and styling, while the capability keeps permissions and the write boundary.

Generated UI writes the interface. Composed UI chooses it.

The difference is where responsibility sits. A model is good at deciding what kind of interaction would help. Deterministic software is much better at guaranteeing how that interaction behaves. Composed UI puts each on the side of the line it is good at.

A renderer gives components. A domain-rich app gives a grammar.

Composed UI only works if the primitives carry more than pixels. A generic chart renderer hands the model a bar and a line and leaves it to guess when each one is right. That is the same mistake as a thin API wrapper that leaves the model to guess what a field means: access without meaning, with the guessing moved into the UI layer instead of removed.

A domain-rich app carries the interaction knowledge too. By domain-rich I do not mean business semantics piled into the UI layer. I mean the primitive carries the knowledge required to use it well. For a chart, that is a decision matrix: which shapes of data each visualisation is good at expressing, what fields each one needs, which combinations are misleading. Ours renders fourteen chart types today, and the count is not the point. The knowledge that sits beside them is. The chart app tells the model to decide from what the data is: amounts flowing from stage to stage are a Sankey, shares of one whole in two to five parts a pie, a ranking a bar, horizontal once there are more than eight items. The model reasons over that designed choice space instead of rediscovering visualisation principles on every query.

Updated September 2026: I have since measured which part of that knowledge does the work, and it was not the part I expected. Across 240 runs, rules for all fourteen types changed the model's choice once: it stopped drawing a twelve-slice pie. Mostly it picked text, a bar or a line either way (Q23). What mattered more was that three of the fourteen types could not be reached at all. The schema demanded a field those charts do not use, so a correct choice was refused and quietly fell back to a line or a bar, and the refusals never reached the server log (Q24). So the rule is now: size the guidance to the mistakes the data invites, walk every type with data built for it, and refuse a call that would mislead instead of warning after it has drawn (Q22c). For a form, the knowledge is the field types, the validation rules, what is required, what is constrained, what can be prefilled. For a table it is the column types that turn a number into a currency or a status into a coloured badge. For a map it is the markers and layers.

I keep the responsibilities split three ways:

the capability carries business meaning, permissions and operations;
the app carries interaction meaning and presentation constraints;
the model carries intent, reasoning and the choice at runtime.

Domain knowledge does not all move into the UI. The app knows how constrained structured input should be collected and shown. The capability knows what a maintenance request means, which fields matter and who may file one. That stays on the server, where it already lives.

The old application knew the workflow before you arrived

Traditional enterprise software decides the interaction in advance. A developer chooses which page exists, which fields sit on the form, which columns the table shows, which chart represents the data, and which navigation path gets you there. The application carries the meaning, and the user has to translate their question into its structure. "Which buildings around Utrecht have an expired energy label" becomes: open the building register, find the label screen, locate the map, set the filters, read the result. The interface exists before the intent.

An agent inverts that. The intent arrives first. By the time a representation is needed the model already knows what was asked, which capabilities are relevant, what data came back and whether more input is required. So the flow stops being screen → controls → intent and becomes intent → capability → the interaction that fits. The application is no longer a fixed sequence of screens. It gets composed around the task while the conversation runs.

The constraint is the feature

The architecture that makes this safe is not model → arbitrary UI code. It is model → constrained interaction schema → trusted renderer. The model has real freedom, and that freedom sits inside a boundary drawn by engineers. For a chart the boundary is the valid visualisation types and their configuration. For a form it is the supported field types and validation. For a map it is the markers and layers that exist. The model chooses inside that space. It can still propose something the schema does not allow, and the renderer is what refuses to execute it.

That constraint is not a limitation to apologise for. It is the thing that lets deterministic software and probabilistic reasoning each do what they are good at, in the same interaction, without either one being trusted with the other's job.

Write flows are where this earns the most

Reads are the easy case. Writes are where composed UI stops being a nicety.

Here is one we run. An energy consultant is reviewing a building's consumption, and the model has drafted a handful of weekly observation notes to sit on the graph, each pinned to a point on the time axis. Instead of writing them, it opens a review form. The consultant edits the text of each note, ticks the ones worth keeping, and approves. The time anchors the model chose are shown read-only, so a note pinned to the wrong week gets caught by the person who would know.

Then the mechanics that matter. The model cannot write the notes. Approval in the form is what calls the commit, through a tool the model has no access to, and the form mints a single-use intent that is spent on that one approval. If a week looks unclear the consultant sends it back to chat instead of approving, nothing is written, and the model goes and investigates. The write is create-only and restricted to that group of consultants, and the approval is the only thing that ever authorises it.

The model decides what information is needed. The app controls how it is collected. The capability controls what may actually be written.

That is the shape under every composed write, and it is a convention the servers share rather than a bespoke flow. Another write tool, the one that attaches a file to a record, is app-only in the same way: only its own app may call it, never the model. The generic form primitive does the milder version of the same thing. It validates client-side as a convenience for the person filling it in, then hands the values back to the model, and it cannot reach a backend at all. Either way the UI is a convenient way to gather and confirm structured input. It is never the guarantee about what reaches the database, and nothing rendered client-side ever should be.

One question, several representations

The version of this that I find most convincing is not one app per conversation. It is a single task moving through several.

Someone asks which projects have margins below five percent. The model queries live ERP data and answers with a table. Then: show me where those are. It reuses the same result and selects a map. Then: update the forecast for these three. It selects a form, prefills the project data it already pulled, and asks only for what it is missing. Table, then map, then form, then a bounded write, with no fixed page flow anywhere in it. The application emerged around the conversation instead of the conversation being routed through the application.

This is not "no frontend"

The conclusion is not that frontend engineering disappears. It becomes more infrastructural. Instead of building every workflow as its own screen, you build a small number of primitives to a high bar: robust schemas, real validators, design-system integration, accessibility, responsive behaviour, safe action patterns, rendering guarantees. The amount of bespoke screen logic goes down while the quality bar on the primitives goes up.

The frontend moves from designing every journey to designing the grammar the journeys are composed from.

That is closer to building an interaction runtime than building pages, and it is a stronger claim than "AI can generate forms."

Where I would not push this

I want to keep this honest, because the failure mode of an idea like this is to oversell it. Composed UI is early here. It is a small set of apps behind one server, not a finished platform, and I am describing a pattern that is emerging rather than a system I have run for years.

It does not mean every enterprise screen should become dynamic. Plenty of workflows are known in advance and deserve a designed page. It does not mean generated UI is always wrong, or that chat should disappear. It does not solve permissions or validation for you; the apps carry presentation constraints, and the real guarantees still have to live in the capability. And it does not make the model a validator. It makes the model a chooser.

The defensible version is narrower and more interesting than "the AI builds the app." For interactions whose shape can be described declaratively, a small set of trusted primitives can give a model substantial runtime flexibility without handing it responsibility for implementation.

The visual half of the same argument

This sits directly on top of the capabilities argument. Scale capabilities before you scale agents answered what the model should be able to reach, and the case that most MCP servers are semantically empty answered why access without meaning is not enough. Composed UI answers the next question. Once the model can reach a capability, who decides how that capability appears to the person using it?

The answer is the same shape as before. Encode the stable knowledge, bind it to the capability, let the model reason over it, and keep the deterministic guarantees in deterministic software. It gives a useful layering:

SYSTEM OF RECORD
      ↓
CAPABILITY        data + action + meaning
      ↓
MODEL             intent + reasoning + selection
      ↓
PRIMITIVE         form | table | chart | map
      ↓
HUMAN

The model does not become the application. It becomes the composer between intent, capabilities and trusted primitives. It can decide a Sankey diagram is the right representation without implementing a Sankey renderer. It can decide which fields a maintenance request needs without being the final word on what may be written. It can decide that location is part of the answer without building a mapping library.

We used to design the page first and ask the user to navigate toward their intent. An agent can reverse that. Understand the intent, reach the right capability, then choose the interaction that fits the task. The model does not need to generate the application to do that. It needs a grammar of trusted primitives it can compose. Give the model freedom over the decision, and keep the guarantees in the software.

This post is one piece of a longer argument. Production MCP: A Practitioner's Guide puts all of them in order, from understanding your data through to identity-bound deployment.

Scale Capabilities Before You Scale Agents

David Golverdingen — Sat, 12 Sep 2026 15:48:34 +0000

Enterprise AI reference architectures have converged on two pictures. One is agents everywhere: a planning agent, a finance agent, an ERP agent, a supervisor to coordinate them, shared memory, handoffs, routing, state. The other is a company brain, one chat that knows everything. Every box in the first is another boundary where context can diverge, state can go stale and meaning can get lost. The second has no boundaries at all, which is its own problem: one application ends up answerable for the whole company.

The estate at Warmtebouw went the other way. Twelve MCP servers and 97 tools by the end of August, reaching eleven external APIs and our own internal ones, and no network of agents anywhere in it. Around twenty colleagues use it on a given day, and more than a hundred have used it at least once over the past few months. Most of them are not developers.

The bias is one sentence: before you add autonomy, give the model reliable and well-explained access to the business. By capability I mean a permission-bounded tool exposing one live operation or query, with enough semantics travelling alongside it that a model can use it correctly. Not an endpoint, and not a document about one.

The three architectures differ in one thing

Almost every "AI for the company" proposal is one of three shapes. The useful way to compare them is to ask where the meaning of the company ends up living.

Approach	Where meaning lives	Source of truth	Architectural cost
Agents everywhere	Spread across the agents, and it has to survive being passed between them	The systems, reached through a chain	Task ownership, per-agent identity, state, cross-agent evaluation, failure propagation
The company chatbot	Centralised in the chatbot, which has to know about every source	Whatever each integration was wired to	One application holding every integration, permission model and interpretation, and having to be right about all of them at once
Capabilities	In the interface to each system, next to the data it describes	The system of record, unchanged	Writing the meaning down once per capability, and fitting every description into one context window

Agents distribute interpretation across boundaries. A chatbot centralises it in one application that has to be right about every source at once, which is a layer you keep alive on top of systems that already work. Capabilities keep interpretation next to the system that owns the data. For operational questions, that was the trade-off we preferred.

Why capabilities won here

The questions are operational. They change during the day, and a copy is only ever as current as the last sync, which is a job you own rather than an answer you get.

There is one place to fix a misreading. A raw API is not automatically a useful capability. Hand the model { "energielabel": null } and it still has to work out whether that means no label, not registered, not applicable, or not loaded yet. Four valid answers share one JSON representation, so this is a contract problem and not a model-quality problem. No model reliably recovers a distinction the interface does not encode; a strong one guesses right more often, which is the trap. That interpretation belongs with the capability, in one place read by every client, rather than with whichever agent happens to consume it.

Users do not ask questions that respect the org chart. A project manager working out why a job is losing money wants the ERP margin, the installed BIM elements, the service history and the meter readings in one conversation, in about ninety seconds. Route that through four departmental agents and a supervisor and you have built a switchboard for a question nobody would phrase that way. Permissions come along with the capability: access is allowlisted per role against the identity provider that already governs those systems, rather than reinvented per agent.

If a capability is semantically thin, an agent on top of it does not fix that. It guesses, a supervisor interprets the guess, and the user gets a well-written answer with the uncertainty two hops from anyone who could have caught it.

If the interface is empty, an agent on top of it is a guess with a job title.

Capabilities, procedures, agents

Three levels, and most architecture diagrams collapse them into one.

A capability gives the model access, meaning and bounded authority.
A procedure prescribes how capabilities are combined. A skill is one.
An agent decides at runtime what to do next.

The dividing line is control flow, not intelligence. A procedure has a path you can read before it runs; an agent chooses part of that path while running, and that choice is where the machinery starts. Stopping conditions, state, evaluation and observability all get harder once the path is not known in advance. Control flow is also what keeps this consistent with my complaint about skills: the skill is the procedure, the capability holds the domain knowledge and the data. A skill that explains what a field means has taken over the capability's job.

"Agent" increasingly describes how a system looks from outside rather than how it is built. A workflow calling five tools can look agentic while containing no autonomous component at all. What matters is where meaning lives, who may act, and which decisions genuinely require autonomy.

Do not ask how to operate an agent until you have established that you need one.

So is there a place for an agent?

Yes, but less often than those reference architectures suggest. A service message comes in, and Gemini 3.7 Flash writes a usable subject line for it: clear input, bounded output, one responsibility, easy to evaluate. It chooses no next action and carries no state. Much of what gets drawn as an agent turns out to be a function with a model in it, that example included.

A "finance agent" is the opposite shape: no clear input, no bounded output, nowhere natural to measure it, and one reason to exist, which is that finance is a department. Use an agent when you need autonomy, a capability when you need access.

What does earn autonomy is work whose next step genuinely cannot be known in advance, and the levels stack cheaply once the bottom one is good. A scheduled task runs a procedure, the procedure calls the capabilities in the order it prescribes, and the model handles whatever the procedure could not anticipate. Ours is a scheduled task in Claude running a skill. That is autonomy doing real work, with no agent per domain. The capability was the investment; the schedule and the skill are configuration on top of it.

Where this breaks down

Tool selection scales badly, though less than it did. Ninety-seven tools in one context is a selection problem before it is an achievement, and descriptions rich enough to carry domain meaning consume the most room. Clients have started fixing that, with tools connected deferred and their schemas fetched on demand, and the protocol is moving the same way. That moves the ceiling rather than removing it. Selection now runs against the description, so a thin description stops being misunderstood and starts being skipped over, and getting the right meaning to the model at the right moment becomes the work. When routing does arrive, I want it choosing which capabilities to load, not choosing which departmental agent to ask.

And this is one company. Around 350 people, one primary user-facing model, and about an hour a week keeping twelve servers' descriptions true. Whether the same defaults hold across a multinational with hundreds of systems and complex tenancy, I have no idea.

The measure is not how many agents are running

Agent count is not a maturity metric. The better question is whether the model can reach the right part of the company and understand what it finds there.

Build that layer first. Add procedures when the sequence is known, routing when scale requires it, and autonomy only when it earns its place.

This post is one piece of a longer argument. Production MCP: A Practitioner's Guide puts all of them in order, from understanding your data through to identity-bound deployment.

The Cheapest Time to Be Wrong

David Golverdingen — Thu, 13 Aug 2026 12:59:11 +0000

If an agent writes most of the code, what stops it from confidently shipping the wrong thing?

Our answer is three review layers, firing at different times for different reasons. The one that carries the weight is the one that runs while there is no code to review. That is the two earlier posts' loose end: why we replaced Jira with markdown tickets, and the skill and the loop that let an agent work those tickets on its own.

Before review: authoring against the real code

A review can only be as good as the thing it measures against, so the acceptance criteria have to be worth measuring against.

That starts with how the ticket was authored, from a checkout, against the real code. The skill then enforces a shape on the result. Objective in one or two sentences. Context under 120 words. Around five acceptance criteria, one requirement each, written for behaviour rather than deliverables, so "tests pass" and "version bumped" are excluded by definition.

Behavioural criteria use EARS form: When <trigger>, the system shall <observable outcome>. That is not ceremony. The trigger is the test setup, and writing it forces out which criteria only a running application can confirm. Those become the manual test later, and they are the ones nobody would otherwise think to check.

The section budgets exist for the same reason. A ticket should be quick to understand during refinement, not a wall of text and detail that belongs in a plan, so it captures what and why and never how. If Context is overflowing, analysis has leaked into a document that is supposed to be a specification, and the fix is to defer it to the plan.

The plan is the highest-leverage artifact

Then the ticket gets planned, and this is the step worth spending real effort on.

Planning runs read-only, as the previous post describes. The agent explores: the scope, the acceptance criteria, the code it will touch, the history of those files, older tickets on the same component. Then it drafts a plan into a scratch file, one block per task:

### Task 1 — <name>
- Goal: what this task delivers
- Approach: concise steps
- Decisions: choices made + rejected alternatives + why this sequencing
- Touches: files / components
- Verification: build/tests/manual check that proves it's done

Once approved, the plan is what the ticket's tasks get created from, and execution then works through those tasks one by one, each landing as one self-contained commit. Anything hinging on an unproven integration gets an early-validation task sequenced first: a throwaway harness that proves the wiring before real work is built on top of it.

A Mermaid diagram goes in when a flow or state machine is clearer drawn than written. The pre-commit hook runs the real Mermaid parser over every block, so a diagram that would not render cannot be committed.

The Decisions line is the one that matters. It carries the rejected alternatives and the reason for the sequencing, which is exactly what disappears when a plan lives only in a chat window.

Here is why this artifact outranks the others: a wrong decision is cheapest to fix before any code exists. Bad sequencing caught in a plan costs a paragraph. The same mistake caught in review costs hours of rework and the tokens burned rebuilding on the wrong foundation, and caught after merge it costs a follow-up ticket. Not every defect is a design defect, and no plan review will catch a null check. But design and sequencing errors are the expensive class, and this is the only layer that gets at them while they are still cheap.

Layer one: a second model reads the plan

So the plan gets reviewed before anyone implements it.

Claude drafts the plan; Codex attacks it. Different model family, running read-only and in the background. The instruction is deliberately narrow: list findings for Claude. Gaps, missed edge cases, risky sequencing, wrong assumptions. Not a rewrite.

That constraint is the whole trick. A second model asked to improve a plan will produce its own plan, and you are left comparing two documents with no way to judge. A second model asked to attack a plan produces a list you can act on item by item. The agent folds in what is worth acting on and notes what it consciously rejected, so the disagreements are visible rather than silently resolved.

Model diversity is the point, not a vote. Two instances of the same model share the same blind spots, and averaging them just gives you a more confident version of the same mistake.

The human gate

Then it stops and asks.

This is the approval that always exists, on every ticket, no matter how autonomous the rest of the run is. Nothing has been written to the ticket yet, so the plan is still free to change. The reviewer is looking at a page of decisions rather than a thousand lines of diff, which is the cheapest possible moment for a human to disagree.

It also does not have to be the same reviewer every time. A page of decisions is cheap enough to hand to a second developer, not only the one who scoped the ticket, which makes this pair-planning where most teams only ever get around to pair-coding: a second person looking at the shape of the work before it exists, not the diff after.

After approval the plan is written into the ticket and the session throws its own context away.

Layer two: multi-lens self-review before the PR

Implementation happens task by task. Then, before the pull request is opened or readied, a full self-review runs, and the first thing it does is throw away the context that produced the code.

That clear is unconditional. A reviewer holding the authoring transcript inherits the assumptions the author used to justify the work, and inherited assumptions are exactly what a review is supposed to catch. The branch diff and the ticket carry everything a reviewer needs.

The review then fans out into read-only lenses running in parallel, each with a different brief. A code-heavy diff gets all four:

Correctness and edge cases: logic errors, null and undefined, async and promise handling, swallowed failures, boundary inputs.
Security and boundaries: authentication and authorisation, validation at trust boundaries, secrets, injection, and for Firebase the ownership and App Check specifics.
Conventions and architecture: the repo's own CLAUDE.md and language rubric, over-engineering, and scope drift measured against the ticket.
Test adequacy: whether changed branches and error paths are actually exercised, and whether assertions would fail if the code broke.

A docs-only or config-only diff does not need four code lenses, so the set is sized to what actually changed and the skipped lenses are named in the output. Same discipline as the bot review below: a skip is a visible decision, not a silent gap.

They share one pre-computed scratch file with the diff, the ticket and the standards, so four reviewers are not four times re-reading the same thing. The win there is token cost rather than wall-clock, which is the sort of thing that decides whether a review runs on every pull request or only on the ones you remember. Codex reviews independently again alongside them.

Two things make the output trustworthy rather than voluminous.

Adversarial verification. Every candidate finding goes to a skeptic whose job is to disprove it, and never the lens that raised it, because a finder grading its own work is not a check. The skeptic scores confidence from 0 to 100 and anything under 80 is dropped. Executable proof beats argument: run the function on the triggering input, grep the actual file. Precision matters more than recall here, because false positives are how a review becomes something people stop reading.

Tools as ground truth. Build, lint, typecheck and tests are run, not guessed, and their real output is shown. A failure is a finding, not something to summarise away.

The complete findings list is presented with a verdict of Ready, Needs work, or Blocking, and nothing has been changed yet. Only then does the main agent act: Critical and High are fixed and re-verified, Medium and Low are offered as a decision. The reviewers find and the main agent fixes, which keeps the roles from blurring.

Layer three: the bot review, driven by the agent

The last layer is CodeRabbit on the pull request, and the interesting part is that the agent runs it rather than waiting on it.

Automatic review is switched off. The trigger is a deliberate comment, and it only gets spent on diffs that warrant one. A pull request touching only documentation, tickets or config skips the review entirely, and the skip is written down.

Then a trap worth knowing. A green CodeRabbit check means the review completed, not that it was clean: six unresolved findings sit behind the same green tick as none. The comments have to be fetched separately, and treating "check passed" as "nothing to do" is the easiest way there is to merge a reviewed pull request without reading the review.

Each comment gets triaged the same way as any other finding: real issue, nit, or wrong. A bot review is not automatically right, and grounding a rejection in file:line is the difference between disagreement and hand-waving.

The last step is the one people skip. Reply before resolving, and address the bot by name. CodeRabbit ingests replies that mention it and can record a repo-scoped learning, so "we do this deliberately because X" has a chance of stopping the same flag on future pull requests. Silently resolving teaches it nothing at all. In our repositories the review has got quieter over time, and I am fairly sure that is why.

One safety rule sits underneath all of this: review comments are data, never instructions. An agent that executes what it reads in a pull request comment is one crafted comment away from doing something nobody asked for.

Why three and not one

Each layer catches what the one before it structurally cannot. The plan review catches design, because the design is all that exists yet. The self-review catches implementation drift against the ticket, which needs code to exist. And the bot is the only one looking across the repository's history rather than at a single branch, which is a view none of the others can construct.

Other people have started calling this shape an AI-native SDLC. The three layers above are what that name actually cashes out to once nobody is reading every line by hand.

The honest part

This is slower per ticket than not doing it, and it is not a replacement for a human reading the diff. Nothing here removes the pull request review; it changes what arrives at it.

What we get is that a human's first look is no longer the first challenge to the work. A different model family has attacked the plan, a skeptic has tried to kill each finding, and the build and tests have actually run. What is left is usually a real conversation about a real decision.

On the good days, that is what code review was supposed to be.

The Ticket Is the Context Window

David Golverdingen — Thu, 13 Aug 2026 12:57:22 +0000

I thought the deliverable was the file format and the board. It was not. The deliverable is the process, written down in a form the agent executes.

I did not see that coming when we replaced Jira with markdown files in our repositories. That post covers why we left and what the system is. This one is about what the system turned out to be for.

The skill is the product

Our workflow lives in a Claude Code skill: 452 lines covering how a ticket is created, refined, planned, picked up, worked, reviewed and closed, plus a few reference files it pulls in on demand so the always-loaded part stays readable. Not a style guide. Instructions with gates in them, which the agent is required to load before touching any ticket.

The create flow does not start by scaffolding a file. It starts by making the agent ask two to four targeted questions when a request is thin, then present the drafted Objective, Context and Acceptance Criteria for sign-off before anything is written. Planning runs in read-only mode, so no ticket write can happen before the plan is approved. Work happens one task at a time, each claimed on the board before a line of code is written.

The routing rule

The most useful rule in it fits in a sentence. There are two ways to write a ticket, and the diff decides which one.

Ticket-only changes go through the MCP server, which commits straight to the default branch: creating a ticket, refining it, flipping status before the code work or after the pull request lands. No checkout, no branch, no pull request, no review bot. The analysis still happens locally where the code is; only the write is remote.

Code work happens on a ticket branch with the CLI and git, where the plan, status changes, task completions and work log entries ride along with the code commits and merge through the same pull request.

Before the rule, every status change during a coding session was a small decision with no good answer: open a throwaway pull request for a one-line frontmatter edit, or commit ticket noise onto the feature branch. Now the diff answers it.

One implementation, four consumers

Underneath both paths sits one npm package holding the schema, the parser, the serializer, and every edit operation as a pure function.

Four things import it: the CLI that agents and humans run in a checkout, the Angular viewer behind every board edit, the Cloud Functions commit gateway, and the MCP server for the remote path. Nobody reimplements ticket semantics. The MCP server has no authoring logic of its own; it resolves the project, allocates an ID, runs the shared transform, and lets the gateway validate before committing.

That is what makes a guardrail real. When we added a rule that a ticket cannot be closed while its acceptance criteria are unticked, it went into the package once and now fires identically whether you type a CLI command, call the MCP tool from your phone, or drag a card across the board. There is no back door, because there is only one door.

The override is the part I like most. You can force past that gate, but it costs a written reason, and the same operation that flips the status appends that reason to the work log. A bypass is always visible and attributable. A gate people quietly route around reads as enforcement while providing none.

The loop

The thing that changed daily work most is one line:

/goal complete tasks according to the wbtickets skill until the PR is mergeable

That is the whole prompt. What follows runs on its own, and it can run on its own because the ticket carries enough state to make it possible:

Pull, re-read the ticket, take the first task that is not done.
Claim it: mark it in-progress, commit, push. Before any code, so the board and any parallel session see the claim.
Implement exactly that task. Build it, test it.
Present the pending diff and wait for approval.
Complete the task, write the work log entry, commit code and bookkeeping together, push.
Next task, back to step 2.

Step 4 is the default, and the goal is what waives it. A goal is a hook that blocks the session from ending until its condition holds, so typing that line is the approval: instead of stopping at each task, the agent finishes one, pushes, and walks straight into the next. The gate is not removed from the skill and it is not disabled for the repository. It is authorised once, for this run, by the person who started it. Point it at a ticket with seven tasks and it works the ticket, not the task.

That makes it a judgement call rather than a setting I leave on. Waiving the per-task check is right when the tasks are small, the plan is well understood and a wrong turn costs one revert. It is wrong on anything where I would want to see the shape of task three before task four is built on top of it. The goal trades review granularity for throughput, and low-complexity, low-risk tickets are where that trade is clearly worth making.

Two things make the unattended version acceptable rather than reckless.

The claim happens before the code. It is bookkeeping with nothing attached and it must reach the board first, or a second session picks up the same task. The recurring failure was sliding from one task's finished commit into the next task's edits without claiming, which looks harmless until two agents are working in parallel.

One task is one commit. The loop never batches. Every step lands as a separate, conventionally named commit carrying its code, its task completion and its work log entry together. An unattended run is reviewable afterwards, commit by commit, and the pull request reads as a sequence of decisions instead of one wall of diff.

And the gates the goal cannot touch sit at the edges: an approved plan going in, and three layers of review coming out. Autonomy inside the ticket, scrutiny at the boundaries. Skipping the per-task check is defensible precisely because those two are not skippable.

Planning ends by throwing the context away

The shape this replaces is one I used for years. Read the ticket, make a plan from it, let the plan drive the code. That plan lived in the chat or in a scratch file, outside both the ticket and the repository, and nothing merged it back. When the work deviated, the plan stayed as written and the reasoning for the deviation went wherever the conversation went. Now the plan is a section of the ticket, so it travels with the code through the same pull request, and a deviation lands next to the plan it deviated from.

Planning is the one phase that deliberately stops, and it stops twice: once for approval, then again at the very end. The session writes the plan into the ticket, splits the work into tasks, adds a Mermaid diagram when a flow or state machine is clearer drawn than described, commits, and then clears its own context.

The rule that makes it work: if the reasoning exists only in the chat, the plan was not self-contained, and that is a bug to fix before clearing. The decisions, the rejected alternatives, the sequencing rationale and the per-task verification all go into the ticket.

The ticket is the context window. A fresh session picks up task three of seven without any of the conversation that produced the plan. It still syncs the branch and re-reads the ticket, but it never has to reconstruct why the work is shaped the way it is, because that is in a file it can read. The exploration transcript is not context, it is exhaust.

Getting that plan right is the highest-leverage step in the whole workflow, which is why it gets a review of its own before any code exists.

This is also why old tickets stay readable. They are time-locked decision records. Before planning work on a subsystem, the flow has the agent mine the history of the files it will touch and search older tickets on the same component, so a decision made in March is available in August without anyone remembering it exists.

Distribution is the quiet multiplier

A process written down helps one repository. A process that installs itself helps all of them.

The skill ships inside the same package as the CLI, with a sync command wired to a session-start hook, so every repository picks up the current version at the start of every session. Change the instructions and the change reaches every agent session in the company by the next session start. No migration, no announcement, no repository left on last month's process. The same package serves the guidance the MCP server hands to colleagues authoring tickets from claude.ai, so the two cannot drift apart.

It is not one skill riding along either. Ten travel that channel now, from the review process to the per-stack rubrics, reaching a Java repository and an Angular one alike. That was not the plan. It is what happens when you build a way to ship one process and discover the pipe does not care how much you put in it.

Watching four agents work

One ticket, one checkout, one session. That is forced rather than chosen: the bookkeeping auto-commits, so two sessions cannot share a working copy without fighting over it. A parallel command does the rest, provisioning a git worktree per ticket with its own port and dependencies, flagging any files two tickets would both touch, and handing back one kickoff prompt per session.

That constraint produced the best moment I have had with this system.

Three ingredients, none designed for it. Ticket bookkeeping auto-commits and pushes the instant it happens, the one deliberate exception to our never-auto-commit rule, because the board has to see it. The board is branch-aware, reading each ticket from its own feature branch rather than the stale copy on the default branch, so it shows work in flight. And the in-progress lane is double width with the task checklist inline.

Run four sessions at once and the board becomes a live view: four tickets in progress, four checklists ticking themselves off within seconds of each push. I had it open on a second screen and watched the work move.

The caveat is honest: the board is exactly as current as the last push, so unpushed work does not exist to it. In practice that is fine, because the bookkeeping pushes itself, and the bookkeeping is the part worth watching.

I did not build this to be watchable. But it is the first time a project management tool has shown me something I did not already know from being the person doing the work.

What this actually changed

Our tickets are now the thing an agent reads before it writes code, instead of the thing someone updates after the code is written.

The board did not get smarter. The tickets did.

That leaves the uncomfortable question. If an agent writes most of the code, and on a good day you tell it not to pause between tasks, what stops it from confidently shipping the wrong thing? Three layers of review, and the one that does the most work runs before a single line of code exists.

We Replaced Jira With Markdown Files

David Golverdingen — Thu, 13 Aug 2026 12:57:18 +0000

Early this year I was wiring Claude into Jira through an MCP server. It worked, and every session it felt slightly wrong: slow round trips, a schema I did not control, structure sitting somewhere the agent could not see while it was reading the code.

That is a context problem. Context engineering is not about pushing more context into the model; it is about putting the context where the agent is already looking. Ours could read every line of the codebase directly, and the ticket telling them what to change only through a tool call.

The fix was almost embarrassingly simple. Put the ticket in the repo, as markdown. I pitched it to a colleague, and off we went.

Seven months later, 15 projects across 10 repositories, 165 live tickets, 12 people on the board including non-developers, and no Jira licence.

This post is why we left and what we built. Two follow-ups cover the rest: the skill and the loop that let agents work these tickets, and the three review layers that keep the output honest.

What was actually wrong with Jira

The cost was easy to name: roughly €2,000 a year for something we used maybe 5% of. It was not the reason we left.

Every user had to be paid for, so the board was implicitly rationed. Performance degraded as projects grew. The features we wanted sat behind paid plugins. Automations were clumsy enough that we mostly did not write them. And the board was close to what we wanted without ever being it, because that last gap lived in someone else's product roadmap. None of that is fatal alone. Together it means the tool shapes the team instead of the other way around.

The constraint that ruled out the obvious answers

We are one team maintaining ten separate repositories that ship independently of one another, across TypeScript, C#, Java and PowerShell. A monorepo was never realistic.

That kills the usual alternatives. GitHub Issues comes closest and misses twice: issues are scoped to one repository, so cross-repo visibility becomes somebody's weekly spreadsheet, and despite feeling like part of the repo they are not in it. They live in a database behind an API. Not files, not on the branch, not in the diff, and not something an agent editing the code can read without a round trip. Every hosted alternative moves the work further away still.

So we inverted it: distribute the tickets, centralise the view.

One file per ticket

Every repository carries a tickets/ folder. A ticket is one markdown file:

---
id: APP-42
type: story
title: '[Profile] Add user avatar upload'
status: in-progress
priority: high
size: m
assignee: developer@example.com
reported_by: colleague@example.com
tasks:
  - name: Implementation plan
    status: done
  - name: Upload component
    status: in-progress
---
## Objective
## Context
## Acceptance Criteria
## Scope
## Design
## Technical Notes
## Implementation Plan
## Diagram
## Work Log

The frontmatter is the machine-readable half, and none of it is free-form. Every field is schema-validated: the status vocabulary, priorities, t-shirt sizes, the ID matching its filename, timestamps in one format. A pre-commit hook and a CI step both run that validation, so a malformed ticket never reaches the default branch.

The body is the human half, with fixed headings. That is what makes a section addressable: a tool can replace Acceptance Criteria by name without touching anything around it, which you cannot do reliably to a free-form description field. ## Diagram holds Mermaid, and most substantial tickets have one, because a state machine or a data flow is faster to check than the paragraph describing it. The same pre-commit hook parses every Mermaid block with the real Mermaid parser, so a diagram that would not render cannot be committed.

One rule holds it together: nobody edits these files by hand. Writes go through a CLI of typed operations (set a status, claim a task, tick a criterion, append a work log entry, replace a section) that stamps timestamps, refuses invalid transitions, and keeps the file valid by construction. Hand-editing markdown is how fields drift and a board stops being trustworthy. The format is open to read and closed to casual writing.

Each repository also holds a small derived .tickets.config.json with its prefix, default branch and allowed values, so validation is local and calls nothing external. An admin edits project settings in the portal; the file is written out to every affected repository.

The board is a projection

A viewer application (Angular, Firebase, a GitHub App for commits) scans every configured repository and aggregates the tickets into one Kanban board. Edits commit back to the correct branch: the ticket's feature branch if one exists, the default branch otherwise. Because every change is a commit, git history is the audit trail.

The one piece of ticket content not in git is board ordering, which lives in Firestore next to the things that were never content: profiles, saved filters, role lists, the project registry. Dragging a card to reprioritise would otherwise rewrite files across ten repositories and produce merge conflicts carrying no information. Content is git-canonical. Ordering is a view preference.

Two decisions I would keep in any rebuild. The lanes are asymmetric: in-progress is twice the width of the others and shows the task checklist and the live branch inline, which matters far more than I expected once several tickets run at once. Workflow steps are subtasks, not columns: code review, manual test and E2E are entries in the ticket's task list. For a team of two to five, a column per step produces a board of nearly-empty columns, while task-level detail puts the standup answer on the card.

Nobody pays to be on the board

We already had Microsoft Entra SSO, so authentication cost nothing and no seat has a price on it. That reads like a footnote, and it is the change I value most: when visibility stops being metered, you stop deciding who deserves it.

It also took the system somewhere I did not plan. Five of the fifteen projects have no repository at all. They are folders in a shared host repo covering application management, business automation, engineering optimisation, AI enablement and general company work. What is in them now: onboarding a new colleague, enabling SSO, formalising a technical quick-scan process, getting the team through a Claude course. None of it is code, all of it sits on the same board, next to the software work it competes with for time.

Two ways in, one authoring guide

WBTickets has its own MCP server alongside the eleven others we run: 18 tools for reads, writes, milestones and attachments, hitting the same repositories through the same commit gateway as the board.

That is how the projects without a codebase work. A colleague in claude.ai, with no checkout and no git, describes a problem in their own words and ends up with a schema-valid ticket committed to a repository. create_ticket is deliberately two-step: called with no arguments it creates nothing and returns the authoring guide, which tells the agent what to ask and to get sign-off before writing. That last part is instruction rather than enforcement. The server will happily create a ticket on a first call that arrives with arguments; what the two-step buys is that the guide is in front of the agent before it has anything to commit.

For code repositories we prefer the other route, running on that same guide. A ticket for a real codebase is written from a checkout by an agent that reads the code first: what exists, what the change touches, which older ticket decided the design that is there now. That is the difference between a Scope with real boundaries and one that merely sounds plausible. The write still lands on the default branch through the same path; only the analysis is local.

Attachments get their own trick. Screenshots are how non-developers explain a bug, but pushing image bytes through a model's context is pure waste. So view_attachments returns metadata only and opens a small app inside the chat; the app fetches and uploads the actual bytes through separate tools that never put them in the model's context at all. You see the screenshot, drag a new one in, and the agent's context stays clean.

The loop closes at the far end: reported_by records who asked, and they are notified when the ticket reaches done. They never have to open the board.

The board matches the work that was delivered

I have never seen a ticket board outside the codebase that still matched what was actually built. Not a failure of any particular team: it is distance. Scope changes, deviations and the reasoning behind them get settled in a pull request or a call, and updating the ticket is a separate action somebody has to remember to take, later, from memory. Some of it lands days late as a summary. Most of it never lands at all, which is why the interesting question about any board is not what it says but when it last agreed with reality.

Here the agent doing the work is what writes it down, in the same commit as the code. A deviation gets a work log entry when it happens, with the reason, while the reason is still in context rather than reconstructed afterwards. So by the time the pull request opens, the ticket describes what was built and not only what was planned, and where the two disagree that disagreement is on the record with its argument attached.

That is the part I would miss most if we went back. A board that is merely tidy tells you how disciplined the team is about bookkeeping. A board that is written by the work tells you what happened.

What came nearly free afterwards

Once the substrate was markdown in git, the adjacent things stopped being projects. Milestones as roadmap items with horizons instead of dates. Release notes generated from git tags with ticket IDs resolved to board links. Design artifacts: a self-contained HTML mockup committed beside the ticket, reviewed in the same pull request as the code and rendered in a sandboxed iframe on the board.

The next one is in build: a knowledge base to replace Confluence and its ~300 articles. What made it worth starting is that almost none of it is new. It inherits the auth, the attachments, the markdown rendering and the same git-canonical instinct, so the architecture argument was about content workflow rather than infrastructure.

Same primitive every time. That is the compounding return of a format every tool already understands.

The build-versus-buy line moved

We are a small in-house IT department. Warmtebouw installs heating, cooling and ventilation; we are the handful of people who build the software around that. This is not a heroic story, and that is the part worth noticing.

You rarely bought a tool because its feature list was unbeatable. You bought it because building and maintaining something that fit your team cost far more than the licence did. That arithmetic has changed. Writing a bespoke system, and more importantly keeping it correct and documented while you use it, is now cheap enough that a small team can do it alongside the actual work. We are one of many teams quietly discovering that the licence was buying convenience we can now produce ourselves, and better, because ours fits.

It does not generalise to everything. The tools worth replacing are the ones where your own workflow is the product and the vendor's genericity is the tax you pay. Nobody sane is rebuilding their ERP this way.

The vendors have noticed. Atlassian is now positioning itself as the layer in the middle of agentic work, and I would not want to be selling that. The middle is precisely the position an agent routes around. If the work lives in the repository and the agent is already there, a hosted system of record stops being where the work happens and becomes a place you synchronise to. That is a difficult thing to charge per seat for, and a harder one to defend once teams notice the alternative is a folder of markdown files.

The honest ledger

You own the maintenance. Jira's operating burden is zero and ours is not. This began as a side project and grew in the gaps between real work. The core worked from the moment there were tickets on the board; everything since has been sharpening it.

What makes that sustainable is who maintains it: the team that uses it every day. A rough edge gets filed down by the person it just annoyed, usually in the same session they hit it, and the fix is filed as a ticket in the system it fixes. In a week where we are not adding features, that upkeep is roughly an hour. There is no maintenance budget to defend, because the work is spread thinly across all the other work.

What we bought is a system that fits our workflow exactly rather than 60% of it, a board open to everyone in the company, and every remaining failure mode being ours to fix. The licence saving is real and it is the least interesting part.

The board was the deliverable. The consequence was that the description of the work now lives where the agent is already looking, and that changed how the work gets done far more than any board could. Here is what that looks like in practice.

Enterprise AI Without an Enterprise Budget

David Golverdingen — Tue, 26 May 2026 07:27:06 +0000

Enterprise AI gets sold as something only large companies can afford. It doesn't have to be. The reason is structural: the protocol layer underneath is absorbing the work that used to require an AI platform.

Over the first three months at one mid-sized engineering firm (not a software company), I operationalised AI across the entire business through nine production MCP servers covering ERP, BIM, calculations, building automation, energy, and operational logs. By the end of August, the estate had grown to twelve. No platform team, no framework dependencies, no custom chat UI. Project managers, field engineers, and operations colleagues query the whole company's data in natural language, every day. The running cost is roughly €19/seat/month for the staff who use it, plus the engineering time to build the MCP layer.

This piece is about the architecture that made that reachable, and why it's reachable for small and mid-sized companies that have been told enterprise AI is out of their league.

The standard path is expensive

When a mid-market or smaller company decides to bring AI in, the path they're usually pointed toward looks the same: build a branded chat UI on the API, wire it to internal auth, manage prompts in-house, maybe add a RAG pipeline against company documents, optionally an orchestration framework for "agent workflows," and increasingly an observability platform to monitor it all. That path is real, and at sufficient scale it may be the right call. I haven't run this architecture at the scale of a large multinational with hundreds of heterogeneous systems and complex tenancy requirements, so I can't tell you whether the same posture holds there. My guess is that the MCP layer itself stretches further than the framework industry assumes (more servers, deeper hierarchies of tools, more careful schemas) rather than needing a different architecture entirely. But that's a hypothesis from one scale, not a report from another.

For a company with twenty important systems and a few hundred employees, the standard path doesn't pay back. It's expensive in three coupled ways, and pulling the three apart reveals a simpler architecture underneath.

The chat client. A branded chat UI is a frontend team, a design effort, conversation history infrastructure, attachment handling, multi-modal input support, an admin panel, model routing, prompt management. The vendor (Anthropic, OpenAI, Google) ships all of this as part of the subscription and continues to ship new affordances every quarter. Building it in-house means investing engineering hours into a commodity layer where the vendor has structural advantages no internal team can match.

The model. A custom chat UI almost always pins to a specific model version for stability. Six months later the frontier moves, and the pinned model is now a generation behind. Upgrading means re-validating every prompt and every tool, so most teams don't. Meanwhile every Claude Team subscriber got Opus 4.7 the morning it shipped, with zero engineering work.

The billing. API billing is per-token, which means the cost is a function of user behaviour that hasn't happened yet. In a workforce of 50-500 people, roughly 20% of users drive 80% of consumption once adoption stabilises. Published analyses of heavy usage put the API-vs-subscription cost ratio at 15-30x; for average users the multiple is smaller (3-10x), and for light users API can come out ahead. The relevant number isn't the average. It's the variance.

These three costs aren't independent. They flow from the same root decision: build our own chat UI, or use the vendor's. Building locks all three together. The standard path commits a smaller company to a build budget, a maintenance team, an aging model, and an unpredictable bill, all at once.

The simpler path

Use the vendor's chat client. Pay per seat. Connect your existing identity provider. Then put your engineering hours where the value compounds: in MCP servers that encode your domain.

This is the architecture in production. Employees use Claude through the standard client (web, desktop, mobile). The client authenticates against the corporate identity provider, same as every other corporate system. By the end of August, employees had access to twelve MCP servers covering the full operational chain. Each MCP tool is RBAC-gated against the same IdP roles that govern every other system. A field engineer sees their own time bookings; a controller sees aggregated financials; a guest user sees nothing.

What I didn't build: a chat UI. A model gateway. A prompt management platform. A vector database. A retrieval pipeline. An agent observability stack. An "AI platform" of any kind. None of those layers exist in the stack, because the subscription client provides everything above the MCP layer, and the IdP provides everything around it.

A concrete example. The most common AI project a mid-sized company is pitched is "RAG over our documents": chunk all the SharePoint or Google Drive content, embed it, build a vector store, wire it to a retrieval layer, host and maintain the whole pipeline. Even when that pipeline is cheap to build, it's a layer you have to keep alive. Re-index when documents change, re-tune when retrieval quality drops, re-permission when access rules shift, re-host when the embedding model is deprecated. Meanwhile, the Microsoft 365 and Google Workspace integrations that ship with Claude, ChatGPT, and Gemini are themselves MCP servers, published by the vendors, maintained by the vendors, with permissions inherited from the existing IdP and freshness handled upstream. The "document search" capability that makes a custom RAG pipeline sound necessary is already an MCP server you can turn on in your admin console. The choice isn't cheap vs. expensive. It's an extra layer you maintain vs. no extra layer at all. And once you stop blaming the data and start fixing the meaning layer, the case for a custom RAG pipeline gets thinner still.

That sharpens the architectural rule. MCP isn't a category that lives only inside your perimeter; it's the protocol the entire ecosystem speaks, and vendors are already publishing servers for the commodity layer: productivity suites, code hosts, ticketing systems, design tools. Your engineering investment goes into the MCP servers that only you can write: your ERP, your BIM data, your operational logs, your calculation history. The systems unique to your business that no vendor has, or will ever have, a connector for. Everything else, you consume. That's where the investment compounds, and where it doesn't.

The cost picture inverts. Claude Team is about €19/seat/month on the annual plan; ChatGPT Enterprise and Gemini for Workspace are in similar territory. The vendor eats the billing variance. Every seat gets the latest frontier model the day it ships. No frontend to maintain, no platform team to staff, no orchestration platform to buy.

What this opens up

The interesting part of this architecture, and the part that makes it reachable for small companies, is the shape of the MCP layer.

The domain layer is model-agnostic. MCP servers are typed interfaces with tool descriptions and schemas. The same servers work with Claude today, Gemini tomorrow, GPT next quarter. None of the domain logic is locked to a model vendor. The engineering investment is portable across the entire frontier-model market.

Identity lives at the tool boundary. RBAC is enforced inside the MCP server, against your existing IdP. A model that's been prompt-injected can only call tools the authenticated user is already authorised to call. The security model is the same one your company already runs for every other system. No AI-specific identity layer, no prompt firewall, no model gateway. The tool boundary is the trust boundary.

The engineering shape is small. An MCP server, in my experience, is one engineer working with one domain expert for a few weeks per domain. That's the whole staffing model. Nine production servers in the first three months, twelve by the end of August. No platform team, no specialists. The people who own the underlying business systems can do most of the work themselves, with engineering support.

The servers aren't free once they exist. Schemas drift, a source-system upgrade breaks a connector, tool descriptions go stale as the business changes. That is the same kind of upkeep I just used as the argument against a custom RAG pipeline, and it applies here too. Across twelve servers it has run at roughly an hour a week. What makes it affordable is where it lands: on the people who already own those systems, in the weeks they are already working on them.

This is what makes the approach reachable. A small or mid-sized company doesn't need to hire an AI platform team to run this stack. The chat client is rented from a vendor at a price comparable to a productivity-suite seat. The MCP layer is built incrementally by the engineers and domain experts already on the payroll.

What you rent, what you own

What you rent	What you own
The chat client (Claude, ChatGPT, Gemini, your choice)	The MCP servers that encode your domain
Conversation history, attachments, multi-modal UI	Tool descriptions, query strategies, business logic
Enterprise SSO, audit logs, retention policies	Identity-gated tool access through your existing IdP
Frontend updates, model upgrades, security patches	Domain knowledge written into schemas
The model itself, latest version on day one	The integration with ERP, BIM, energy, calc
Predictable per-seat billing	One engineer, one domain expert, per server

What you rent is the commodity layer: the stuff vendors compete on and ship continuously. What you own is the part no vendor can build for you, because no vendor knows what your data means.

The same pattern, one floor down

The reason this is reachable goes one layer deeper than the chat client. The same logic applies to the framework layer underneath: LangChain, LangGraph, CrewAI, RAG pipelines, vector DBs, agent observability stacks. Building on top of those is one shape of architecture; building MCP servers directly against a frontier model is the same architectural posture without the additional layer.

Each MCP spec release closes another category of problem that previously required a framework layer. Tool calling, resource management, prompts, sampling, elicitation, UI primitives via MCP Apps, and enterprise identity integration on the 2026 roadmap. Each one used to live in a framework above MCP, and each one is now in the protocol itself. The framework layer isn't being argued against; it's being absorbed. Companies building on top of frameworks today are building on top of a layer the protocol is in the process of swallowing.

Both layers reward the same answer: rent the surface, own the domain. Use the vendor's client. Use the vendor's identity integrations. Use the vendor's model upgrades. Skip the framework layer. Spend your engineering on the part that's actually yours: the MCP servers that turn your operational data into something an agent can reason about.

That's what "MCP is the platform" actually looks like in practice: a perimeter you draw. Inside the perimeter: your domain, your tools, your IdP, your data. Outside: the model, the client, the vendor. The line between them is MCP.

If you're starting

Subscribe to Claude Team, ChatGPT Enterprise, or Gemini for Workspace. Connect your existing identity provider. Then pick the one system whose data your colleagues most want to query in natural language, and write one MCP server against it. Ship that. Watch them use it. Build the next one. The practitioner's guide walks the full seven-step recipe.

That's the entire starting move. No vendor selection process for an AI platform. No headcount plan for a platform team. No procurement cycle for orchestration software. A subscription, an identity wire-up, and one MCP server is enough to be in production with real users by the end of a month.

Three months of that across a real business produced nine production servers, and steady additions brought the estate to twelve by the end of August, with no framework dependencies, no custom chat UI, no API bill, no platform team, and a company that gets every frontier model upgrade for free the day it ships.

This architecture isn't a clever workaround for the moment. It's an early version of what enterprise AI looks like once the protocol layer finishes absorbing the platform layer above it.

Enterprise AI doesn't require an enterprise budget. It requires picking the right perimeter to draw.

MCP Is the AI Platform

David Golverdingen — Tue, 26 May 2026 07:11:26 +0000

Stop building around the model. Build for MCP.

By the end of August, the production estate at one mid-sized engineering firm had reached twelve MCP servers and 97 tools. Bound to Claude in our case, though everything below applies equally to GPT, Gemini, or any frontier model that speaks MCP, here's what I didn't build: agent frameworks, RAG pipelines, vector databases, orchestration platforms, or any of the other layers the AI industry insists you need.

What I have instead: a frontier model, MCP servers, and well-written tool descriptions. That's it. And it works, daily, across the whole business. Updated September 2026: "measurably" now has a public measurement behind it, on a reference server anyone can run, with one caveat I learned there: "well-written" includes short, because only the first 2,048 characters of a description reach the model on Claude Code (evidence).

By 2026 MCP isn't a niche bet. It crossed roughly 97 million monthly SDK downloads, and OpenAI, Google, Microsoft, and Anthropic have all integrated it across their products. The protocol question is settled. And because every frontier model now consumes MCP through the same interface, the model question is settled too. Pick any of them and the architecture doesn't change. What's still being argued is whether you need anything else on top.

The model is the agent. The framework is overhead.

The framing "you need an agent framework" obscures a simpler truth: the model is the agent. It reads tool descriptions. It chooses which tool to call. It sequences the calls. It interprets the results. That's textbook agentic behaviour, built into every frontier model that speaks MCP.

What companies sell you on top of that is framework around the agent: orchestration logic, retrieval pipelines, prompt managers, observability layers. Each of those products is solving a real problem in some context. But in a mid-sized business with a knowable set of important data sources, those contexts mostly don't apply.

What I use	What I skip
A frontier model (Claude in my case; swap as needed)	LangChain + LangGraph + LangSmith stack
MCP servers (custom, well-typed)	Multi-agent orchestration (CrewAI, Microsoft Agent Framework, OpenAI Agents SDK)
Tool descriptions as the interface	Vector DBs, embedding pipelines, agentic-retrieval frameworks (LlamaIndex)
Domain knowledge written into schemas	Hand-curated knowledge graphs sitting next to the tool
Cross-source composition through tool design	Workflow orchestration platforms
Production telemetry as the feedback loop	Agent observability stacks (LangSmith, LangFuse, Arize Phoenix)

Each row on the right is a paid product category. Each row on the left is the model, the protocol, or work I did once and reuse.

What "build for MCP" looks like in practice

A well-designed MCP server doesn't ask the model to figure out what the data means. It tells the model what the data means in the tool description itself.

The contrast plays out at every level. A bad tool says: "query data from the ERP." A good tool says: "always start with summaryOnly=true. Active projects accumulate thousands of records. Type codes determine which fields are populated. Use get_budget for planned costs, this tool for actuals."

The first version forces the model to invent a query strategy on every call. The second hands the model a query strategy on every call. The difference between those two servers, in production, is whether business users actually use the result.

This is the work teams skip when they reach for frameworks. The complexity is mostly self-inflicted. It exists because nobody wrote down what the tools mean. The same gap is why 97% of the MCP tool descriptions in a study of public servers contain at least one smell.

One server can compose many sources

The most common objection ("but you need orchestration to combine data from multiple systems") assumes orchestration has to live in a separate framework. It doesn't.

One of my MCP servers combines five heterogeneous sources behind one interface: a third-party meter-data aggregator, a public weather API, a government building registry, the company ERP, and an IoT building-automation platform. No agent dance. No retrieval pipeline. Just typed tools with descriptions explaining when each source applies and how they relate.

The model figures out the composition because the tool descriptions tell it the relationships. The pattern works across eleven production servers covering ERP, BIM, calculations, building automation, energy, and operational logs. Effectively the entire operational surface of one business, addressable through tool descriptions, consumable by any MCP-speaking model.

Tools abstract everything below them

The model never sees how the data is fetched. Inside one MCP server, individual tools call whatever the underlying system speaks: REST for SaaS products, GraphQL for internal APIs, direct SQL against the data warehouse, JSON files on disk, SOAP envelopes for legacy systems. The tool returns typed records; the protocol heterogeneity stays inside the tool.

That's the abstraction layer the data-fabric and iPaaS industries charge premium prices to build. MCP tools already do it, one tool at a time, in whatever language the data actually lives in, with no central pipeline. The choice of backend doesn't propagate; pick whatever fits the underlying system, and the model interface stays identical.

Even SQL becomes tractable. Direct SQL from an LLM is dangerous because the model can be tricked into destructive queries. But SQL inside a typed MCP tool (where the server builds SQL from schema-validated parameters, the connection runs as a read-only role, and the corporate IdP gates who can call it) is just a regular function call. Any value that doesn't match the tool's JSON schema is rejected at the protocol boundary before the tool's code runs at all.

This isn't theoretical. One of my servers is 100% SQL behind a query endpoint, covering calculation data. Every tool translates a typed agent request into a SQL query: the model passes schema-validated parameters in, the server constructs and runs the query, typed records come back out. The model never sees SQL. The connection runs as a read-only role, and access is gated by the same IdP roles that govern every other system.

I built it in one day. The calculation expert who owns the underlying data validated it, and it already exposes every dataset that team needs. Once you've internalised the pattern, applying it to a new domain is a day's work, not a quarter's project.

Why mid-market is the sweet spot

This argument has bounds. At Fortune 500 scale (hundreds of heterogeneous systems, multi-tenant SaaS, mountains of unstructured documents) you might need retrieval pipelines and orchestration. The complexity is real because the scope is real.

But mid-sized businesses have something Fortune 500 doesn't: a knowable set of important data sources. Five to twenty key systems. A handful of domain experts who can sit with you for an afternoon and tell you what the data actually means. That's the entire prerequisite for a well-built MCP server.

If your company fits in one office building and has fewer than twenty important systems, you're who this is for. You almost certainly don't need most of what the AI industry is trying to sell you.

What "the platform" actually is

Notice what's missing from the table above: a platform. There's no "AI platform" in the stack. Just a frontier model, MCP servers, and the corporate identity layer the business already pays for. Swap the model (Claude today, Gemini tomorrow, GPT next quarter) and the rest of the stack stays identical.

That last piece is what turns an estate of MCP servers into something an enterprise can run. Not an AI-specific identity layer. The one the company already operates. In a Microsoft shop, that's Entra ID with RBAC. In other shops, Okta, Google Cloud Identity, or any OAuth 2.1 provider. MCP servers authenticate against the existing IdP, scope tool access by role, and log every call to the same audit trail every other corporate system already uses.

The implications:

A field engineer can call the project and time-booking tools, and not the HR or payroll ones.
A controller sees aggregated financials, not raw payroll.
A guest user sees nothing.

Every action is attributable to a named identity in the same audit log as every other system. That's the entire enterprise AI security model. No prompt-firewall vendor. No AI-specific governance platform. No model gateway. Just the access-control infrastructure the company already runs, enforced at the MCP-tool boundary. Even prompt injection becomes bounded. A tricked model can only call tools the authenticated user is already authorised to call.

Anthropic's 2026 MCP roadmap leads with enterprise authentication and identity-provider integration. The protocol is moving in this direction because the pattern works: tool-level RBAC against the corporate IdP turns "the AI security problem" into a solved authentication problem. Which it always was.

Wire MCP servers through enterprise identity and MCP isn't connected to the platform. MCP is the platform.

The work that matters

What the framework industry sells is scaffolding. What actually moves outcomes is the specific, domain-bound work of writing good tool descriptions: choosing the right granularity, documenting which tool fits which question, adding query strategies, capturing failure modes from production usage and feeding them back.

None of that can be outsourced to a vendor, because nobody outside your business knows what your data means. But all of it is reachable in a few weeks per domain, with one engineer and one domain expert. That's the trade you're being told doesn't exist.

The question that replaces "which framework should I pick?"

If you're starting MCP work today, the most useful question isn't "which framework do I need?" It's "what's the smallest useful tool I can write for the one person whose week would get better tomorrow if it worked?"

Build that. Watch them use it. Write down what they tried that didn't work. Update the tool description. Ship the next one.

Three months of that across a real business produced nine production servers (eleven since) and zero framework dependencies. That's the story: not that frameworks are bad, but that for most mid-sized companies, they're the wrong problem to be solving first.

The model is the agent. The IdP is the security boundary. MCP is the platform. Build for the platform, not around it.

This post is one piece of a longer argument. Production MCP: A Practitioner's Guide puts all of them in order, from understanding your data through to identity-bound deployment.

The Six Levels of MCP Servers

David Golverdingen — Mon, 25 May 2026 20:25:32 +0000

Most MCP servers do the same thing: wrap an API, expose tools with one-sentence descriptions, and hope the model figures out the rest. In a previous post I described why this can fail for enterprise data. Here's the maturity ladder that emerged from an eleven-server, 90+ tool production snapshot across eleven APIs.

I call it the six-level MCP maturity model. It classifies an MCP server by how much of the domain the server itself carries, on a ladder from Level 1 API Mappers, which expose bare endpoints and leave the model guessing, to Level 6 Secure Write Apps, which act on the system of record. I derived the six levels in 2026 from eleven production servers running at a Dutch HVAC installation company.

Two different samples are at work below, and it is worth keeping them apart. The ladder comes from that eleven-server snapshot. The share column does not: those percentages come from reviewing 50+ publicly available MCP servers in March 2026, so they describe the public ecosystem, not my own estate, and they're a snapshot, not a tracked metric. Eleven servers could not tell you what 10,000 are doing. The Missing Layer sets out that review in full, with named examples at every tier.

Level	Name	Share of servers	What the server carries
1	API Mapper	~70%	Endpoint names and nothing else
2	Functional	~20%	Grouped tools, longer descriptions
3	Metadata-Rich	~8%	Curated knowledge sitting next to the tool
4	Self-Teaching	<2%	Domain knowledge inside the descriptions and schemas
5	Interactive App	emerging	Rendered UI returned by the server
6	Secure Write App	frontier	Validated writes back to the system of record

The types of MCP servers and how they differ

They differ along a single axis: how much of the domain the server carries, versus how much it leaves the model to guess. That is what separates one type from the next. Each level below hands the model something the previous one withheld — starting from bare endpoint names, through typed metadata and descriptions that teach the model how to query, up to interactive apps that write back to the system of record.

Level 1: API Mapper (~70% of servers)

One tool per endpoint. One-sentence descriptions. No domain context. The model figures everything out alone from the tool name. Ask "which projects are running over budget?" and it will happily invent a filter, hit an empty endpoint, and tell you everything is fine.

Level 2: Functional (~20%)

Tools are grouped sensibly. Descriptions are longer. Someone thought about how a human would use this. Still no domain knowledge, no cross-tool references, no query strategies. This is the ceiling most commercial MCP implementations aim for today.

Level 3: Metadata-Rich (~8%)

Knowledge graphs, glossaries, data catalogs. The metadata is real, but it lives next to the tool rather than inside it, and it was typically curated by hand over weeks or months. In practice, manual curation doesn't scale, and the agent only reads it if it happens to call the right meta-tool. I built two of these layers (MCP Resources and a parameterless "guide" tool) and removed both after testing. No Claude client ever requested them unprompted. Updated September 2026: the guide tool deserved a second look. In later evals it was called 10 times in 10 once the description said "REQUIRED: call this first", against 0 in 10 for a soft hint (Q8b). Unprompted it still goes unused; required, it works.

Level 4: Self-Teaching (<2%)

The domain knowledge is in what the model actually receives: the field names, the head of the tool description, the input schema, and the tool's response. Output schema validates the response, but the model never sees it. Updated September 2026: this used to say the description and input schema are the only reliable channels. Measured on Claude Code, only the first 2,048 characters of a description arrive, so the rules for reading a result now travel in the response (Q7, Q15). And that knowledge wasn't written by humans scanning documentation; it was discovered by an AI examining real data, flagged with confidence levels, then validated by domain experts. I called the pattern Introspective Context Engineering for MCP.

The difference is not subtle. A Level 1 server says "query data from the ERP." A Level 4 server says "always start with summaryOnly=true, active projects accumulate thousands of records. Type codes determine which fields are populated. Use get_budget for planned costs, this tool for actuals. Report friction via report_problem." Not the same product. Not the same category.

Level 5: Interactive App (emerging)

The server doesn't just return data. It returns rendered UI. Interactive charts, sortable tables, clickable maps, typed forms, all drawn by the server and displayed inline in the conversation. The agent coordinates; the server controls presentation.

A table of 400 rows in a markdown code block is unreadable. A rendered, sortable, filterable table is a tool a business user can actually use. Level 5 is where the interface meets the user where they are.

Working examples from an open-source demo server: render_chart and render_table, each a self-describing tool whose schema teaches the agent how to configure the view, no wrapper logic required.

Level 6: Secure Write App (frontier)

The server doesn't just read, it writes. Carefully. Two patterns: agent-initiated bounded writes for low-risk mutations (feedback, scores) through standard tools, and user-initiated secure writes for business-critical data through validated MCP App interactions. I call this the WriteIntent pattern: agent opens the door, user walks through it, server checks every step.

Almost nobody is here yet. Most builders are still nervous about giving MCP servers write access at all, and until Level 6 patterns exist, they should be.

The progression

Expose data (1) → organize tools (2) → understand the domain (3) → learn from data and feedback (4) → present through interactive apps (5) → act through secure writes (6).

Most of the public MCP ecosystem is stuck between 1 and 2. MCP isn't dead. Most MCP servers are empty. A different transport doesn't fix that; filling the tool interface with real domain knowledge does.

If you're building an MCP server today, the most useful question isn't "which framework should I pick?" It's "what level is mine, and what does Level N+1 look like?"

This post is one piece of a longer argument. Production MCP: A Practitioner's Guide puts all of them in order, from understanding your data through to identity-bound deployment.