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 fails for enterprise data. Here's the maturity ladder that emerged after building eleven production servers with more than 90 tools 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.
| 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.
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.
Top comments (3)
"An agent that can technically call your systems but doesn't actually understand your domain" is the precise gap between a Level 1-2 MCP server and a useful one, and almost everyone stops at the wrap-the-API stage because it demos fine. The trap is that exposing endpoints as tools just relocates the domain reasoning back onto the model, now the agent has to know that closing a fleet work order requires checking the energy reading first, because the raw tools don't encode that, and the model improvises a plausible-but-wrong sequence. The higher levels are really about moving domain constraints out of the model's guesswork and into the server: valid state transitions, required preconditions, the operations that should never be exposed as raw primitives. That's the same insight as harness-over-prompt, the server should make the wrong call impossible, not hope the model knows your business rules. Nine servers across ERP/BIM/fleet/energy is a serious proving ground for exactly where Level 1 breaks. That encode-the-domain-in-the-boundary thinking is core to how I build agent tooling in Moonshift. What distinguishes your Level 5-6 servers, is it enforced workflow/state, or domain validation the model can't bypass?
Neither, and that's the interesting part — validation isn't what separates 5 and 6. It's Level 4's job, and if it isn't in the schema by then, 5 and 6 can't rescue it.
Level 5 is presentation: the server renders the chart, table or form instead of returning markdown the agent reshapes. Level 6 is the write path, and there the answer to your either/or is "both, plus a third thing" — the user. That's the WriteIntent pattern: agent opens the door, user walks through it, server checks every step. Agent-initiated writes stay bounded and low-risk (feedback, scores); anything business-critical goes through an interaction a human actually confirms.
On validation the model can't bypass — the strongest version I've built isn't in the MCP server at all. It's one npm package holding the schema, the parser, and every edit operation as a pure function, imported by four consumers: a CLI, a web app, a commit gateway, and the MCP server. The MCP server has no authoring logic of its own. So a rule like "this can't be closed while its acceptance criteria are unticked" went in once and fires identically whether you type a CLI command, call the MCP tool from your phone, or drag a card across a board. There's no back door because there's only one door.
The override is the part I'd defend hardest: you can force past the gate, but it costs a written reason, and the same operation that flips the status appends that reason to the log. A gate people quietly route around reads as enforcement while providing none.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.