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

> Source: <https://dev.to/quotentiroler/transport-surface-skin-building-mcp-plugins-that-survive-the-spec-5dln>
> Published: 2026-07-25 12:57:57+00:00

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?

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:

`initialize`

/ `initialized`

handshake is `_meta`

on every request, under keys like `io.modelcontextprotocol/protocolVersion`

.`Mcp-Session-Id`

. Any request can hit any instance.`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.`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.`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 `Mcp-`

for the new pair.`notifications/cancelled`

on this transport.`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:

``` php
(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.

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` |

`@maxhealth.tech/prefab`

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

`@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:

``` js
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](https://datatracker.ietf.org/doc/html/rfc9728) `/.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:

``` js
// 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.

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:

`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`

`404`

, so old clients can tell "wrong era" from "wrong URL." Anything that 404s every non POST needs a small change.`Mcp-Session-Id`

and `Last-Event-ID`

is now exposing two headers that no longer exist.`_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.

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:

``` js
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:

``` js
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:

`text/html;profile=mcp-app`

.`text/html`

is silently treated as an ordinary resource and never loads in an iframe.`registerViewerResource`

sets `_meta`

in both places for exactly this reason.`structuredContent`

is required.`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.

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:

`--primary`

, `--card`

, `--radius`

, `--success`

, `--font-sans`

). Stable across every brand and every stack.`{ 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:

``` js
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:

``` js
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.

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

``` js
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.

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.

`@maxhealth.tech/mcp-http`

`@maxhealth.tech/prefab`

`brandc`