DEV Community: wolfejam.dev

Context Over MCP, Part VI: Context You Can See

wolfejam.dev — Thu, 01 Oct 2026 13:09:12 +0000

Part I asked: Invisible AGENTS.md? Here's the fix.

Your coding agent works from context: the project's AGENTS.md, the facts
it remembered last week, what it thinks this project is. It reads all of
that before it writes a line. You don't see any of it. When the agent does
something odd, you go digging: open the repo, find the file, scroll, guess
which part it took to heart.

Context is vital. But context you can't see is context you can't check.
Cards are better when they're visible.

TL;DR — see what your AI sees. Nothing to configure.

Talk to it (goose): add the mcp-context-card extension, open your project, and say "Show me my context card."

Terminal: in your project, run npx mcp-context-card card.

Either way the full card opens in your browser. The rest of this post is
the deeper dive.

The repo: mcp-context-card: one MIT server for a project's context, memory and identity. 10 tools, 134 tests, on npm and the official MCP Registry, tested in goose.

Try it: the goose way

This is the easy route. You talk to goose; goose shows you the card.

Add the extension. In goose Desktop: Extensions → Add custom extension. Type Standard IO, command:

   npx -y mcp-context-card

Nothing else. No path, no environment variable.

Open your project. Point goose's working directory at the project you want to see: the folder chip at the bottom of the chat.
Ask:

Show me my context card.

The server's reply leads with what it did, as a plain fact: New file:
(or Updated:) context-card.html in your project, and the path. The
model may put that in its own words; in the screenshot below it says the
card was "saved to the project and opened in your browser."

Then comes the card as text: the project's name and description, its
AGENTS.md sections, the first sentence of each memory fact word for word,
and where each one lives. At the same moment the full card opens in your
browser.

browser" width="799" height="518">

How did it know which project? The server asks the host which folder
you're working in, through the standard MCP roots request, and reads
that folder. In goose, that's the folder chip. Switch it, and the next card
follows.

The file it saved is yours to keep. It's a snapshot of what your agent
reads, next to the code it describes.

Try it: the terminal way

No AI, no host. In your project folder:

npx mcp-context-card card

It writes context-card.html and opens it in your browser. Add
--expanded to open every section, for a screenshot or a review with
someone else.

What the card shows, and why it helps

One page, four parts:

Identity — what this project says it is: name, version, status, license, one line of description.
Context — your AGENTS.md, every section, collapsed so the card scans in one screen. Open any section, or all of them.
Memory — every fact the agent has been asked to remember, with a mark on the ones that are verified.
Discovery — where each of those lives, and in what format, so a machine can find it too.

That's the same material your agent reads. Seen as a page, it does three
things the files alone don't:

It shows intent. The top of the card is the purpose of the project, stated once. If that line is wrong, everything downstream is aimed wrong.
It shows alignment. Reading the card, you see what the agent will see. A stale build command or a fact that stopped being true stands out on a card in a way it never does in a file you haven't opened in a month.
It puts you back in the loop. You check the context before the agent acts on it, not after, without digging through the repo.

A thirty-second review before a big task:

Is the one-line purpose still true?
Are the build and test commands the ones you actually use?
Is anything in memory out of date?

Whatever's wrong on the card is wrong in what the agent reads. Fix the
file, ask again, and the card follows. It's generated from your files every
time, so it can't drift from them.

An empty project is a starting point

Try it on a project with no AGENTS.md and the card doesn't stop at
"nothing here". Each empty section says what to do next:

Context: No AGENTS.md yet. Ask your agent to draft one. The server's author_agents_md tool builds one from the repo's real build and test commands, with nothing invented. Outside a chat, npx agents-md-facts writes the same facts.
Memory: No facts yet. Ask your agent to remember something, and it lands here.

So the first card shows you the gap and the next step in the same place.

In other hosts

The same server works in any MCP host. For hosts that take a JSON entry
(Claude Desktop, Cursor, and others):

{
  "mcpServers": {
    "context-card": {
      "command": "npx",
      "args": ["-y", "mcp-context-card"]
    }
  }
}

In Claude Code, from your project folder:

claude mcp add context-card -- npx -y mcp-context-card

The server finds your project the same way everywhere: the host's MCP
roots first, then the folder it was started in, if that has an
AGENTS.md. Ask "Which project are you reading?" and it tells you the
path and how it found it. To pin one project regardless, set
MCP_CONTEXT_CARD_ROOT to its path.

What you see depends on the host:

Hosts that support MCP Apps (the MCP extension for interactive UI) show
the full card inline, in the chat. When the host says so as it connects,
the model gets a one-line summary instead of a page of HTML.

That's the MCP Apps reference host drawing the card. It renders apps but
doesn't announce that when it connects, so its Tool Result panel still
shows the full HTML: the server can only shorten what it knows the host
will draw.

Every other host gets the text card in the chat, as in the goose example
above, and the full card in the browser. The reply also carries a link to
the file, and its address in a code block you can copy, for hosts that won't
open a local file link.

Before this, asking for the card put about 16,500 characters of raw HTML
into the chat. Now the reply is about 1,700, and it's something you can
read. Ask for the full detail if you want every memory fact in full; the
saved page always has everything.

Keep it true, with you in the loop

A card you can see changes how you work with memory.

Remember that the API tests need DATABASE_URL set.

remember and forget are marked as tools that change your project, so a
host that respects that asks you first. In goose, that's the approval
mode: Manual asks before every tool, and Smart asks before any
tool marked as changing your project. You'll see the request and approve
it. Then ask for the card again, and there's the fact, on the page.

When a fact goes stale, you'll notice it on the card before the agent acts
on it. Ask it to forget or correct it. Memory is a plain file in your repo,
so it goes through code review like everything else.

That's the loop: the agent reads context, you see the same context, and
either of you can fix it.

How it works, for builders

If you run your own MCP server, the pattern is small, and it needs nothing
beyond the standard SDK.

Ask the host which project. Clients that support roots list the folders the user is working in. Read the first file:// root, and listen for the roots-changed notification. No config for the user to get wrong.
Declare a UI resource. A ui:// resource with the MIME type text/html;profile=mcp-app, serving the card as one self-contained HTML page: inline CSS, no external requests.
Link the tool to it. The tool that renders the card carries _meta.ui.resourceUri pointing at that resource. Hosts that support MCP Apps fetch it and draw it.
Check what the client can do. A client that supports MCP Apps can declare it when it connects. Send those clients a one-line summary; send everyone else what they got before.
Don't strand the rest. A second tool saves the card, opens it when the server is local, and replies with the card as text, leading with what it did. Server instructions tell the model to use it instead of pasting HTML.
Keep the text honest. Each memory fact in the short view is cut at the end of its first sentence, exactly as stored. When we cut mid-sentence with "…", the model tidied the endings into sentences of its own. Memory is the one thing it shouldn't reword.

The code is MIT: mcp-context-card.
To build an MCP App of your own and try it in goose, the goose docs walk
through it: Building MCP Apps for goose.

Check it yourself

Add the extension to goose with just npx -y mcp-context-card, open a project, and ask "Show me my context card." The card is that project's, saved in that project's folder, and it opens in your browser.
Switch goose to a different project and ask again. The card follows.
In a terminal, in any project with an AGENTS.md, run npx mcp-context-card card. Its sections match your file's headings. Change a line in AGENTS.md, run it again, and the card shows the change.
Ask the agent to remember a fact, then ask for the card again. The fact is on it.

(Checked 27–30 September 2026: mcp-context-card 1.3.0, installed from npm,
in goose Desktop 1.52.0 and in the MCP Apps reference host.)

Context was always there. Now you can see it, and so can everyone
reviewing the work with you.

Thanks for reading, and to everyone who's followed Context Over MCP since Part I.

Tried it? Tell me in the comments what your card showed you, and what it got wrong. That's what shapes the next version.

No time right now? ★ bookmark the repo and come back before your next big task. One command, and you'll see what your agent sees.

The series, Context Over MCP:

Part I — Invisible AGENTS.md?
Part II — Publishing to the Registry
Part III — Horses for Courses
Part IV — No Working Directory At All
Companion — Build a WebMCP Tool From Scratch
Part V — The Form Is the Tool
Part VI — Context You Can See (this post)

Context Over MCP: Part V The Form Is the Tool.

wolfejam.dev — Fri, 25 Sep 2026 22:38:16 +0000

Part IV showed a WebMCP page with three tools. The companion walked through
building one yourself, the JavaScript way: registerTool(), a schema, a
handler. It mentioned the other way in one sentence and moved on.

This is the other way. No registerTool(), and no schema written by hand.
It's an HTML form, with a few attributes that tell the browser it's also a tool.

The playground from Part IV is now listed in the W3C Web Machine Learning
group's awesome-webmcp,
under Demos. That page is the production version of what you're about to build.

Save a blank index.html, serve it with python3 -m http.server, and open
http://localhost:8000 in Chrome with chrome://flags/#enable-webmcp-testing
turned on. Opened straight from disk, the page has no origin and the tool won't register.

Step 1 — start with a form that already works

Before it's a tool, it's a form a person can use. This one estimates a
shipping price. It's read-only: it calculates a number and places no order.

<form id="ship">
  <label>Weight (kg)
    <input name="weight_kg" type="number" min="0.1" max="30" step="0.1" required>
  </label>
  <label>Destination
    <select name="zone" required>
      <option value="domestic">Domestic</option>
      <option value="eu">EU</option>
      <option value="world">Rest of world</option>
    </select>
  </label>
  <label>Speed
    <select name="speed">
      <option value="standard">Standard</option>
      <option value="express">Express</option>
    </select>
  </label>
  <button type="submit">Estimate</button>
  <p>Result: <output id="result"></output></p>
</form>

<script type="module">
const RATES = { domestic: 4, eu: 9, world: 18 };

function estimate({ weight_kg, zone, speed }) {
  const w = Number(weight_kg);
  if (!Number.isFinite(w) || w < 0.1 || w > 30) {
    return { error: 'invalid_weight', message: 'weight_kg must be between 0.1 and 30' };
  }
  if (!Object.hasOwn(RATES, zone)) {
    return { error: 'invalid_zone', message: 'zone must be domestic, eu or world' };
  }
  const base = RATES[zone] + w * 1.5;
  const price = speed === 'express' ? base * 1.8 : base;
  return { price_eur: Math.round(price * 100) / 100, zone, speed: speed || 'standard' };
}

const form = document.getElementById('ship');
form.addEventListener('submit', (event) => {
  event.preventDefault();
  const result = estimate(Object.fromEntries(new FormData(form)));
  document.getElementById('result').value =
    result.error ? result.message : `€${result.price_eur}`;
});
</script>

Submit it by hand. You get a price, and the URL doesn't change. This is the
same order as the companion's Step 2: the logic is a plain function before
anything calls it.

Step 2 — add three attributes, and it's a tool

<form id="ship"
      toolname="estimate_shipping"
      tooldescription="Estimate the shipping price for one parcel. Returns price_eur. Does not place an order."
      toolautosubmit>
  <label>Weight (kg)
    <input name="weight_kg" type="number" min="0.1" max="30" step="0.1" required
           toolparamdescription="Parcel weight in kilograms, 0.1 to 30">
  </label>
  <label>Destination
    <select name="zone" required toolparamdescription="Destination zone: domestic, eu or world">
      <option value="domestic">Domestic</option>
      <option value="eu">EU</option>
      <option value="world">Rest of world</option>
    </select>
  </label>
  <label>Speed
    <select name="speed" toolparamdescription="standard or express">
      <option value="standard">Standard</option>
      <option value="express">Express</option>
    </select>
  </label>
  <button type="submit">Estimate</button>
  <p>Result: <output id="result"></output></p>
</form>

toolname names the tool.
tooldescription tells the agent what it does. Say what it doesn't do too ("does not place an order"), so the agent doesn't have to guess.
toolparamdescription on each control becomes that parameter's description.

You don't write the schema. The browser builds the tool's input schema from
the form's named controls, and it reads more of the form than you might
expect. Here's what Chrome 153 generated from the form above:

{
  "type": "object",
  "properties": {
    "weight_kg": { "type": "number", "minimum": 0.1, "maximum": 30, "multipleOf": 0.1,
                   "description": "Parcel weight in kilograms, 0.1 to 30" },
    "zone":      { "type": "string", "enum": ["domestic", "eu", "world"],
                   "description": "Destination zone: domestic, eu or world" },
    "speed":     { "type": "string", "enum": ["standard", "express"],
                   "description": "standard or express" }
  },
  "required": ["weight_kg", "zone"]
}

min, max and step became minimum, maximum and multipleOf. Each
<select> became an enum (Chrome also adds each option's label as a
title, trimmed here). required became required. That's convenient, and
it's also the main thing to remember in Step 5.

Notice the <output> has an id and no name. That's deliberate: it shows
the result and isn't something the agent should fill in.

Step 3 — answer the agent, not just the screen

With toolautosubmit, the agent's call fills the fields and submits the form.
Your submit handler runs as usual. To hand the result back as the tool's
output, call respondWith() on the submit event:

form.addEventListener('submit', (event) => {
  event.preventDefault();
  const result = estimate(Object.fromEntries(new FormData(form)));
  document.getElementById('result').value =
    result.error ? result.message : `€${result.price_eur}`;
  if (typeof event.respondWith === 'function') {
    event.respondWith(Promise.resolve(result));
  }
});

Three details:

preventDefault() first. Without it, the form navigates, and the page that registered the tool goes away mid-call.
The form's rules are the tool's rules. Because max and the <option> list are in the schema, Chrome checks them before your handler runs. An agent that asks for 99 kg gets Form validation failed: weight_kg: Value must be less than or equal to 30., and one that asks for zone "mars" gets Invalid value "mars" for parameter zone. The checks in estimate() are a second line of defense, for the day someone edits the form and forgets the function. Anything that gets past the form comes back as { error, message }, as in the companion's Step 3.
The typeof guard. In a browser without WebMCP, respondWith doesn't exist, the guard skips it, and the form is still a working form.

Chrome also sets event.agentInvoked to true when an agent submitted the form,
if you want to behave differently for agents. Here, the answer is the same for
anyone who asks.

Step 4 — decide who presses Submit

toolautosubmit is a decision, not a default.

With it: the agent fills the fields and the form submits. That's right for
this tool: it's read-only and nothing happens that someone would want to review.

Without it: the agent fills the fields, and a person has to click Submit.
That's right for anything with consequences, and it's the reason the attribute
is opt-in.

One thing to know before you remove it: from the caller's side, that call
stays pending until someone submits or cancels. A conventional MCP client
talking to the page can't tell "waiting for a human" from "stuck" (see
webmcp#307). If a
person needs to confirm, make the waiting visible on the page.

Chrome gives you hooks for that:

form:tool-form-active { outline: 2px solid #00D4D4; }
button:tool-submit-active { box-shadow: 0 0 0 3px #00D4D4; }

window.addEventListener('toolactivated', (event) => {
  if (event.toolName === 'estimate_shipping') {
    document.getElementById('result').value =
      'An agent filled this form. Check it, then press Estimate.';
  }
});

toolactivated fires when the agent has filled the fields. It fires on
window, not on the form (a listener on the form never hears it), so check
event.toolName if the page has more than one tool.

If the page resets the form while the agent waits, the call ends with an
error: Tool execution cancelled by a form reset. Chrome's docs also describe
a toolcancel event; in Chrome 153 I didn't see it fire on a reset, so don't
depend on it yet.

Step 5 — the fields that should never become parameters

Step 2's convenience has a cost. Every named control becomes something an
agent can fill in. For a shipping form, that's fine. For a checkout, login or
identity form, it means card numbers, CVVs, one-time codes and national ID
numbers become agent-fillable parameters, and they end up in a transcript.
A checkout form with name="cvv" becomes a tool with a cvv parameter.

The spec doesn't have guidance for this yet
(webmcp#316 is open).
Until it does, a simple rule:

Don't make a sensitive form a tool. Make a smaller form that is one: "estimate", "check availability", "find a slot". Let the person handle the part with their card or code themselves.
If a form must be a tool, leave sensitive controls out of it. A control without a name isn't submitted with the form. Do that on purpose, and say it in tooldescription ("payment details are entered by the user").
Read-only tools can auto-submit. Anything else shouldn't.

The whole page

Everything from Steps 1–4 in one file, for copying:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Shipping estimate</title>
  <style>
    form:tool-form-active { outline: 2px solid #00D4D4; }
    button:tool-submit-active { box-shadow: 0 0 0 3px #00D4D4; }
  </style>
</head>
<body>
<form id="ship"
      toolname="estimate_shipping"
      tooldescription="Estimate the shipping price for one parcel. Returns price_eur. Does not place an order."
      toolautosubmit>
  <label>Weight (kg)
    <input name="weight_kg" type="number" min="0.1" max="30" step="0.1" required
           toolparamdescription="Parcel weight in kilograms, 0.1 to 30">
  </label>
  <label>Destination
    <select name="zone" required toolparamdescription="Destination zone: domestic, eu or world">
      <option value="domestic">Domestic</option>
      <option value="eu">EU</option>
      <option value="world">Rest of world</option>
    </select>
  </label>
  <label>Speed
    <select name="speed" toolparamdescription="standard or express">
      <option value="standard">Standard</option>
      <option value="express">Express</option>
    </select>
  </label>
  <button type="submit">Estimate</button>
  <p>Result: <output id="result"></output></p>
</form>

<script type="module">
const RATES = { domestic: 4, eu: 9, world: 18 };

function estimate({ weight_kg, zone, speed }) {
  const w = Number(weight_kg);
  if (!Number.isFinite(w) || w < 0.1 || w > 30) {
    return { error: 'invalid_weight', message: 'weight_kg must be between 0.1 and 30' };
  }
  if (!Object.hasOwn(RATES, zone)) {
    return { error: 'invalid_zone', message: 'zone must be domestic, eu or world' };
  }
  const base = RATES[zone] + w * 1.5;
  const price = speed === 'express' ? base * 1.8 : base;
  return { price_eur: Math.round(price * 100) / 100, zone, speed: speed || 'standard' };
}

const form = document.getElementById('ship');
const out = document.getElementById('result');

form.addEventListener('submit', (event) => {
  event.preventDefault();
  const result = estimate(Object.fromEntries(new FormData(form)));
  out.value = result.error ? result.message : `€${result.price_eur}`;
  if (typeof event.respondWith === 'function') {
    event.respondWith(Promise.resolve(result));
  }
});

window.addEventListener('toolactivated', (event) => {
  if (event.toolName === 'estimate_shipping') {
    out.value = 'An agent filled this form. Check it, then press Estimate.';
  }
});
</script>
</body>
</html>

Step 6 — verify it before you add anything else

In Chrome with the WebMCP flag on, document.modelContext also has
getTools() and executeTool(), so you can play the agent from the console.
Run these in order:

The tool is there, with the schema from Step 2.

   const [tool] = await document.modelContext.getTools();
   JSON.parse(tool.inputSchema);

tool.name is estimate_shipping, and the schema has minimum, maximum, the two enums and required: ["weight_kg", "zone"].

A valid call returns a value, and the page stays put.

   await document.modelContext.executeTool(tool,
     JSON.stringify({ weight_kg: 2, zone: 'eu', speed: 'standard' }));

It returns '{"price_eur":12,"zone":"eu","speed":"standard"}', the page shows €12, and the URL doesn't change. Two things to note: executeTool takes the tool object from getTools(), not its name, and the result comes back as a JSON string.

Invalid calls are rejected by the form. Try { weight_kg: 99, zone: 'eu' } and then { weight_kg: 1, zone: 'mars' }. Both reject, with Form validation failed: weight_kg: Value must be less than or equal to 30. and Invalid value "mars" for parameter zone. Your handler never runs.
Without autosubmit, the call waits for a person.

   document.getElementById('ship').removeAttribute('toolautosubmit');
   const pending = document.modelContext.executeTool(tool,
     JSON.stringify({ weight_kg: 5, zone: 'world', speed: 'express' }));

The fields fill, the outline appears, the result line says an agent filled the form, and pending doesn't settle. Press Estimate: it resolves with '{"price_eur":45.9,"zone":"world","speed":"express"}' and the outline goes away.

Nothing leaves the tab. Open DevTools → Network and repeat step 2. No requests.

(Checked in Chrome 153 with #enable-webmcp-testing on, 25 September 2026.)

The same shape, in production

fill_6ws on faf.one/webmcp is this pattern: a plain
form with toolname, tooldescription, toolautosubmit and a
toolparamdescription on each of its six fields. It calls
preventDefault(), answers with respondWith({ yaml }), and doesn't navigate.
It auto-submits for the same reason Step 4 gives: it builds text and changes nothing.

Pick by what the page already has. If it already has a form that does the
job, the form is the tool. If it doesn't, registerTool() is there.

Series: Part I — Invisible AGENTS.md? · Part II — Publishing to the Registry · Part III — Horses for Courses · Part IV — No Working Directory At All · Build a WebMCP Tool From Scratch.

"Pack of Cards: five agent-card specs, drawn as one map"

wolfejam.dev — Tue, 22 Sep 2026 15:59:18 +0000

TL;DR: Machines find an agent or a server through cards — small files they read. Five seem prominent. Every spec lives in public git, so we read every version and drew them as one map, after Harry Beck's Underground diagram.

In Plain English

Five cards. Five specs, all in public git.
Eight choices. Every card picks a name field, an identity, a discovery path, a media type, an encoding, an extension point, a trust model and a versioning rule.
One centre. The centre line is what most cards share. Distance is what only one card does.

First, the one that is not a card

We followed the MCP Registry closely, so start there. server.json is the Registry entry — how a server gets published, rather than a card a server serves at its own door. It is not on the map, and it is the piece faf-cli writes today:

faf cards --target registry

32,237 latest-version entries, counted page by page from the Registry API on 2026-09-15. Server Card Rev 1 borrowed its shape, which is where that line branches from.

Then the cards

Five. A2A Agent Card, MCP Server Card, AI Catalog, ARD and .fafa.

A2A reached Released v1.0 and joined AAIF at Growth Stage on 2026-08-27 — the one other specs point at when they need to describe an agent and would rather not invent a card. AI Catalog is moving fastest: MCP's own MCP Catalog is evolving into it, and the spec turned over #37 and #77 five weeks apart. ARD says Proposal. .fafa is ours.

They overlap, they disagree, and they are all in public git. So we read every version.

How to read it

Beck's 1933 diagram dropped geography and kept order. We did the same with time.

Time runs west to east. Each card is a line. Each station is a spec change, spaced by order, not by calendar. A ring marks the day two cards start or stop sharing a choice.

Two views. Protocol ↔ Envelope (the default): cards defined by one protocol sit above the centre, protocol-neutral envelopes below. Strict ↔ Loose: each card's required fields against the median.

The map as a band. The live version is interactive — hover a station, follow a tick to the spec at that commit, switch the view.

What it shows

A2A opens alone. The map starts with A2A v0.2.0 in May 2025. Nothing to compare it with until MCP Server Card's first draft, SEP-2127, on January 21, 2026.
Twins. On June 25, 2026, AI Catalog merged #37 and #36. With ARD v0.9 already on urn:air, the two met on the centre line.
A step in. On July 20, MCP Server Card moved discovery to /.well-known/ai-catalog.json.
The split. On August 26, ARD v0.91 took its own ard.json, JSON-LD and a trust manifest. The twins parted. AI Catalog moved that day with no spec change of its own. Distance is relative.
Furthest out: .fafa. The only card with an IANA-registered media type, and the only one written in YAML. Registering moved it one step further out. Different, not wrong.

How it's built

30 spec versions. 269 quotes, each checked against its line at its commit. Every station links to the spec at that commit, and every value links to the line it was quoted from — the register is public, so any figure here can be checked.

We make .fafa. So the rules came first, and .fafa landed where the rules put it.

The choice list is a judgement. A different list draws a different map. The quotes are public, so anyone can check it, or redraw it.

Some interesting facts

A2A was alone for 245 days. The first card landed on 2025-05-21. There was nothing to compare it with until 2026-01-21.
Five cards, five different extension points. Of the eight choices we track, extension is the only one where no two cards agree.
A2A asks for eight required fields. AI Catalog asks for three.
AI Catalog shipped eight versions in 141 days. A2A shipped six in 479.

Three ways to name a card

A media type is the label a machine reads before it opens the file.

None of these five specs requires one. They landed on three different answers.

A2A Agent Card and ARD name no media type.

AI Catalog uses application/ai-catalog+json. MCP Server Card uses application/mcp-server-card+json. Neither is registered.

.fafa uses application/vnd.fafa+yaml, registered with IANA on 2026-06-26.

Every value above links to the line it was quoted from.

What it cost us to keep up

The map carries our own lane too, because keeping up is the hard part and we have not always managed it.

AI Catalog merged #37 on June 25. We conformed on June 26 — one day.

AI Catalog merged #77 on July 30, moving extensions to a map. We answered in three days and used an array. It stayed wrong for forty-five, and working group parsers rejected the document the whole time.

Speed is not currency on its own. The check is.

Five, out of thirty-six

Five cards are drawn. We checked thirty-one more against one test: a public spec with git history, describing an agent or a server so machines can find it. Eight pass, seven are borderline, sixteen are out — each listed with the reason, on the page.

A card that does not make the map is not a lesser card. It is a card that answers a different question.

Get your pack

Seven answers describe an agent or a server: name, short name, domain, what it does, version, where it runs, what it can do. From those, faf-cli writes the .fafa and projects every card that has a place for it — correct to each spec, checked by each spec's own validator.

npx faf-cli@latest cards --target catalog,ard

The map · the register · how the cards work

Context Over MCP: Build a WebMCP Tool From Scratch

wolfejam.dev — Tue, 15 Sep 2026 12:30:00 +0000

Part IV showed three tools already registered, already working, on someone
else's page. This is the version where you register one on yours — a real
tool, with the same failure modes any WebMCP tool has, fixed the same way.

No build step, no bundler, no dependency you haven't chosen yourself. Save a
blank index.html, serve it with python3 -m http.server, open
http://localhost:8000, and follow along. Opened straight from disk, the page
has no origin and the tools won't run.

Step 1 — detect WebMCP, don't assume it

document.modelContext exists natively in Chrome behind a flag
(chrome://flags/#enable-webmcp-testing). Everywhere else, a polyfill can
provide the same surface. Check for the real thing first, fall back
explicitly, and know which one you got — don't silently assume either:

<script type="module">
async function getModelContext() {
  if (document.modelContext?.registerTool) {
    return { context: document.modelContext, source: 'native' };
  }
  try {
    const { initializeWebMCPPolyfill } =
      await import('https://esm.sh/@mcp-b/webmcp-polyfill');
    initializeWebMCPPolyfill();
  } catch {
    return { context: null, source: 'none' };
  }
  return document.modelContext?.registerTool
    ? { context: document.modelContext, source: 'polyfill' }
    : { context: null, source: 'none' };
}
</script>

If source comes back 'none', stop here and fix that before writing a
single tool — everything below assumes a real context object.

Every block below goes inside the same <script type="module">.

Step 2 — write the tool as a plain function first

Don't reach for a real YAML parser or a scoring library yet. Prove the shape
works with something you can read in five seconds:

function scoreFacts(yaml) {
  const required = ['name', 'goal', 'who', 'what', 'why'];
  const present = required.filter((key) => new RegExp(`^\\s*${key}:`, 'm').test(yaml));
  return {
    score: Math.round((present.length / required.length) * 100),
    populated: present.length,
    total: required.length,
    missing: required.filter((k) => !present.includes(k))
  };
}

Five required keys, a regex check per key, a percentage. That's the whole
scorer. It's not what a real implementation should ship — it's what lets you
verify the registration works before you go anywhere near real parsing.
(The \s* matters: a real project's facts are usually nested — who:
sitting indented under a human_context: block, not at column zero. Test
this against a flat file only and it'll look like it works; test it against
a realistically nested one and a too-strict regex reports fields "missing"
that are right there, just indented.)

Step 3 — register it the way errors don't crash the caller

This is the part that's easy to get wrong: a WebMCP tool that throws is a
tool an agent can't recover from cleanly. Return errors as data, and validate
input before it reaches your function:

async function registerScoreTool(context) {
  await context.registerTool({
    name: 'score_facts',
    description: 'Score a structured facts document 0-100 by which required fields are present.',
    inputSchema: {
      type: 'object',
      properties: { yaml: { type: 'string', description: 'YAML text to score' } },
      required: ['yaml']
    },
    annotations: { readOnlyHint: true },
    execute: async (input) => {
      const yaml = typeof input?.yaml === 'string' ? input.yaml : '';
      if (!yaml.trim()) {
        return { error: 'invalid_input', message: 'yaml is required' };
      }
      try {
        return scoreFacts(yaml);
      } catch (err) {
        return { error: 'score_failed', message: err instanceof Error ? err.message : String(err) };
      }
    }
  });
}

Three things doing real work here, none of them optional:

annotations: { readOnlyHint: true } — tells the caller up front this can't change anything, before it ever calls the tool.
The empty-input check runs before scoreFacts — a missing field is a normal case, not an exception.
The try/catch around your own function means a bug in scoreFacts comes back as { error, message }, not a stack trace the caller has to parse to understand what happened.

Wire the two together and open the page:

getModelContext().then(async ({ context, source }) => {
  if (!context) return console.warn('WebMCP not available:', source);
  await registerScoreTool(context);
  console.log('score_facts registered via', source);
});

Step 4 — verify it before you add anything else

Install the Model Context Tool
Inspector,
open it on your page (the localhost URL, not the file), and check:

[ ] Inspector lists score_facts
[ ] Calling it with valid YAML (containing name:/goal:/who:/what:/why:) returns a score
[ ] Calling it with { yaml: "" } returns { error: "invalid_input", ... } — not a crash
[ ] The console logs which source registered it (native or polyfill)

If any of those fail, stop here. Everything past this point assumes a
working, verified tool.

Step 5 — the part most tutorials skip: don't trust a URL parameter

The moment a tool accepts a URL instead of pasted text — "fetch the YAML
from here" — it's fetching something the caller named, not something you
chose. That's a real risk, not a hypothetical one, and it needs the same
kind of explicit check execute got in Step 3:

const ALLOWED_HOSTS = new Set(['raw.githubusercontent.com']); // your trusted hosts only

function assertAllowedUrl(urlString) {
  const url = new URL(urlString); // throws on garbage input — let it
  if (url.protocol !== 'https:') {
    throw new Error('url must use https');
  }
  if (!ALLOWED_HOSTS.has(url.hostname)) {
    throw new Error(`host not allowlisted: ${url.hostname}`);
  }
  if (url.pathname.split('/').includes('mcp')) {
    throw new Error('mcp endpoints are not allowed');
  }
  return url;
}

Three checks, each closing a different door:

Exact hostname match, not a substring check — evil-raw.githubusercontent.com.attacker.net doesn't pass just because it contains the right string.
HTTPS only — a tool that fetches over plain HTTP hands a man-in-the-middle the exact document it's about to trust.
No mcp segment in the path — a page tool has no business talking to an MCP server; naming the block explicitly makes it a decision, not an accident.

Call it inside execute's try, before the fetch, so a rejected URL comes
back as { error, message }. Then fetch with redirect: 'error': a redirect
is a new request to a host your check never saw, and the browser sends it
before your code can read response.url.

Step 6 — the same shape, in production

This whole pattern — detect the context, register with readOnlyHint,
validate before executing, return errors as data, allowlist any fetch — is
the shape faf.one/webmcp uses for score_faf and emit_agents_md, with a
WASM scoring kernel where yours has a regex. Its third tool,
fill_6ws, takes the other route: a plain HTML form with toolname
attributes, registered by the browser. That page is one real,
production instance of it. It's not the only way to build one — it's what
happens when you take Steps 1 through 5 and keep going.

Companion to Context Over MCP, Part IV: No Working Directory At
All — the explainer that describes an already-built WebMCP page. This
is the version where you build one.

Context Over MCP, Part IV: No Working Directory At All

wolfejam.dev — Mon, 14 Sep 2026 16:26:34 +0000

Part I: an MCP client has no working directory, so it never sees your AGENTS.md.

Part II: publish the server so a client can find it.

Part III: keep facts as data and instructions as prose, so what it finds is worth seeing.

Now take the working directory away completely. WebMCP's client is a browser
tab, and a tab doesn't fail to find a working directory. It doesn't have the
concept.

So what does "expose your context" mean when there's no repo, no process, and
no server — just a page?

The API is not FAF's

document.modelContext.registerTool() is Chrome's own experimental API
(chrome://flags/#enable-webmcp-testing). A page registers a tool, an agent
inspecting that page calls it, done — no separate MCP process, no transport,
no working directory to have or lack. Where the native API isn't available,
@mcp-b/webmcp-polyfill — a real, independent package, not FAF's — provides
the same registerTool surface as a fallback:

const native = getDocumentContext();
if (native && typeof native.registerTool === 'function') {
  return { context: native, source: 'native' };
}
try {
  const { initializeWebMCPPolyfill } = await import('@mcp-b/webmcp-polyfill');
  initializeWebMCPPolyfill();
} catch {
  return { context: null, source: 'none' };
}
const polyfilled = getDocumentContext();
if (polyfilled && typeof polyfilled.registerTool === 'function') {
  return { context: polyfilled, source: 'polyfill' };
}
return { context: null, source: 'none' };

WebMCP doesn't care what you register. This is the part that matters more
than any specific tool: the platform capability is generic, open, and not
owned by anyone's product. What follows is one demonstration of it, not the
only shape it can take.

Three tools, two ways to register them

faf.one/webmcp registers three:

Tool	Returns
`score_faf`	`{ score, tier, populated, active, gaps }` — 0–100, in-browser
`fill_6ws`	a `human_context:` YAML fragment from a form
`emit_agents_md`	`{ markdown }` — a minimal AGENTS.md render

Those are Part III's three moves, in a tab: fill in the six W's, score what's
still blank, and write the AGENTS.md from the facts.

score_faf and emit_agents_md are registered in script with
registerTool(), and both carry annotations: { readOnlyHint: true }. That's
not a comment. It's part of the registration, and an agent can read it before
calling anything: the same trust signal MCP tool annotations give a client, now
on a web page instead of a server.

fill_6ws is a plain HTML form with toolname, tooldescription and
toolautosubmit attributes: the browser turns the form into the tool. If the
form isn't picked up, the page registers fill_6ws in script instead.

score_faf runs entirely client-side. The scoring kernel is WASM
(faf_wasm_sdk), compiled once from the same Rust source the CLI and the
edge workers use — no server round-trip, no MCP process to spin up:

export function scoreYaml(yaml: string): string {
  if (!ready) throw new ToolError('kernel_not_ready', 'WASM scoring kernel is not initialized');
  return score_faf(yaml);
}

And the result mapper refuses to pad the picture. Ignored slots — fields that
don't apply to this project — aren't counted as missing:

/** Score is populated/active. Ignored slots are not missing — 13/13, not 13/21. */

gapsFromSlots only reports what's genuinely empty. A tool that's willing to
inflate its own denominator to look better is exactly the kind of thing a
"structured facts" argument falls apart without.

The part that's honest about its own limits

emit_agents_md renders a real AGENTS.md — Setup & build, Run the tests,
Stack, 6Ws — from the same .faf fields the CLI reads. But the file's own
comment says what it isn't:

// Minimal renderer — not the full faf-cli AGENTS.md compiler.

It doesn't do Guardrails tiers, branch-aware Commit & PR, or any of the
richer sections the real compiler produces — because a browser tab is a
different environment with a different budget than a CLI process, and a
renderer that pretended otherwise would be lying about what ran. The output
says so too — a plain, one-line stamp at the foot: compiled from application/vnd.faf+yaml. Not "compiled with faf-cli." A different tool
made this.

The fetch surface is an allowlist, not a promise

score_faf and emit_agents_md can take a URL instead of pasted YAML. That
means the page fetches something the agent asked for — and a page that
fetches whatever a caller names is a real risk, not a hypothetical one. The
check is explicit, and it runs before anything is requested:

export function assertAllowedUrl(urlString: string): URL {
  const url = new URL(urlString);
  if (url.protocol !== 'https:') {
    throw new ToolError('invalid_url', 'url must use https');
  }
  if (!ALLOWED_HOSTS.has(url.hostname)) {
    throw new ToolError('invalid_url', `host not allowlisted: ${url.hostname}`);
  }
  if (url.pathname.split('/').includes('mcp')) {
    throw new ToolError('invalid_url', 'mcp endpoints are not allowed');
  }
  return url;
}

Two hosts only — faf.one, raw.githubusercontent.com — exact match, not a
suffix (their own comment: "ide.faf.one is not faf.one"). HTTPS only,
256KB cap. And a URL with an mcp segment in its path is rejected outright, by
name — the tool doesn't just happen to avoid talking to an MCP server, it
refuses to. A github.com/owner/repo link gets rewritten to the raw file
host before any of this runs, and fetchAllowedYaml refuses redirects
(redirect: 'error'), so the only URL the browser ever requests is the one
this check approved.

Updated 15 Sep: the page now refuses redirects. It used to re-check the final
URL after following them, which guards the response but not the request.
Thanks to @joinwell52 for the catch.

Try it

chrome://flags/#enable-webmcp-testing → enable → relaunch Chrome.
Open https://faf.one/webmcp (production needs HTTPS; localhost over plain HTTP works fine for local testing).
Install the Model Context Tool Inspector and open it on that tab.

Five things should be true:

[ ] Inspector lists score_faf, fill_6ws, emit_agents_md
[ ] score_faf on the loaded fixture returns a numeric score
[ ] Bad YAML returns { error, message } — not a thrown exception
[ ] The 6Ws form returns YAML and does not navigate the page
[ ] Network tab shows no call to any MCP server or /mcp URL —
    the only network activity is the one allowlisted YAML fetch

That last one is the actual claim of this piece, made checkable: nothing here
talks to a server. The tab did it.

What Part I asked, answered somewhere Part I didn't expect

Part I's problem was a client that can't see your AGENTS.md because it has
no way to walk to it. WebMCP's problem is stricter: there's no walking to
anything, ever — so the only way to expose context is to hand it over
directly, as tool calls, from wherever the process already lives. score_faf,
fill_6ws, emit_agents_md are one answer to that, running in the browser
because the browser is where this particular client already is.

The API that makes it possible isn't FAF's, and doesn't have to be. Register
whatever a page's own good judgment says an agent visiting it should be able
to call.

Series: Part I — Invisible AGENTS.md? · Part II — Publishing to the Registry · Part III — Horses for Courses · mcp-context-card.

Context Over MCP, Part III: Horses for Courses

wolfejam.dev — Sat, 12 Sep 2026 20:41:33 +0000

Part I: an MCP client has no working directory, so it never sees your
AGENTS.md.

Part II: publish the server to the registry so a client can find
it. Now it can — and this part is about what belongs in the context it finds.

Horses for courses. A flat race wants the fastest horse. A course with fences
wants one that knows how to jump. Two different horses, and you would not swap
them.

The flat racer: Markdown, for instructions

AGENTS.md is a flat racer. Prose, fast to write, expressive, carries
judgment: use SerializerV2 for new features; V1 is back-compat only. Setup,
Build, Test, Conventions, Guardrails — how you work in this repo. The context
card renders exactly this: sections a client can navigate, the operational
manual an agent acts on.

For that course, prose is the right horse. Nothing beats a paragraph for "here
is the nuance, here is the exception."

The course has fences: the facts

Open the card as a human and the manual is not what you want first. First you
want the portrait: what is this, who is it for, why does it exist, where does it
run. The six W's. The card does not show them, because AGENTS.md sections
are a checklist, not a description.

You could add an ## About section. People do:

## About

mcp-context-card is a TypeScript MCP server. It runs on Node 22+, builds with
tsc, has no database (memory is a file), and deploys as a stdio process or a
stateless Streamable HTTP service. CI runs on GitHub Actions across three OSes.

Every clause is a fact that already lives somewhere machine-readable —
package.json, tsconfig.json, the Dockerfile, ci.yml. It has been copied
into prose, and prose is where it goes to rot.

I found one of these while writing this article. mcp-context-card's own
AGENTS.md said "Node 22 or newer." Release 1.0.1 had lowered the engines
floor to >=20 — package.json moved, the README followed, the AGENTS.md
prose did not. An agent reads "Node 22+" at full confidence and tells a
contributor on Node 20 they are unsupported. Wrong, and the file was sure.

That is a fence. So are these: the facts feed more than one reader (the agent,
the card, a catalog); you want to know which of the six W's you have not
answered; two people edit the repo and the prose diverges. A flat racer piles
into the first fence.

This is separation of concerns — the oldest idea in the trade. One place for
each kind of thing.

The structured layer defines. AGENTS.md instructs.

The jumper: schema, for definitions

Facts want structure. Here is project.faf — YAML, one file at the repo root:

project:
  name: mcp-context-card
  main_language: TypeScript
  type: mcp
stack:
  runtime: Node.js
  build: TypeScript (tsc)
  api_type: MCP (JSON-RPC 2.0 — stdio + stateless Streamable HTTP)
  database: none            # memory is a file
  hosting: any Node host — stdio local, stateless HTTP remote
  cicd: GitHub Actions — typecheck + build + test on 3 OSes
human_context:
  who: MCP host and server implementers who want a project's context over MCP
  what: the essential context / memory / identity components for MCP
  why: AGENTS.md is the standard, but a client must know the file exists and read it whole
  where: github.com/Wolfe-Jam/mcp-context-card

Diffable. One source. Scoreable — a completeness check tells you which W's are
still blank. And it is still YAML: a human reads it fine. You are not trading
readability for structure — you get both.

The example here uses .faf. It is IANA-registered
(application/vnd.faf+yaml), it ships with the scorer, and it is what
mcp-context-card reads — so it is the instance throughout.

— or use yours. The pattern is format-agnostic: a package.json plus a
short PROJECT.yaml, a custom schema, whatever your toolchain already emits.
The horse for this course is any structured source. The point is facts as
data, kept apart from the instructions.

Both horses, one card

The card only ever reads AGENTS.md — never project.faf, on purpose. That is
what keeps it vendor-neutral. So the facts reach it the same way any good
manual gets its spec sheet: you derive that part.

npx faf-cli export --agents      # or the equivalent over MCP

human_context becomes a prose section at the top — the portrait. stack
becomes a facts block. Your hand-written conventions and guardrails stay exactly
where they were, outside the managed markers. Re-run it after a code change and
only the facts refresh.

Now the card shows the portrait and the manual, and neither drifts.

(Same "— or use yours": any tool that writes a facts section into AGENTS.md
from a structured source does this. agents-md-facts does the facts layer with
no project.faf at all.)

The loop

change the code
  → re-export         facts section refreshes · project.faf re-scores
  → the card updates  it just re-reads AGENTS.md

The manual stays true because you wrote it once and it rarely changes. The
portrait stays true because it is derived, not typed.

What this series is about

Prose for instructions, schema for facts — run the right one on each, and the
card shows both: the six W's a human reads first, the manual an agent acts on,
in one page, honest on their own.

Build the schema layer with .faf — or use yours. The point was never the
format. It's this: a client should be able to see your context, and your context
should be worth seeing.

Series: Part I — Invisible AGENTS.md? · Part II — Publishing to the Registry · Part IV — No Working Directory At All · mcp-context-card · the .faf format.

FastMCP 3 4 migration: the breaking changes that compile

wolfejam.dev — Mon, 07 Sep 2026 20:31:26 +0000

FastMCP 4 is GA. If you have an MCP server or client on fastmcp 3.x, you'll
upgrade soon. Most of it is painless — FastMCP(...), @mcp.tool, and
mcp.run(transport=...) are all unchanged. The parts that aren't painless are the
parts that don't announce themselves.

These are field notes on top of the official
Upgrading from FastMCP 3
guide — the items that bit hardest when I moved one MCP server and two clients,
in the order they bit.

1. `pip install -U fastmcp` can leave you half-broken

FastMCP 4 is split into extras. The fastmcp package is now a thin meta-package
that depends on fastmcp-slim[client,server]; fastmcp-slim carries the actual
code, and its extras are client, server, mcp, anthropic, apps, azure,
code-mode, gemini, openai.

On a fresh install this is invisible — pip install fastmcp pulls
fastmcp-slim[client,server] and everything works.

I upgraded in place with pip install -U fastmcp over fastmcp 3.2.x, and pip
did not re-resolve those base extras. Result: an importable shell with nothing in
it.

>>> import fastmcp
>>> fastmcp.__file__ is None
True
>>> dir(fastmcp)
[]
>>> from fastmcp import Client
ImportError: cannot import name 'Client' from 'fastmcp' (unknown location)

This looks exactly like a broken release. It isn't — it's the 4.x extras split not
getting re-resolved on an in-place upgrade. (FastMCP separately documents a
different pip file-manifest issue on the 3.2 → 3.3 hop and notes uv is
unaffected by that one; this is a distinct problem, and I hit it with pip -U —
I didn't test uv pip install -U.)

The fix, either way:

python -m pip uninstall -y fastmcp fastmcp-slim
python -m pip install fastmcp   # or fastmcp==4.0.x to pin the version you tested

Or just recreate the venv. It cost me a false-alarm debugging session — twice,
because the symptom (ModuleNotFoundError on a submodule that's genuinely in the
wheel) is so convincing.

Also: fastmcp in 4.x no longer exposes __version__. If you assert on it
anywhere, switch to importlib.metadata.version("fastmcp").

2. `httpx` → `httpx2`: your `except` clauses go quiet

FastMCP 4 dropped httpx for httpx2 (a next-gen fork) internally. So a FastMCP
client call that used to raise httpx.ConnectError now raises
httpx2.ConnectError.

The trap: httpx is still transitively installed in most environments, so this
keeps importing and type-checking:

try:
    async with Client(StreamableHttpTransport(url)) as c:
        result = await c.call_tool("do_thing", args)
except httpx.ConnectError:   # never matches on FastMCP 4
    ...

It just silently stops catching. Grep for except httpx. and check whether each
one wraps a FastMCP Client / transport call — if it does, migrate it to
httpx2 (or catch FastMCP's own fastmcp.exceptions.ToolError, which is usually
what you actually want). Your own direct httpx calls are unaffected as long as
you keep httpx as a dependency.

Same silent class, elsewhere: anything you hand into FastMCP that's built on
httpx — a custom httpx_client_factory, an httpx.AsyncClient passed to a
transport, an httpx.Auth — now needs to be httpx2. The official guide lists
this right next to the except trap.

One more downstream effect: TLS verification now uses the OS trust store via
truststore (honouring SSL_CERT_FILE / SSL_CERT_DIR) instead of bundled
certifi — corporate-CA setups may verify differently. HTTP log records also move
from httpx / httpcore.* to httpx2 / httpcore2.* — update logging filters.

3. `Client` now defaults to `mode="auto"`

In 4.x, Client(...) defaults to mode="auto" and negotiates the modern
2026-07-28 protocol era. That era is sessionless, and it changes runtime
behaviour even though your code compiles fine:

No on_initialize handshake — middleware / init hooks tied to it never run.
ctx.set_state() doesn't persist to the next call.
ctx.elicit() raises — the modern era has no server-initiated back-channel.

If your client only does plain reads and writes (call_tool, read_resource),
you're fine — that's the common case and it needs no change. If it relies on
session state, an init hook, or elicitation, pin it back:

Client(server, mode="legacy")

StreamableHttpTransport also dropped sse_read_timeout= — pass timeout= on the
Client instead.

4. Removed `ctx` methods

These are gone and raise AttributeError:

ctx.sample()
ctx.sample_step()
ctx.list_roots()

If your server's job was to borrow the caller's model via ctx.sample() (or
FastMCP(sampling_handler=...), also removed), you either call an LLM directly
from the server now or stay on 3.x. ctx.elicit() still exists but requires a
response_type argument and raises on modern connections — rewrite it as a guard
tool that returns an "input required" result, or branch on
ctx.request_context.protocol_version.

Background tasks moved to an extension. @mcp.tool(task=True) no longer runs
anything by itself — install fastmcp[tasks] and register
mcp.add_extension(TasksExtension()), or startup raises. Drop task= from
@mcp.resource / @mcp.prompt (tools only).

5. Version floors

# hard requirement — resolution fails without it
pydantic = ">=2.12"

# only if you use the server's FastAPI extra
starlette = ">=1.0.1"    # → FastAPI >= 0.133.0 (first version admitting Starlette 1.x)

Pin style unchanged: an app pins the exact version it tested
(fastmcp==4.0.x); a library floors at fastmcp>=4.0.0 in its own
dependencies and tests against the current release.

6. Import moves (quick reference)

3.x	4.x
`from fastmcp.tools.tool import Tool, ToolResult`	`from fastmcp.tools import Tool, ToolResult`
`from fastmcp.resources.resource import Resource`	`from fastmcp.resources import Resource`
`TextContent`, `Tool` protocol types from `fastmcp.types`	`from mcp.types import ...` (`fastmcp.types` now holds only FastMCP-defined types)
`mcp.as_proxy(sub)`	`create_proxy(sub)` from `fastmcp.server`
`mcp.import_server(sub)`	`mcp.mount(sub)` (live composition, not a snapshot)
`mcp.add_tool_transformation(name, cfg)`	`mcp.add_transform(ToolTransform({name: cfg}))`
`CachableToolResult` (old typo)	`CacheableToolResult` — no compat alias
`McpError(ErrorData(code=..., message=...))`	`McpError(code=..., message=...)`

SDK v2 also renamed model fields camelCase → snake_case (inputSchema →
input_schema, isError → is_error). Old reads are auto-bridged and emit a
FastMCPDeprecationWarning. The bridge is
fastmcp.settings.mcp_camelcase_compat (env FASTMCP_MCP_CAMELCASE_COMPAT),
bool, default true. Set it false once — that turns every remaining camelCase
read into a hard error, so you can find and clear them before the bridge is
removed.

7. New defaults from the settings page

gofastmcp.com/more/settings lists every
setting — each has a fastmcp.settings.<name> attribute and a FASTMCP_<NAME>
environment variable. Three defaults changed behaviour in 4.x and don't get a
line in the upgrade guide:

telemetry_mode defaults to "native" — FastMCP 4 auto-instruments OpenTelemetry spans for MCP calls. If you don't want that, FASTMCP_TELEMETRY_MODE=off (or propagation_only).
check_for_updates defaults to "stable" — the CLI checks PyPI for a newer FastMCP on startup. Set FASTMCP_CHECK_FOR_UPDATES=off in CI and containers.
client_raise_first_exceptiongroup_error defaults to true — a client error surfaces as the first underlying exception, not the ExceptionGroup. That's why except ToolError: still works; if you were catching with except*, revisit.

Also worth a look while you're there: stateless_http (new-transport-per-request,
the sessionless/Cloud-Run knob), http_host_origin_protection (new, opt-in Host/
Origin validation for Streamable HTTP), and mask_error_details (default false
— error text is passed through unless you raise an explicit ToolError /
ResourceError / PromptError).

Keep FASTMCP_DEPRECATION_WARNINGS=true (the default) for the whole migration —
it's how you find the rest of this list in your own code.

The good news: the minimal server barely changes

If your server is only @mcp.tool-decorated functions plus
mcp.run(transport="stdio") or mcp.run(transport="streamable-http"), there is
no code change. The constructor, the decorator, and the transport call are all
the same. You:

bump pydantic (and FastAPI, if you use it),
grep for except httpx. and migrate the ones around FastMCP calls,
run your tests.

That's it.

What I actually changed

Shape	Change
An MCP server — `@mcp.tool` + `mcp.run("stdio" / "streamable-http")`	dependency floor only — zero code
Two MCP clients — `Client` + `StreamableHttpTransport` + `except ToolError`	dependency floor only — verified `mode="auto"` is fine for plain reads / writes

No API changes in either. The real cost was the pip install -U false alarm
(twice) and one test that hard-coded a version string in an assertion.

The checklist

[ ] Recreate the venv (or `pip3 uninstall fastmcp fastmcp-slim` first) — don't `-U` over 3.x
[ ] pydantic >= 2.12   (+ FastAPI >= 0.133.0 if you use the server's FastAPI extra)
[ ] grep `except httpx.` — migrate the ones wrapping FastMCP Client/transport calls to httpx2
[ ] grep `httpx_client_factory` / `httpx.AsyncClient` / `httpx.Auth` handed to FastMCP — same, → httpx2
[ ] grep `ctx.sample` / `ctx.sample_step` / `ctx.list_roots` — removed (and `FastMCP(sampling_handler=)`)
[ ] grep `ctx.elicit` — needs response_type + fails on modern connections
[ ] grep `@mcp.tool(task=True)` — now needs fastmcp[tasks] + TasksExtension()
[ ] grep `Client(` — needs mode="legacy" only if it relies on session state / on_initialize / elicit
[ ] grep `sse_read_timeout` — moved to Client(timeout=...)
[ ] grep imports: fastmcp.tools.tool, fastmcp.resources.resource, fastmcp.types, mcp.as_proxy, import_server
[ ] grep `fastmcp.__version__` — gone; use importlib.metadata.version("fastmcp")
[ ] set `fastmcp.settings.mcp_camelcase_compat = False` once — clear the camelCase deprecation warnings
[ ] CI: `FASTMCP_CHECK_FOR_UPDATES=off`; decide on `FASTMCP_TELEMETRY_MODE` (default is `native` = OTel on)
[ ] keep `FASTMCP_DEPRECATION_WARNINGS=true` (default) for the whole migration
[ ] run the test suite

If you're just @mcp.tool + mcp.run, the whole list is "bump two floors and
check your httpx catches." Everything else is for the code that does more.

React, Next.js, Svelte, Zod: none of them can tell AI who they're actually for

wolfejam.dev — Wed, 02 Sep 2026 15:40:01 +0000

Your coding agent is good at reading code.

Point Claude Code or Cursor at a repo
and it will figure out the language, the framework, the build command — it just costs you tokens and a few tool calls every session to re-derive what it forgot.

What it can't read is the part that isn't in the code: who the project is for,and why it exists. So it guesses. Confidently, in the same tone it uses for the facts it actually verified.

I wanted to see how big that gap is on real projects, so I ran a mechanical context extractor over eight of the most-loved repos in the JavaScript world.

The method

faf git <url> clones a repo and fills in a small typed context file (project.faf) from what it can find — README, package.json, project structure, config. No hand-authoring, no LLM writing prose. It fills what's there and leaves the rest blank. Nine-ish slots: the identity (name, goal, language) and the six W's — who, what, why, where, when, how.

Run it yourself: npx faf-cli git https://github.com/facebook/react

The result

repo	extracted	`who`	`why`
facebook/react	56%	— blank —	— blank —
vercel/next.js	44%	— blank —	— blank —
expressjs/express	50%	— blank —	— blank —
colinhacks/zod	67%	— blank —	— blank —
sveltejs/svelte	88%	— blank —	— blank —
prettier/prettier	75%	— blank —	— blank —

Eight repos in total (React, Next.js, Express, Zod, Hono, Svelte, Vue, Prettier). Every one of them: who is this for and why does this exist came back empty. Not one has that written anywhere a machine — or an agent at task time — can read it.

Svelte scored 88%. The who and why are still blank. This isn't a documentation-quality problem, and it's not a knock on any of these projects. The stack lives in the files. The intent lives in maintainers' heads, design docs, old RFC threads, and Discord history — none of which your agent has open when it's editing a file.

Why the two halves behave differently

The scores range from 44% to 88%, and that whole spread is one thing: how much stack the repo exposes in config files. Svelte's monorepo setup fills seven stack slots (framework, runtime, build, CI…) and lands at 88%. React's root exposes one, and lands at 56%. More config → higher score.

So the recoverable half — language, framework, build — varies 2× across these repos. A cold agent can dig all of it out; you just pay for the dig, every session, in tokens and latency.

The unrecoverable half doesn't vary at all. who and why came back empty in every one of the eight, regardless of repo size, fame, or documentation.
No amount of spelunking through src/ tells you that a library was built to replace one specific painful pattern, or that it targets library authors and not app developers, or that an architectural choice you're about to "clean up" was deliberate. That information was never committed in a form the agent can consume.

So the agent fills the blank with a plausible story. On React it'll probably land close. On your internal service, or a library with a subtle audience, it won't — and it'll refactor accordingly, with confidence.

The fix is about ten minutes

faf go walks a maintainer through the six questions once, writes the answers into project.faf, and you commit it. From then on every agent — Claude Code, Cursor, Codex — reads the same authored context instead of guessing, and it's one file that projects out to CLAUDE.md, AGENTS.md, .cursor/rules/ so
those can't drift apart.

faf-cli's own project.faf looked much like these until someone sat down and filled it in. React's team could close their gap in a single commit.

(The first project.faf I ever wrote was for a Svelte app — which makes it a little funny that sveltejs/svelte topped this table at 88% and still can't tell an agent who Svelte is for.)

If you want the number

Fill the gaps first with faf go, then faf bench measures the delta directly: it asks a model the questions about your repo cold, then again after reading project.faf, and grades the answers mechanically (no LLM judge). Questions are derived from the populated slots — the .faf is the answer key — so a repo that still has who/why blank can't be graded on them; that's what faf gois for. The delta is the accuracy your agent is leaving on the table, and where the cold misses cluster tells you which parts of your project only exist in your head.

npx faf-cli go                     # fill project.faf (the ten minutes)
npx faf-cli bench questions        # the questions, derived from your repo
npx faf-cli bench grade answers.json --cold
npx faf-cli bench grade answers.json --faf

A low cold score isn't a verdict on the model. It's a diagnosis that the project is under-described for an agent to work in — and the output ends in faf go, not a leaderboard.

Notes: faf git's percentage reflects how much is in the repo, so a high score means good docs, not a good tool — and the who/why blanks are honest, the information genuinely isn't there to extract. project.faf is one typed source (the .faf format is an IANA-registered media type,application/vnd.faf+yaml) that the per-tool context files are generated from, rather than another markdown file to maintain by hand.

Your tools/list is stamped. That is not the same as cached.

wolfejam.dev — Thu, 20 Aug 2026 11:00:00 +0000

A stamp on tools/list is a claim about later reuse. Presence is not proof the next call is cacheable.

TL;DR — The 7/28 spec put ttlMs and cacheScope on tools/list. Most write-ups treat that stamp as a cache. It is a claim about later reuse. Presence means the server said something. Truth needs an observation that can fail. We shipped a liar and a probe. The catalog grew. The probe still said OK. The stamp half was along for the ride. One mutant per clause. Name which negatives are still live.

The victory lap

The 2026-07-28 spec added list-cache stamps (SEP-2549), modeled on HTTP Cache-Control. The official sentence is some version of: clients know exactly how long tools/list is fresh.

That sentence is doing a lot of work.

HTTP already taught this. Cache-Control: max-age=60 is a statement. It is not proof the next GET returns the same bytes. MCP imported the words. It did not import a test.

A server can print ttlMs: 60000, cacheScope: Public and change its catalog on the next call. The stamp is still well-formed. A probe that only checks presence will still pass.

We built a liar. Then the lie got lazy.

Last piece: a labeled companion, mcp-worse, and one command — contrast-smoke — that passes only if the good server meets the BETTER list contract and the bad one fails it.

The checker looked like this:

fn is_lying_surface(p: &ListProbe) -> bool {
    let unstamped = p.ttl_ms.is_none() || p.cache_scope.is_none();
    let wrong_order = p.names != better_names();
    unstamped || wrong_order
}

That OR is the hole.

mcp-better grew a third tool, confirm_echo. mcp-worse still lists two: echo, health. So wrong_order (really: names ≠ the good catalog) is always true. The stamp half stopped carrying observable weight.

If worse grew with_ttl_ms and with_cache_scope tomorrow, the example would still print OK. It would fail for contents only. The negative case for ttlMs would be gone, and nothing would say so.

The “companion must stay a reliable liar” guard only fires when every clause goes green at once. Partial decay is invisible.

A comment on that post named it. They were right.

A liar that fails for two reasons is weaker evidence than two liars that each fail for one. Steal-the-pattern already said: one smallest lie per claim. We had one binary that violated every clause, and an OR that hid which ones were still live.

Presence is not truth

Order is a property of the list the probe is holding. You can see it.

ttlMs and cacheScope are statements about how that list may be reused later. Confirming the fields exist and look well-formed proves the server made a claim. It does not prove a client would be right to skip the next tools/list.

order-restart-smoke does the right thing for order: two processes, same names. It applies that shape to TTL as ttl_a == ttl_b — the stamp is restart-stable. That is a property of the number, not of the caching behavior the number describes.

Falsifying a TTL claim takes an observation pair that straddles a change. Our catalog is compiled in. The TTL claim cannot be violated yet. Declared, not falsified. Once the catalog goes dynamic, ttlMs is the first stamp with room to lie — and it is the clause with the least behind it.

This lab reads this list. Not the next call. Not a client cache.

Run the audit

The probe now requires each teaching clause on the companion. Stamp decay fails closed and names the clause.

// examples/contrast_smoke.rs — current tree
fn is_unstamped(p: &ListProbe) -> bool {
    p.ttl_ms.is_none() || p.cache_scope.is_none()
}

fn wrong_names(p: &ListProbe) -> bool {
    p.names != better_names()
}

Both must stay true on mcp-worse. If either goes green, the example exits non-zero and says which.

Step 1 — Clone and build both binaries

git clone https://github.com/Wolfe-Jam/mcp-better.git
cd mcp-better
cargo build --bins

This is the tree, not cargo install mcp-better. The published v0.5.0 tag still has the OR. The named-clause OK line is the honesty cut on current main.

Step 2 — Run contrast-smoke

cargo run --example contrast-smoke

Expect (captured 2026-08-19, current tree):

better names=["health", "echo", "confirm_echo"] ttl=Some(60000) scope=Some(Public)
worse  names=["echo", "health"]                 ttl=None        scope=None
contrast-smoke: OK (better contract · worse unstamped · worse names≠health,echo,confirm_echo)

The OK line is the point. It names which negatives are still live.

Step 3 — What you just proved

Claim	Evidence	Not proved
Good list is ordered + stamped	Wire: three names, `ttlMs > 0`, `cacheScope == Public`	That a client should cache it
Companion stays unstamped	`unstamped` asserted, not `OR`-ed away	Cache behavior
Companion catalog ≠ better	`names ≠ health,echo,confirm_echo` (today: two tools, reversed)	That “wrong names” is only order
Partial decay is visible	Stamp clause going green fails the example	A second mutant (stamped-but-reversed)

That last empty cell is honest. One companion that fails for two reasons is still weaker than two mutants that each fail for one. This cut makes the live negatives named. It does not ship a second dummy.

What this is not

Not a cache test. No observation pair straddling a change. The catalog is compiled in.
Not a rewrite of the last post. That one built the liar. This one asks what the probe actually falsified.
Not a version diary. No new tool. No new crate.
Not “every BETTER server must implement a mutant factory.”
Not a security scanner.

Steal the pattern

Same shape as last time — finish the last step:

Write down every claim the docs make about the wire.
For each claim, the smallest change that would make it false.
One mutant per claim — or, at minimum, assert each clause so one leftover violation cannot hide another.
Print which negatives are still live. An OK line that does not name them is an OR in disguise.
If the claim is about later reuse (ttlMs, cacheScope), a presence check is “a claim was made.” Do not call it verified until something can fail.

If you cannot say which clause is still live, you do not have a negative case. You have a dummy that is wrong in a pile.

Close

A README cannot lie to a test that reads the wire. A stamp can still lie to a README.

ttlMs on the list is a reuse claim. contrast-smoke now says which teaching clauses are still live. That is the list. Not the cache.

Claim = wire. Ask what you actually falsified.

Which clause on your tools/list is only present — not proven?

I'm an AAIF Ambassador. This piece is public MCP education — the kind of practical path the program exists for.

"Never guessed" isn't the same as "never misses."

wolfejam.dev — Thu, 20 Aug 2026 00:27:17 +0000

TL;DR — I built a tool that authors AGENTS.md from real repo facts, never invented ones. A month after it was scored as a real AAIF contribution: 29 downloads, 2 stars, 0 issues. Nobody stress-tested it, so I did — against two repos I'd already dug into by hand. Every line it wrote was true. It still missed the most important test in both of them, for the same structural reason, twice.

The honest starting number

agents-md-facts authors a minimal AGENTS.md from what your repo actually declares — real build commands, real test commands, real file layout. Nothing guessed. It was submitted to AAIF as a project contribution and scored accordingly.

A month later: 29 npm downloads, 2 GitHub stars, 0 issues, 0 forks. Five commits since launch, all docs and housekeeping — nobody used it hard enough to find something to fix.

That's not a failure post. It's the honest premise for this one: if nobody else was going to stress-test it, I would.

Dogfooding it for real

I ran it, --dry-run, against two repos I already understood deeply — not blind spots, ground truth I could check the output against. One Rust, one TypeScript.

$ cd mcp-better && npx agents-md-facts --dry-run

## Run the tests

```bash
cargo test
cargo clippy
```

## Definition of Done

Done when: `cargo clippy` exits 0 · `cargo test` passes · committed with a clear message.

$ cd claude-faf-mcp && npx agents-md-facts --dry-run

## Run the tests

```bash
npm run test
npm run lint
```

## Definition of Done

Done when: `npm run lint` exits 0 · `npm run test` passes · committed with a clear message.

What it got right

Every single line in both outputs traces to something real. cargo test and cargo clippy genuinely exist and genuinely run in mcp-better. npm run test and npm run lint genuinely exist and genuinely run in claude-faf-mcp. Zero invented commands, either time. The tool's actual promise — never guessed — held completely, both times, under real conditions.

What it missed — twice, same shape

mcp-better ships a tool called confirm_echo with a real multi-round contract: a sealed, tamper-checked handshake. The unit tests for it live in src/server.rs and run fine under cargo test. But the contract — does the tool still promise what it promised, over the wire, to a real client — is checked by a completely separate command:

$ cargo test --all-targets
   Running unittests examples/mrtr_client.rs
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored

cargo test compiles that file. It runs zero test functions in it. The actual check only happens if you separately run cargo run --example mrtr-client — which is exactly the command the generated AGENTS.md never mentions, because "Definition of Done: cargo test passes" is what the tool detected, and that line is true. It's just not the whole truth.

claude-faf-mcp has the same shape from a different angle. The generated file correctly points at npm run test. Sitting in the same tests/ directory, untouched by the generated output: WJTTC-FAFM-MEMORY.md, WJTTC-MCP-CLI-CONTINUITY-v274.md, WJTTC-REPORT-MCP-v120-STRESS-TEST.md — a separate certification layer the tool has no way to surface, for the same reason: it doesn't look like npm run test, so there's nothing for a facts-detector to grab onto.

Two different stacks. Same blind spot, in the same place: the deepest verification layer in each repo is precisely the one that doesn't look like every other repo's test command.

Why — and it isn't a bug

"Never guessed" means the tool only writes down things it can detect. That's the entire safety property, and it's a real one — it's the whole reason this class of tool doesn't fall into the auto-generated-bloat trap the research on AI-written instruction files warns about. But detection has a shape. The tool knows what cargo test and npm run test look like. It has no way to know that cargo run --example mrtr-client or a hand-written stress report also answers "is this thing actually verified" — because those don't match any pattern it's built to recognize.

"Real fact" and "fact my detector recognizes" are not the same set. The gap between them is exactly where the most important line in an AGENTS.md can go missing, silently, while every other line stays true.

What this means beyond this one tool

Any facts-based generator — this one or the next one — inherits the same limit. A generated AGENTS.md is a floor, not a ceiling: provably not-wrong, because every line traces to something real, which is not the same claim as complete. And the layer most likely to be missing is usually the one that matters most, because a repo's deepest verification is often exactly the thing that was built custom, in a shape nothing else in that codebase uses — which is precisely what a pattern-matcher is worst at finding.

What I'm changing because of this

The fact-sourcing discipline underneath all of this — every line traces to a fact, verify it stays true in the same PR it changed — is still the right foundation. It just isn't sufficient alone, and pretending otherwise would be exactly the kind of overclaim this series has spent five parts arguing against.

The honest addition is one more pass, after the tool runs, human or agent: does this repo have a second, differently-shaped verification layer the tool wouldn't have found? That's the question that surfaced mrtr-client and the WJTTC reports here. It's not automatable yet. Naming it is the first step toward making it so.

Help guide what we build — comments and suggestions welcome.

"I built a lying MCP server on purpose — here's how you catch it"

wolfejam.dev — Mon, 17 Aug 2026 05:06:18 +0000

TL;DR — A server's README can say anything. Its tools/list response either backs that up or it doesn't.

I built mcp-worse — a second binary, sharing two of mcp-better's tool names, that deliberately omits the list-cache stamps and serves tools in the wrong order — so a test could prove the difference. That test is contrast-smoke: one command, real MCP clients, real wire traffic. Exit code 0 only if the good server passes the contract and the bad one fails it.

This is what "claim = wire" looks like when you stop saying it and start shipping it.

The problem with trusting a README

Every MCP server's docs make claims: stateless, cacheable list, stable tool order. Nothing in the protocol stops a server from claiming all three and doing none of them. The client can't tell from the tool names — health and echo look identical whether the server behind them is honest or not.

So the question isn't "does this server have a tools/list endpoint." It's: if the docs are wrong, what breaks, and when?

Most servers never answer that, because nothing is built to fail on purpose. You only find out a claim was false in production, from a client that behaved unpredictably against a server that "worked" in every manual check.

Build the lie on purpose

The cleanest way to test a contract-checker is to hand it something that violates the contract — not a hypothetical, a real binary.

mcp-worse is that binary. Same protocol version on the wire, same transport, and it mirrors two of mcp-better's tools by name (health, echo) — mcp-better has since grown a third (confirm_echo, an MRTR retry-flow demo) that the lying companion was never updated to match, so the tool count alone is now part of the gap too, alongside two deliberate breaks:

// src/worse.rs
/// Intentional anti-order (BETTER is health → echo).
const WORSE_TOOL_ORDER: &[&str] = &["echo", "health"];

/// Unstamped list with reversed order — the lie.
pub fn lying_list_tools(&self) -> ListToolsResult {
    let mut tools = self.tool_router.list_all();
    tools.sort_by(/* ...WORSE_TOOL_ORDER... */);
    // Deliberately omit with_ttl_ms / with_cache_scope.
    ListToolsResult::with_all_items(tools)
}

No ttlMs. No cacheScope. Tools reversed. The health tool result even says so out loud:

{
  "status": "ok",
  "server": "mcp-worse",
  "version": "0.4.3",
  "protocol": "2026-07-28",
  "tier": "LYING-DEMO",
  "warning": "This binary deliberately fails the BETTER list contract for teaching."
}

It's not a trick client would fall for in the wild — it's labeled, it's teaching-only, it never ships to a registry. Its only job is to be wrong on purpose, reliably, so something else can prove it catches a lie.

Run the audit

contrast-smoke spawns both binaries as actual child processes, talks real MCP over stdio, and checks the wire — not the source, not the docs:

// examples/contrast_smoke.rs
fn is_better_contract(p: &ListProbe) -> bool {
    p.names == better_names()
        && matches!(p.ttl_ms, Some(ms) if ms > 0)
        && p.cache_scope == Some(CacheScope::Public)
}

fn is_lying_surface(p: &ListProbe) -> bool {
    let unstamped = p.ttl_ms.is_none() || p.cache_scope.is_none();
    let wrong_order = p.names != better_names();
    unstamped || wrong_order
}

Step 1 — Clone and build both binaries

git clone https://github.com/Wolfe-Jam/mcp-better.git
cd mcp-better
cargo build --bins

This builds mcp-better and mcp-worse side by side — contrast-smoke needs both on disk to probe them.

Step 2 — Run contrast-smoke

cargo run --example contrast-smoke

Expect (real output, captured 2026-08-16 against v0.4.3):

better names=["health", "echo", "confirm_echo"] ttl=Some(60000) scope=Some(Public)
worse  names=["echo", "health"]                 ttl=None        scope=None
contrast-smoke: OK (mcp-better passes BETTER list contract · mcp-worse fails it)

Read those two lines side by side — that's the whole post in two rows of text. Same protocol, same transport, one server stamps and orders its list, the other doesn't, and now there's a command that says so instead of a paragraph that claims so.

If mcp-better ever regresses — someone drops the ttlMs stamp in a refactor, tool order stops being deterministic — this fails loudly, on the good server, using the exact same probe that already knows what "bad" looks like. And if mcp-worse ever accidentally started passing the contract, that fails too (the companion has to stay a reliable liar or the test is worthless).

Step 3 — What you just proved

Claim	Evidence
`mcp-better`'s list is cache-stamped	`ttlMs > 0`, `cacheScope == Public`, read off the wire
Tool order is a real contract, not incidental	`mcp-worse` reversing it is what makes the test fail
The checker isn't fooled by names	`mcp-worse` shares two tool names with `mcp-better` (`health`, `echo`); wrong order and missing stamps fail it regardless — no name-matching heuristic to fool
The contract has a negative case	Not just "good passes" — "bad provably fails," same probe

That last row is the actual point. A test suite that only ever runs against the happy path proves the happy path exists. It doesn't prove the checker works — that it would catch a violation if one showed up. mcp-worse exists so contrast-smoke has something real to fail against, once, in CI, forever.

What this is not

Not a security scanner — it doesn't check auth, injection, or prompt-level trust. It checks one specific, common claim: does the list response match what the docs say about caching and order.
Not a general-purpose MCP fuzzer. Two tools, one contract, on purpose — small enough to read in five minutes.
Not a product. mcp-worse never ships to the MCP Registry. It exists in the same repo as mcp-better, for the same reason a crash-test dummy exists next to the car.
Not "MCP servers are untrustworthy." Most aren't audited this way yet — that's the gap this pattern closes, not an indictment.

Steal the pattern

You don't need mcp-worse specifically. You need the shape:

Write down every claim your server's docs make about its wire behavior (cache hints, ordering, transport headers — whatever you promise).
For each claim, ask: what's the smallest change that would make it false?
Build that — deliberately, once, labeled as a teaching/test fixture, never shipped as a product.
Write one probe that checks both your real server and the broken companion, and asserts they land on opposite sides of every claim.

If you can't build the broken version, you don't know what your claim depends on.

Close

A README can't lie to a test that spawns the real process and reads the real wire. mcp-worse isn't clever — two constants and a missing function call are enough. That's the whole lesson: the gap between "claims to be BETTER" and "is BETTER" is usually that small, and invisible until something is built to fail on it.

Claim = wire. Build the broken version. Ship the probe that fails on it.

What's the smallest claim your own server makes that you've never tested?

I'm an AAIF Ambassador. This piece is public MCP education — the kind of practical path the program exists for.

Not all MCP servers are equal — what 7/28 just made official

wolfejam.dev — Fri, 31 Jul 2026 06:34:03 +0000

TL;DR — 7/28 (wire: 2026-07-28) is the modern MCP release. The big deal is STATELESS: no protocol session, request/response core, Discover, stamped lists, Streamable HTTP routing headers. A server can expose health on three hosts and still be three different machines operationally. This post is the GOOD → BETTER map, plus a runnable textbook you can install in minutes.

MCP lives under the Agentic AI Foundation / Linux Foundation. Spec: modelcontextprotocol.io/specification/2026-07-28. Claude-side rollout note: Bringing MCP 2026-07-28 to Claude (2026-07-28). Ship note: faf.one/blog/mcp-better.

Same name, different machine

InterOp is not “does tools/list return a string called echo?”

InterOp is: does this server behave like a 7/28 peer under a modern client?

Question	Why it bites
Does the client use Discover, or only legacy `initialize`?	Handshake-as-identity is GOOD-era. 7/28 is request/response + `server/discover`.
Does `tools/list` return `ttlMs` + `cacheScope`?	List cache is part of the modern contract — not optional polish for BETTER claims.
Is tool order stable?	Prompt-cache and client caching assume determinism.
On HTTP: are `Mcp-Method` / `Mcp-Name` present?	Routing without body parse — required on Streamable HTTP POSTs.
Does the server invent session stickiness as identity?	Protocol sessions are gone. App state = explicit handles if anything.

If two servers both advertise echo but only one answers those questions honestly, they are not interchangeable. Host A “works.” Host B “flakes.” The tool name stayed the same. The operational surface did not.

GOOD habits (pre-7/28 muscle memory)

None of this is “you’re bad.” It was the world the old samples taught.

Habit	What it looked like
Session as identity	Sticky `Mcp-Session-Id`, “connected” means long-lived peer
Handshake as the event	`initialize` / `initialized` as the main lifecycle story
Unstamped lists	`tools/list` works, but no cache hints — clients re-poll forever
Host-lucky InterOp	Works in one Desktop config; mystery failure in another
Banner claims	README says “modern MCP”; wire is still 2024-shaped

Call that GOOD: real MCP, real tools, real value — with session-era operational assumptions.

BETTER after 7/28 (checklist you can audit)

Humans say 7/28. Machines negotiate 2026-07-28. The big deal is STATELESS.

BETTER check	Spec-shaped meaning
Stateless core	No protocol session; any request can hit any healthy instance (HTTP)
Discover	Clients prefer Discover / Auto → 7/28; servers answer discover correctly
Self-describing traffic	Version + capabilities travel with the request (`_meta` / headers)
Stamped lists	Positive `ttlMs`, intentional `cacheScope` (`public` for static catalogs)
Stable tool order	Same process, same order across N list calls
HTTP road (if claimed)	Streamable HTTP + `Mcp-Method` / `Mcp-Name`; no fake “we’re remote-prod” without auth
Honest claim surface	Docs + CI prove what you claim; no deprecated Roots/Sampling/protocol Logging as greenfield features
MRTR / Tasks / OAuth	Real, but not required to be a BETTER tools textbook on day one — document later if you go deep

BETTER is not “more tools.” BETTER is claim = wire.

If MCP had an AGENTS.md

One box. Steal it for every server README you touch:

## Operational contract (7/28)
- Protocol: 2026-07-28
- Lifecycle: Discover-compatible (not initialize-only)
- tools/list: ttlMs + cacheScope + stable order
- Transports: stdio (default) · Streamable HTTP (if enabled — document bind + auth posture)
- Non-goals: (resources / OAuth / Tasks — say so if out of scope)
- Prove it: (link CI / smoke that fails when you lie)

Short. Specific. Actionable. Same discipline as a good AGENTS.md — facts the peer can verify, not vibes.

10-minute textbook: `mcp-better`

mcp-better is a small Rust server built for this era — not a product platform. Two tools: health, echo. Official rmcp 3. Discover-compatible. Stamped list. v0.1 = 7/28 over stdio. v0.2 = same era + opt-in Streamable HTTP (local demo).

On crates.io and the MCP Registry as io.github.Wolfe-Jam/mcp-better.

Step 1 — Install

cargo install mcp-better --version 0.2.0
mcp-better --help

First install compiles Rust deps once — one-time wait; then you’re done.

Step 2 — Run stdio (default)

mcp-better

Point a Discover-capable client / smoke at it. Or from the repo:

git clone https://github.com/Wolfe-Jam/mcp-better.git
cd mcp-better
cargo build --bins
cargo run --example stdio-client

Expect: negotiated 2026-07-28, list stamps (ttlMs / cacheScope), tools in stable order: health, then echo.

Step 3 — Optional HTTP road (same era)

mcp-better --http
# http://127.0.0.1:8787/mcp

Local demo only — no auth/TLS (see the repo SECURITY.md). From source, http-smoke exercises list + health + echo with Mcp-Method / Mcp-Name.

Step 4 — What you just proved

Claim	Evidence
Built for 7/28	Discover path + era string
List cache	Positive `ttlMs`, `public` scope for a static catalog
Dual transport	stdio default · HTTP opt-in — not a second protocol “version”
Small surface	Two tools — enough to teach the contract

That’s the point of a textbook: copy the operational contract, not a 40-tool megaserver.

What this is not

Not a tour of every SEP.
Not “everyone has migrated.” Hosts and SDKs roll out on their clocks (Claude products are rolling 7/28 support — see Anthropic’s post).
Not a connector-directory pitch. Open Registry + honest wire still matter when app-store shelves optimize for other shapes.
Not a product install funnel. One runnable example. One checklist.

Close

7/28 is hot for a reason. The big deal is STATELESS — Discover, stamped lists, and honest HTTP headers are how the wire enforces that.

If you only remember one line: same tool name ≠ same operational server. Audit the contract. Ship the smoke. Prefer BETTER over banner.

I’m an AAIF Ambassador. This piece is public MCP education — the kind of practical path the program exists for. Questions welcome.

DEV Community: wolfejam.dev

Context Over MCP, Part VI: Context You Can See

Try it: the goose way

Try it: the terminal way

What the card shows, and why it helps

An empty project is a starting point

In other hosts

Keep it true, with you in the loop

How it works, for builders

Check it yourself

Context Over MCP: Part V The Form Is the Tool.

Step 1 — start with a form that already works

Step 2 — add three attributes, and it's a tool

Step 3 — answer the agent, not just the screen

Step 4 — decide who presses Submit

Step 5 — the fields that should never become parameters

The whole page

Step 6 — verify it before you add anything else

The same shape, in production

"Pack of Cards: five agent-card specs, drawn as one map"

In Plain English

First, the one that is not a card

Then the cards

How to read it

What it shows

How it's built

Some interesting facts

Three ways to name a card

What it cost us to keep up

Five, out of thirty-six

Get your pack

Context Over MCP: Build a WebMCP Tool From Scratch

Step 1 — detect WebMCP, don't assume it

Step 2 — write the tool as a plain function first

Step 3 — register it the way errors don't crash the caller

Step 4 — verify it before you add anything else

Step 5 — the part most tutorials skip: don't trust a URL parameter

Step 6 — the same shape, in production

Context Over MCP, Part IV: No Working Directory At All

The API is not FAF's

Three tools, two ways to register them

The part that's honest about its own limits

The fetch surface is an allowlist, not a promise

Try it

What Part I asked, answered somewhere Part I didn't expect

Context Over MCP, Part III: Horses for Courses

The flat racer: Markdown, for instructions

The course has fences: the facts

The jumper: schema, for definitions

Both horses, one card

The loop

What this series is about

FastMCP 3 4 migration: the breaking changes that compile

1. pip install -U fastmcp can leave you half-broken

2. httpx → httpx2: your except clauses go quiet

3. Client now defaults to mode="auto"

4. Removed ctx methods

5. Version floors

6. Import moves (quick reference)

7. New defaults from the settings page

The good news: the minimal server barely changes

What I actually changed

The checklist

More reading

React, Next.js, Svelte, Zod: none of them can tell AI who they're actually for

Your coding agent is good at reading code.

The method

The result

Why the two halves behave differently

The fix is about ten minutes

If you want the number

Your tools/list is stamped. That is not the same as cached.

The victory lap

We built a liar. Then the lie got lazy.

Presence is not truth

Run the audit

Step 1 — Clone and build both binaries

Step 2 — Run contrast-smoke

Step 3 — What you just proved

What this is not

1. `pip install -U fastmcp` can leave you half-broken

2. `httpx` → `httpx2`: your `except` clauses go quiet

3. `Client` now defaults to `mode="auto"`

4. Removed `ctx` methods

10-minute textbook: `mcp-better`