Which makes it a context problem rather than a tooling preference. 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.

Which leads to the rule holding 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 not content.

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.

Which brings me to the vendors. 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. 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.

That is the part I did not see 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:

1. Pull, re-read the ticket, take the first task that is not done.
2. Claim it: mark it in-progress, commit, push. Before any code, so the board and any parallel session see the claim.
3. Implement exactly that task. Build it, test it.
4. Present the pending diff and wait for approval.
5. Complete the task, write the work log entry, commit code and bookkeeping together, push.
6. 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.

Which 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.

Which 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.

Our answer is three review layers, firing at different times for different reasons. What surprised me is which one carries the weight. It is not the review of the code. It 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 is read in seconds during refinement, 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

Each task maps to one self-contained commit, so a fresh session can resume from the ticket alone. 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 a day of rework, 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.

The draft goes to Codex, from a 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.

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 so it stays a visible decision rather than an omission.

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.

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.

Which, on the good days, is what code review was supposed to be.

Over three months at one mid-sized engineering firm (not a software company), I operationalised AI across the entire business. Eleven production MCP servers covering ERP, BIM, fleet, calculations, building automation, energy, and operational logs. 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. Through that client, employees have access to eleven 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, eleven now. No platform team, no specialists. The people who own the underlying business systems can do most of the work themselves, with engineering support.

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. There's no procurement cycle for an "AI platform," no consulting engagement to size the rollout, no infrastructure to provision.

What you rent, what you own

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. Not a stack you build, 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 since have taken it to eleven, 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 is going to look like once the protocol layer finishes absorbing the platform layer above it. The companies that build this way now are getting a head start on a stack that won't look unusual in two years. It will look obvious.

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

Go deeper: read the full practitioner report, The Missing Layer, or explore the working code in the mcp-metadata-demo server.

After shipping eleven production MCP servers across one mid-sized engineering firm (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: measurably, daily, across the whole business.

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.

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 MCP tool descriptions analysed in production contain at least one critical 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, fleet, 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 eleven 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 sees only their own time bookings and assigned projects.
• 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.

Go deeper: read the full practitioner report, The Missing Layer, or explore the working code in the mcp-metadata-demo server.

These are the six changes, grounded in production experience rather than speculation, that would raise the floor for every server in the ecosystem.

1. Smarter tool discovery

Today, every connected MCP server dumps all its tools into the agent's context at once. For a single server with 10 tools, that's fine. For a developer in an IDE with 10 servers connected simultaneously? That's 100+ tool descriptions competing for context.

This has a chilling effect on metadata investment: why write 200 lines of rich domain knowledge per tool if the client is going to flood the context with everything?

The spec needs a discovery layer: DNS for tools. Let servers declare tool groups with short summaries. The client presents groups to the model, the model selects the relevant group, and only those tool definitions are injected. Resolve first, load second.

2. Extensible metadata without context flooding

All metadata currently goes into tool descriptions and input schema descriptions, both consuming context tokens on every call. There's no mechanism for metadata the agent can request on demand.

A tool could declare 200 lines of field-level documentation, cross-reference tables, and query strategy guides as structured metadata. The client loads the tool's name and short description by default, but injects the full metadata only when the model indicates it wants to call that tool.

This would eliminate the trade-off between rich documentation and context efficiency, a trade-off that currently forces server authors to compress critical domain knowledge into artificially short descriptions.

3. Resources that actually work

MCP Resources are the spec's answer to reference documentation: static or dynamic content that agents can request to inform their reasoning. In theory, perfect for domain guides and field dictionaries.

In practice, no tested client reliably surfaces resources to agents. Claude Desktop lists them in a sidebar but agents don't request them. Claude Code and Cursor ignore them entirely. I built resources, tested them, and removed them after validation showed zero agent-initiated requests.

For resources to work, clients need to either: automatically inject relevant resource content when a related tool is selected, allow servers to mark resources as required context for specific tools, or give the model an explicit get_resource primitive that it's trained to use.

4. First-class feedback loops

The current spec has no concept of agent-to-server feedback. Every interaction is request-response: call a tool, get data, move on. No standard way for agents to report confusion, flag data quality issues, or indicate which calls were unhelpful.

I solved this with a custom report_problem tool and queryIntent parameters on every input schema. This works, but it's a workaround. The spec should support feedback as a first-class primitive: a standardized way for agents to annotate tool calls with intent, satisfaction, and issues encountered. Server authors could subscribe to feedback events and improve metadata iteratively, closing the loop that currently requires custom infrastructure.

5. Agent training on MCP patterns

Perhaps the most impactful change would happen not in the spec but in model training. Current models are not trained on rich MCP interactions. They don't know that a WHEN TO USE block should be parsed differently than a generic API description. They don't understand that .describe() annotations on output schema fields are there to be read and used.

If model providers included rich MCP server interactions in their training data (tool descriptions with domain metadata, multi-tool sequences with cross-references, feedback loops with intent parameters), agents would naturally leverage the metadata that server authors invest in writing. The metadata is already machine-readable. The models just need to be taught to read it.

6. Scoped write permissions for MCP Apps

As servers evolve from read-only to interactive applications, write operations become inevitable. But the spec offers no mechanism to restrict a write tool to a specific interaction context. If a server exposes a POST tool, any connected agent can call it at any time.

I designed a workaround: the WriteIntent pattern. The agent calls a model-visible "open" tool that mints a server-side intent. The actual mutation is performed by a separate "commit" tool registered with visibility: ["app"], hidden from the agent, callable only by the MCP App form. The intent is user-bound, resource-scoped, one-shot, time-limited, and validated with typed schemas.

The spec should formalize this: a way to scope write tools to specific MCP apps, so that a tool marked as write-only-via-app can only be invoked through a validated form interaction, not through freeform agent reasoning.

All six recommendations share a common theme: the spec is designed for transport, but the real challenge is knowledge delivery and safe interaction. Addressing these gaps at the framework level would raise the floor for every server, not just the ones built by teams willing to invest 40 hours in metadata engineering.

Go deeper: read the full practitioner report, The Missing Layer, or explore the working code in the mcp-metadata-demo server.

The description blocks I covered in a previous post are the initial knowledge layer. But how do you know what's missing? How do you find the gaps the agent silently works around without telling you? That's where the feedback architecture comes in.

After running eleven MCP servers in production, I settled on three layers (weighted roughly 70/20/10 by value) with one design choice that ties everything together.

Layer 1: Tool call logs (70% of the value)

Log every tool call: request parameters, response summary, session ID, timestamp. No conversation text, no user questions, no agent reasoning. Just the MCP layer.

This is the foundation. Three consecutive calls with tightening filters on the same table means the agent is struggling with something the metadata should have covered. You don't need the agent to tell you it's confused. The call pattern tells you.

In the production implementation, every tool call writes to a persistent store with: tool name, user, queryIntent, filter fields and operators (not values, for privacy), summaryOnly flag, row count, duration, and error type. Session IDs correlate multi-tool sequences.

Layer 2: Pattern analysis (20% of the value)

Weekly analysis of the raw logs. Look for repeated call sequences, redundant calls, unused tools that should have been used, tools called in unexpected order.

Session IDs make this possible. You can trace an entire multi-tool interaction from start to finish and ask: where did the agent take a detour? Where did it call tool A when the answer was in tool B? Where did it retry with different filters because the first call didn't return what it expected?

This finds silent failures: cases where the agent got a wrong answer without realizing it.

Layer 3: QueryIntent + report tool (10% of the value)

A queryIntent parameter on every tool call: one sentence describing the business question being answered. Plus a report tool the agent can use when genuinely stuck.

Here's where it becomes concrete. The same three-call sequence, with and without queryIntent:

Without:

09:14:03 | get_service_records | summaryOnly=true, project=P-7056

09:14:07 | get_service_records | type=13, project=P-7056

09:14:09 | get_service_records | type=13, project=P-7056, completed=true

Three calls. The last one added a filter. Why? Unknown.

With:

09:14:03 | intent: Overview of all service records for project P-7056

09:14:07 | intent: Which maintenance orders exist for this project

09:14:09 | intent: Only completed orders, previous call also returned open items

Now you see exactly what happened: the agent expected only completed items but the metadata didn't make clear that a completion filter is needed. That's a targeted metadata fix requiring minutes to implement.

Nudge patterns: making feedback happen

Agents don't self-report reliably. Academic research shows mixed results on LLM metacognition. So instead of relying on the agent's initiative, the production implementation injects contextual nudges into tool responses:

• Empty results: "No records matched your filters. If unexpected, consider calling report_problem."
• Pagination detected: "You're paginating (skip=200). If you're doing this to manually aggregate data, call report_problem. We may be able to add that summary dimension."
• Every response: A feedback reminder as the last alert: "If this query took multiple attempts or returned confusing data, call report_problem before your next step."

These nudges are injected by the server's handler factory, not by the agent's judgment. They target specific friction patterns and give the agent a low-effort path to report issues it would otherwise silently work around.

Why this compounds

Each resolved issue makes the system permanently smarter. A metadata update isn't a patch. It eliminates an entire category of uncertainty for every future session, every connected agent. The metadata layer grows richer over time while the reasoning layer stays the same. Cheap, permanent, compounding progress.

Go deeper: read the full practitioner report, The Missing Layer, or explore the working code in the mcp-metadata-demo server.

In The Six Levels of MCP Servers, I described what each maturity level looks like. Here's what the jump from Level 1 to Level 4 actually takes.

A tool description is not a sentence

The MCP specification's own best-practice proposal considers this a good description: "Read the contents of multiple files simultaneously. More efficient than reading files individually." That's the ceiling the community is aiming for.

After building more than 90 tools across eleven production servers, I arrived at a different standard. A tool description is an operational manual, structured into blocks, each added because the agent failed without it.

The eight blocks

These blocks are not theoretical. Each was added in response to a specific failure mode observed in production. The agent picked the wrong tool, so add WHEN NOT TO USE. The agent fetched 2,000 records instead of a summary, so add QUERY STRATEGY. The agent ignored that a status code meant something entirely different for a different record type, so add INTERPRETATION.

What actually works as a metadata channel

Not everything you write reaches the agent. After testing across Claude Desktop, Claude Code, and Cursor, a clear hierarchy emerged:

Tier 1: Always works (~95% of the value). Tool descriptions and input/output schema .describe() annotations. The agent reads these on every call. This is where all domain knowledge must live.

Tier 2: Works sometimes. Server instructions, cross-tool behavioral rules injected at session start. Some clients inject them, others don't. Useful for global rules, not a substitute for per-tool descriptions.

Tier 3: Does not work in practice. MCP Resources and meta-tools for reference lookups. I built both, deployed them, tested them. Agents never requested them across any tested client. Both were removed.

The key insight: everything the agent needs must live in the tool description and input/output schema. That's the only reliable delivery channel, for now.

Before and after

The difference in practice. A building profile tool, same API, same data:

Level 1: "Look up building information by postcode and house number." Two untyped parameters. No field documentation. The agent guesses what an energy label means, whether the building year is reliable, and which postcode format the API accepts.

Level 4: Structured WHEN TO USE / WHEN NOT TO USE blocks. A QUERY STRATEGY that warns the agent not to trust smart meter registration addresses as physical building addresses. An INTERPRETATION block that explains three different energy certification standards: NTA 8800 returns kWh/m2, Nader Voorschrift returns MJ total building energy. Without that block, the agent compares them as if they're the same unit and gives confidently wrong advice. Input schema with regex validation. Output fields with .describe() annotations documenting null patterns, cross-tool join keys, and which surface area field to use for which benchmark.

Same tool. Different category. The Level 1 version exposes an API. The Level 4 version teaches the agent how a domain expert thinks about this data.

An open-source extract of this tool, with the metadata patterns intact, lives in the mcp-metadata-demo repo: read get-building-profile.ts to see the eight blocks and .describe() annotations on a real tool.

Go deeper: read the full practitioner report, The Missing Layer, or explore the working code in the mcp-metadata-demo server.

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.

Level 4: Self-Teaching (<2%)

The domain knowledge is in the tool description and the input/output schemas, the only channels the agent reads reliably on every call. 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?"

Go deeper: read the full practitioner report, The Missing Layer, or explore the working code in the mcp-metadata-demo server.

The industry blames data quality. Every survey names it the number one obstacle. But MIT identifies something deeper: not a data problem, but an adaptation failure. Generic AI tools work for individuals but stall in enterprise use because they don't learn from or adapt to specific workflows.

Clean data is not the same as understood data.

The technician that wasn't there

Consider a service management ERP. A maintenance record has an "assigned technician" field. The AI reads it, finds it empty, and tells the user no technician was assigned.

In reality, that field is never populated. The actual technician can only be found through time-booking records filtered by a specific work-order type. The data is perfectly clean. The AI simply doesn't have the interpretation layer to know that this field is a dead end.

This is a data interpretation problem, not a data quality problem.

The market solves the wrong thing

The response follows a consistent pattern: solve the transport problem. RAG embeds documents in vector stores, useful for policy questions but useless for live operational queries. Text-to-SQL translates natural language to syntax, but doesn't know that a "type" field needs a specific numeric code or that certain schema fields are dead ends. Vendor-built AI has platform knowledge but mostly serves standard workflows, not free natural language access across domain-specific data models.

In all cases, knowledge lives in infrastructure layers (vector stores, prompt templates, governance dashboards) rather than in the tool interface where the LLM actually reasons at call time.

Skills: cookbooks at the door

Anthropic's skills guide diagnoses the problem correctly: users connect an MCP server but don't know what to do next. It prescribes a client-side "knowledge layer" of markdown recipes. The diagnosis is right. The prescription treats the symptom.

Skills exist because MCP servers are Level 1. If the server already taught the agent what the data means, when to use which tool, and how to chain calls, there would be nothing left for the skill to teach. The kitchen has no recipes, so they hand out cookbooks at the door.

And client-side knowledge reintroduces the problems it claims to solve: it goes stale when the server updates, fragments across clients and versions, and only helps the one client that loaded it. A skill uploaded to Claude doesn't help the same server when connected to Cursor, Copilot, or a custom agent.

Why nobody builds the missing layer

Four reasons.

Developer mindset. "I make the API available, the LLM is smart enough to figure out the rest." For GitHub or Slack, this works. The model knows what a pull request is. For a mid-market ERP with industry-specific type codes? None of that is in any model's training data.

No complex domain. Most MCP servers wrap well-understood APIs. A GitHub server doesn't need to explain what a commit is. An ERP server does need to explain what a service ticket (type 10) means versus a maintenance order (type 13) versus a service planning (type 48).

No feedback loop. Most builders ship and move on. They don't have power users hitting limits daily, revealing which metadata is missing and which interpretations lead to wrong answers.

New technology. MCP is still maturing. The idea that a tool description could contain multi-paragraph domain knowledge simply hasn't occurred to most builders yet.

The fix isn't a different transport or a client-side knowledge layer. It's filling existing servers with domain intelligence, directly in the tool descriptions and schemas where the agent actually reads it.

I mapped out six maturity levels to make sense of this gap.

Go deeper: read the full practitioner report, The Missing Layer, or explore the working code in the mcp-metadata-demo server.

After shipping eleven production MCP servers at one mid-sized engineering firm over three months, a coherent framework emerged. The thesis: for mid-market companies (five to twenty key data sources, accessible domain experts, no Fortune-500-scale complexity), MCP plus your existing identity infrastructure is the entire AI platform. No RAG. No agent frameworks. No AI-platform vendors.

This guide walks the framework end to end. Each section links to a detailed post on the topic, and to the practitioner report for the full method.

Why most enterprise AI fails

MIT puts the enterprise AI failure rate above 80%. The industry blames data quality. That diagnosis is mostly wrong.

In the field, the data is usually fine. What's broken is meaning: the AI doesn't know what your data means, how the systems relate, which source answers which question. The technician field on the work order is empty, but the real technician name lives in the time-booking records of a parallel system, and nobody told the AI that.

Most "AI data problems" are documentation problems wearing a different name. Fix the documentation in the one place the model reliably reads on every call (the tool description) and the data starts working.

Full argument with concrete examples: Your Data Is Fine. Your AI Doesn't Know What It Means..

The six-level maturity ladder

Once you accept that meaning lives in tool descriptions, you can grade MCP servers by how seriously they treat that layer. After more than 90 tools across eleven APIs, a ladder emerged:

• Level 1: API Mapper (~70%). One tool per endpoint. One-sentence descriptions. The model invents and fails.
• Level 2: Functional (~20%). Tools grouped sensibly, longer descriptions, no domain knowledge. The ceiling most commercial implementations aim for.
• Level 3: Metadata-Rich (~8%). Knowledge graphs living next to the tool. The agent rarely reads side-channels; I built two of these layers and removed both.
• Level 4: Self-Teaching (<2%). Domain knowledge lives inside the tool description, discovered by AI from real data, validated by experts. Production-ready.
• Level 5: Interactive App (emerging). The server returns rendered UI.
• Level 6: Secure Write App (frontier). The server writes back, gated by IdP, structured around explicit user intent.

Most public servers sit between 1 and 2. MCP isn't dead; most servers are empty.

Full breakdown: The Six Levels of MCP Servers.

Tool descriptions are the work

97.1% of MCP tool descriptions, across 856 tools in 103 servers (MCP Tool Descriptions Are Smelly!, arXiv:2602.14878), contain at least one critical smell: unstated limitations, missing usage guidelines, opaque parameters. That's not fringe. That's the baseline.

A tool description is not a sentence. It's an operational manual, structured into blocks, each one added because the agent failed without it. After 52 production tools, the pattern converged to eight: RETURNS, WHEN TO USE, WHEN NOT TO USE, QUERY STRATEGY, INTERPRETATION, EXAMPLES, CROSS-REFERENCES, FAILURE MODES.

Same data behind a Level 1 and a Level 4 tool. Different products entirely in production behaviour.

The eight-block pattern with examples: How to Write MCP Tool Descriptions: The 8-Block Pattern from 11 Production Servers.

Introspective Context Engineering for MCP

The hardest part of writing good tool descriptions is that the domain knowledge they require lives in your team's heads, not in any document. Asking a domain expert to dictate 500 words of operational guidance per tool produces dry, incomplete text. Asking them to review AI-discovered patterns produces precision in a fraction of the time.

That insight became a five-phase pattern I call Introspective Context Engineering for MCP (ICE):

1. Examine: point an AI at real data. Ask it to discover patterns, flag confusing fields, generate hypotheses.
2. Flag: the AI marks each pattern with a confidence level (certain, probable, uncertain).
3. Validate: the domain expert reviews. Confirms, corrects, or rejects.
4. Encode: validated patterns are written into the tool description and schema.
5. Iterate: production usage exposes new gaps; the cycle repeats.

This inverts the traditional metadata-curation pipeline. Instead of asking humans to write down everything (which doesn't scale), the AI asks questions and the human approves answers (which does). The output is structured domain knowledge in the only place the agent reliably reads it.

ICE is what makes Level 4 reachable in days rather than quarters. It's also why the pattern works for mid-market companies and stalls at Fortune 500 scale: it needs a domain expert who can sit with you for an afternoon, not a 40-person governance committee.

The full five-phase method with the feedback architecture: practitioner report.

The feedback loop

A good MCP server isn't built once. It evolves. Three patterns show up in production telemetry that no design session anticipates:

• The agent calls the same tool three times with tightening filters → the description didn't say which filter to try first.
• The agent invents a parameter that doesn't exist → the schema left ambiguity about what's available.
• The agent uses a tool for a query that belongs to a different tool → both WHEN TO USE blocks need sharpening.

Each one is invisible without instrumentation. The pattern that works: every tool accepts a queryIntent string (one sentence from the agent describing what it's trying to find) and logs it alongside parameters. The logs reveal what the agent thought it was doing, which exposes the metadata gap exactly.

Fixes are small. Minutes per fix, not weeks per design cycle.

The full pattern with the queryIntent design: Your MCP Server Should Get Smarter Every Week.

What the MCP spec gets wrong

After more than 90 tools in production, six gaps in the current MCP spec became hard to ignore. The headline ones:

• Resources are the spec's answer to reference documentation. No tested client surfaces them reliably. I built two Resource layers and removed both. Everything has to live in the tool description.
• Enums are loose. Different clients render them differently; some don't show allowed values to the model at all. The agent invents values and the tool rejects them.
• No standard for tool-level RBAC. Every team rolls its own auth pattern; few survive an enterprise audit.

Not reasons to abandon MCP. Reasons to write servers around the parts of the spec that work and push for changes where they don't.

Full list: Six Things the MCP Spec Should Fix.

MCP plus identity is the platform

This is the reframe most "do I need an AI platform?" conversations miss. The platform isn't a product you buy. It's two pieces you already have, composed differently:

1. A frontier model that speaks MCP (Claude, GPT, Gemini, protocol's the same).
2. The corporate identity layer the business already pays for (Entra, Okta, Google Cloud Identity).

Wire MCP servers through enterprise identity and the AI platform is built. Tools authenticate against the existing IdP, scope access by role, log every call to the audit trail every other corporate system uses. A field engineer sees only their own work orders. A controller sees aggregated financials, not raw payroll. Every action is attributable to a named identity.

That's the entire enterprise AI security model. No prompt-firewall vendor. No AI governance platform. No model gateway. Just access control the company already runs, enforced at the MCP tool boundary. Anthropic's 2026 roadmap leads with enterprise authentication. The pattern works.

Complete argument with the use/skip table: MCP Is the AI Platform.

Without an enterprise budget

Enterprise AI gets sold as something only large companies can afford. The path that justifies that price tag (custom chat UI, prompt platform, RAG pipeline, agent framework, model gateway, observability stack) commits a smaller company to a build budget, a platform team, an aging pinned model, and an unpredictable per-token bill, all at once.

The alternative is one structural decision: rent the surface, own the domain. Subscribe to the vendor's chat client at €19/seat/month. Connect your existing IdP. Put your engineering hours into MCP servers for the systems no vendor will ever connect for you. No frontend to maintain, no platform team to staff, no orchestration platform to buy. The model upgrades on the vendor's clock, for free.

The full architecture with the rent/own breakdown and the framework-absorption argument: Enterprise AI Without an Enterprise Budget.

Where to start

The recipe that worked, applied nine times:

1. Pick one domain expert who has too much to do. The accountant who keeps getting margin questions. The fleet manager who keeps getting asked where the vans are. The energy specialist who keeps pulling weather data manually. The person whose week would get visibly better if a specific question got an instant answer.
2. Pick one specific question that person gets asked every week. Not a category. One actual question, with a known correct answer, that takes them more than five minutes manually.
3. Build one MCP tool that answers it. Wrap whatever access the data lives behind (REST, GraphQL, SQL, file). Write the description as if explaining the data to a sharp new hire who has never seen this domain.
4. Wire it through your existing IdP so only that expert (and people they explicitly authorise) can call it.
5. Hand it to the expert. Watch what they try. Log every call. They will try things you didn't anticipate.
6. Update the tool description to fix what you saw. Add WHEN NOT TO USE blocks. Add examples. Tighten the QUERY STRATEGY. Ship the fix the same day if you can.
7. Pick the next question. Build the next tool. Add it to the same server if it's the same domain, a new server if it's a new domain.

Three months of that, applied across domains, produces a portfolio of working MCP servers and a team that uses them unprompted. Not a project plan. A practice.

The skip list, equally important:

• Don't build a framework first.
• Don't build a registry, a router, or an "MCP platform" first.
• Don't try to "do AI strategy" before you've shipped one useful tool.
• Don't ask permission. Domain experts will thank you; committees will slow you down.

The full method

This guide is the practitioner's overview. The complete framework with the Introspective Context Engineering for MCP method, the six-level maturity model, the WriteIntent pattern for secure writes, and the analysis of where the MCP ecosystem is heading is the practitioner report.

If you ship one tool that one colleague uses unprompted within a week, you've already crossed the line that 80% of enterprise AI projects never cross. The rest is repeating that loop until your business has one MCP-shaped layer instead of many integration projects.

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

Go deeper: read the full practitioner report, The Missing Layer, or explore the working code in the mcp-metadata-demo server.