Maximilian Nussbaumer

Posted on Jul 25

Transport, Surface, Skin: Building MCP Plugins That Survive the Spec

#ai #architecture #llm #mcp

Software engineering is dead. That is what they say.

Partially true. Some traditional elements of the craft are genuinely hard to find now. If a model can write the function, why would a human sit down and type it out? The honest answer is: increasingly, they would not.

But losing the typing is not the same as losing the engineering. What actually happened is that the interesting question moved up a level. It used to be how do I build this application. Now it is how do a human, an application, and a model share one workspace.

That question is why the Model Context Protocol went from a curiosity to infrastructure so fast. MCP is the answer to using one or more applications together with AI, simultaneously and synchronously. Not the model calling your API behind the user's back, but the model, the user, and your app all operating on the same live surface.

So: how do you actually build one of these things?

The protocol is a moving target, and that is the point

Anyone who shipped an MCP server in 2025 has rewritten it at least twice. The transport story alone went stdio, then SSE, then Streamable HTTP. Streamable HTTP won and is now the dominant way to build.

And on July 28, 2026, the next revision lands. It is the biggest one yet, because it makes MCP stateless:

The initialize / initialized handshake is gone (SEP-2575). Protocol version, client info, and capabilities now ride in _meta on every request, under keys like io.modelcontextprotocol/protocolVersion.
Protocol-level sessions are gone (SEP-2567). No more Mcp-Session-Id. Any request can hit any instance.
The standalone GET stream endpoint is removed (SEP-2575). Long lived streams did not disappear, they moved: change notifications now arrive on the response stream of a subscriptions/listen POST, which stays open and carries only the notification types you opted into. What did die is resumability, because Last-Event-ID and SSE event ids are gone outright.
Servers no longer send requests to clients at all. Sampling, elicitation and roots are embedded in an InputRequiredResult, which the client answers by retrying the original call with matching inputResponses (SEP-2322, "multi round trip requests"). The spec is blunt: a server "MUST NOT send independent JSON-RPC requests" on a response stream, and clients "MUST NOT send JSON-RPC responses" at all.
Two routing headers become required (SEP-2243): Mcp-Method on every request, and Mcp-Name on tools/call, resources/read and prompts/get only. Intermediaries can now route and rate limit on the operation without parsing a body. MCP-Protocol-Version is not new here, it has existed since 2025-06-18, and mind the casing asymmetry when you write it down: all caps for that one, Mcp- for the new pair.
Cancellation on Streamable HTTP is now simply closing the response stream. No notifications/cancelled on this transport.
Capabilities gain an extensions field (SEP-2133), which makes extensions genuinely first class: reverse DNS identifiers, negotiated through capability maps, living in their own repositories on their own version cadence.

Read that list again and notice what it adds up to. Your MCP server stops being a stateful daemon you have to keep alive and turn into sticky sessions. It becomes a pure function:

(Request, Token) -> Response

Which is exactly the shape of a Cloudflare Worker, a Deno Deploy handler, a Pages Function, or a Bun.serve fetch. Round robin load balancing, zero shared state, no session store to leak memory.

That is a much simpler thing to build. It also means the engineering is no longer in the plumbing. It is in the contracts.

Three layers, three contracts

Once the server is a pure function, a well built MCP plugin decomposes cleanly into three concerns that have nothing to do with each other:

Layer	Concern	Package
Transport	HTTP, OAuth, CORS, lifecycle	`@maxhealth.tech/mcp-http`
Surface	What the user sees and clicks	`@maxhealth.tech/prefab`
Skin	What it looks like, everywhere	`brandc`

Each one is a contract, not a framework. You can throw any of the three away and keep the other two. Let us walk them.

Layer 1: transport

@maxhealth.tech/mcp-http is a framework agnostic MCP HTTP transport built on the Web Fetch API. It runs on Workers, Pages Functions, Deno Deploy, Bun, Node 18+, and anything Hono deploys to. It has been stateless first from day one, which is why the July revision needs no redesign here. Additions, yes. Redesign, no.

A complete authenticated MCP server on Cloudflare Workers:

import { createWorkerFetch, forwardBearer } from '@maxhealth.tech/mcp-http'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'

export default {
  fetch: createWorkerFetch({
    authorizationServer: 'https://auth.example.com',
    createServer: (token) => {
      const server = new McpServer({ name: 'my-api', version: '1.0.0' })
      const fetchFn = forwardBearer(token)
      // register tools using fetchFn for upstream calls
      return server
    },
  }),
}

That is the whole server, and you get more than a transport out of it. You get RFC 9728 /.well-known/oauth-protected-resource served automatically, optional RFC 8414 authorization server metadata, Bearer extraction with a proper 401 and a WWW-Authenticate resource metadata pointer, JWT exp early rejection with a 30 second clock skew buffer, configurable CORS, and an onRequest observability hook that reports outcome, status, and duration.

Two design decisions in there are worth stealing regardless of what you use.

createServer is a per request factory. It receives the caller's raw token. That is the whole trick of stateless auth: the server instance lives exactly as long as the request that authorized it, so a token can never leak into another user's call. The internals are refreshingly boring:

// one transport per POST, no session id generator at all
const transport = new WebStandardStreamableHTTPServerTransport()
await server.connect(transport)
const res = await transport.handleRequest(normalizedReq)

forwardBearer(token) is the seam for on behalf of calls. It hands you a fetch that carries the caller's identity upstream. Your tools never see a credential, they see a function. In a healthcare context, where every FHIR read has to be attributable to a real human with real scopes, that seam is the difference between a demo and something you can put in front of an auditor.

There is also a handleMcpPostStateful path, which keeps a transport alive across requests so the server can issue sampling and createMessage calls. Be clear eyed about what that is now: it routes on Mcp-Session-Id and mints sessions on initialize, and both of those are gone in the new revision. Sampling, roots and logging are themselves deprecated with a twelve month removal window, while ping, logging/setLevel and notifications/roots/list_changed are removed immediately. So it is not "the thing stateless mode cannot do," it is a legacy client path for features on their way out. Design so you do not need it.

What the new revision actually costs a transport

Being honest about the gap is more useful than claiming there is none. Stateless was the right shape early, and the shape holds. The work that remains is real but bounded:

Header validation is now the transport's job. A server that reads the body MUST reject header and body mismatches with 400 and JSON-RPC -32020 (HeaderMismatch), including missing required headers. That is squarely transport layer work.
GET and DELETE on the MCP endpoint SHOULD return 405, not 404, so old clients can tell "wrong era" from "wrong URL." Anything that 404s every non POST needs a small change.
Default CORS needs a trim. Exposing Mcp-Session-Id and Last-Event-ID is now exposing two headers that no longer exist.
The SDK floor moves. Protocol semantics (_meta versioning, MRTR, subscriptions/listen) come from @modelcontextprotocol/sdk, so a peer range of >= 1.29.0 wants a beta bump. Beta SDKs for Python, TypeScript, Go and C# are already out.

None of that touches your tools. That is the point of the seam.

Layer 2: surface

Now the interesting part. Your tool ran, you have data. What comes back?

The default answer is a wall of text for the model to summarize. That is fine for a lookup and terrible for anything a human should touch. If MCP is about using applications together with AI, then a tool result has to be able to be an application.

That is what @maxhealth.tech/prefab does. You build a component tree on the server, hand it to display(), and return the envelope:

import { display, Column, H1, autoTable } from '@maxhealth.tech/prefab'

async function listPatients() {
  const patients = await db.query('SELECT * FROM patients')
  return display(Column([H1('Patients'), autoTable(patients)]), { title: 'Patients' })
}

display() serializes the tree to the $prefab wire format and folds it into an MCP tool result, putting the JSON in content[] as the model's fallback and in structuredContent for the host to render. A zero dependency vanilla DOM renderer, loaded as a single script tag in a ui:// resource, paints it inside the host's sandboxed iframe. 115+ components, reactive template expressions, and auto renderers (autoTable, autoChart, autoForm, autoMetrics) that turn raw rows into a real UI in one call.

The mechanism underneath is MCP Apps, and its status is worth being precise about, because a lot of writing gets this wrong. MCP Apps is not part of the core specification. It is one of two official extensions, it landed with protocol version 2026-01-26, it lives in its own repository (modelcontextprotocol/ext-apps) and it versions independently. The 2026-07-28 core revision does not mention Apps at all. What it adds is the extensions field on capabilities (SEP-2133) that makes that separation official.

Which is a better story than "it is in the spec." An extension on an independent cadence can iterate on interactive UI at UI speed, while the core protocol stays boring and stable. You want your renderer shipping fixes monthly and your transport changing once a year.

Registering the viewer resource correctly is where most people lose an afternoon, so it is one call:

import { registerViewerResource, PREFAB_RESOURCE_URI } from '@maxhealth.tech/prefab/mcp'

registerViewerResource(server)

server.registerTool(
  'browse',
  {
    title: 'Browse',
    inputSchema: schema,
    _meta: { ui: { resourceUri: PREFAB_RESOURCE_URI } },
  },
  async (args) => ({
    content: [{ type: 'text', text: JSON.stringify(data) }],
    structuredContent: data,
  }),
)

Note registerTool, not tool. Every tool() overload in the SDK is deprecated in favour of it, and only registerTool's config object accepts inputSchema and _meta. The tool() signature takes Args | ToolAnnotations there, so passing a config literal fails the excess property check. Note also that _meta.ui.resourceUri belongs on the tool definition, so it shows up in tools/list where the host can discover and prefetch the template, not on the result.

Three more bugs that helper exists to prevent, all of which cost real hours:

The MIME type is exactly text/html;profile=mcp-app. No space after the semicolon. Plain text/html is silently treated as an ordinary resource and never loads in an iframe.
CSP goes on both the resource listing and the content item. The Apps spec has hosts check both, preferring the content item and falling back to the listing. So the content item wins where both are set, but a listing only CSP still gives you a black iframe on the hosts that ignore the listing. registerViewerResource sets _meta in both places for exactly this reason.
structuredContent is required. Return only content[] and the host renders raw JSON, because the UI path never fires.

The pattern that makes this compose is that every handler returns a self contained UI. A list view carries a button whose click calls a detail tool. The detail view carries one that opens an edit form. Submitting calls a save tool. Multi screen flows fall out of independent handlers, with no client side router and no shared state, which is precisely what a stateless protocol wants. And when only the numbers change rather than the layout, display_update() sends a state patch the renderer merges into the live store instead of rebuilding the tree.

Layer 3: skin

Two layers in, there is a quiet duplication problem waiting. Your marketing site has a palette. Your web app has the same palette in Tailwind config. Now your MCP UI needs it a third time, as prefab wire JSON. Three copies of the same brand in three vocabularies is three chances to drift.

brandc is a brand compiler that solves this by separating two axes:

The contract: the names of the variables (--primary, --card, --radius, --success, --font-sans). Stable across every brand and every stack.
A brand: the values. Each colour authored once as a { light, dark } pair in structured TypeScript.

Every delivery format is generated from that one source, so they cannot drift: a CSS custom property stylesheet for SSR string injection, a theme.css file for bundlers, a Tailwind v4 @theme inline preset that maps by reference so runtime dark switching keeps working, and:

import { toPrefabTheme, maxhealth } from 'brandc'
import { display } from '@maxhealth.tech/prefab'

return display(view, { theme: toPrefabTheme(maxhealth) })

Look at what makes that line work. toPrefabTheme(brand) returns { light: Record<string, string>, dark: Record<string, string> }. Prefab's Theme interface is { light?: Record<string, string>, dark?: Record<string, string> }. The two packages know nothing about each other and compose exactly, because both agreed on a shape instead of on an implementation. That is the whole thesis of this article in one function call.

Rebranding is then a new Brand on the same contract:

const ocean: Brand = {
  name: 'ocean',
  colors: { ...maxhealth.colors, primary: { light: 'oklch(0.58 0.06 195)', dark: 'oklch(0.7 0.06 195)' } },
  scalars: { ...maxhealth.scalars, radius: '0.625rem' },
}

The CSS output is deliberately modern: light-dark() so each colour is one declaration rather than a duplicated dark block, @property registration so colour tokens have a <color> contract and are animatable, and oklch throughout. One gotcha worth flagging: if a Tailwind v4 app wants to rebrand colours only, pass scalars: {}, because the contract's --radius* and --shadow* names are the same keys Tailwind uses in @theme, and emitting them overrides Tailwind's own scale.

The whole plugin

Stacked up, an authenticated, branded, interactive MCP plugin is about thirty lines:

import { createWorkerFetch, forwardBearer } from '@maxhealth.tech/mcp-http'
import { display, autoTable, Column, H1 } from '@maxhealth.tech/prefab'
import { registerViewerResource, PREFAB_RESOURCE_URI } from '@maxhealth.tech/prefab/mcp'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { toPrefabTheme, maxhealth } from 'brandc'

const theme = toPrefabTheme(maxhealth)

export default {
  fetch: createWorkerFetch({
    authorizationServer: 'https://auth.example.com',
    createServer: (token) => {
      const server = new McpServer({ name: 'patients', version: '1.0.0' })
      const fetchFn = forwardBearer(token)

      registerViewerResource(server)

      server.registerTool(
        'list_patients',
        { title: 'List Patients', _meta: { ui: { resourceUri: PREFAB_RESOURCE_URI } } },
        async () => {
          const rows = await fetchFn('https://fhir.example.com/Patient').then(r => r.json())
          return display(Column([H1('Patients'), autoTable(rows)]), { title: 'Patients', theme })
        },
      )

      return server
    },
  }),
}

No session store. No sticky routing. No handshake to keep alive. Nothing in memory between requests. It scales behind a round robin balancer because there is nothing to scale, and it was already the shape the July 2026 revision asks for before that revision was written.

So is software engineering dead?

The typing is dying. Good.

What is left is the part that was always the actual job: deciding where the seams go. createServer taking a token instead of closing over one. display() returning an envelope instead of a string. toPrefabTheme() returning a shape another package happens to accept.

None of those are hard to write. A model will write any of them for you in seconds. Knowing that they are the three cuts that make a plugin survive a protocol rewrite, that is the work. The protocol changes again on Tuesday. It will change after that too. Build against contracts and you find out from the changelog instead of from your error rate.

DEV Community