DEV Community: wolfejam.dev

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.

AGENTS.md Series Wrap: Five Lessons, FAQs, and What I'd Do Differently

wolfejam.dev — Tue, 28 Jul 2026 14:48:53 +0000

TL;DR — Five posts. One file. The whole arc: what it is → write one → why it rots → keep it true → author from facts. This is the wrap: the map of the series, five FAQs, and the lesson that stuck — facts block vs unique prose.

📚 The AGENTS.md Series · you're on Part 6 — Series wrap

New here? AGENTS.md is a single Markdown file at the repo root that tells AI coding agents how to work in it — commands, tests, conventions, guardrails. Open standard under the AAIF / Linux Foundation. Start at Part I if you want the full path.

What we covered

Five lessons. One job: make the briefing agents obey true.

Part	Role	One line
I	Field guide	What belongs in AGENTS.md — and what doesn't
II	Hands-on	Build a real file, then point an agent at it
III	The threat	A stale file is still obeyed — at full confidence
IV	Discipline	Same-PR anti-rot, verify with an agent, keep truth current
V	Endgame	Author from repo facts so the file can't drift

If you only read one besides this wrap: III if you've never felt rot; V if you already have a file and want it to stop lying.

Step-through: how the arc fits

Read it as a single path, not five islands.

I   What is AGENTS.md?          →  principles, shape, anti-patterns
II  Write one                   →  real file, real agent payoff
III Watch it go stale           →  why "present" ≠ "true"
IV  Keep it true by hand        →  human discipline while the code moves
V   Stop hand-maintaining facts →  regenerate what the tree already knows
VI  This post                   →  map · FAQs · the lesson that remains

I and II get you a file that works.

III and IV get you a file that stays honest under change.

V removes the class of lines that should never have been typed by hand.

VI (here) is the map and the judgment call: what still needs a human.

The series does not argue for a longer AGENTS.md. It argues for a truer one: a concise facts block, then your prose. Overall length is yours.

Five FAQs

1. Do I need AGENTS.md if I already have README / CONTRIBUTING / CLAUDE.md?

Yes, if agents work in the repo. README is for humans browsing. CONTRIBUTING is process. Vendor files (CLAUDE.md, etc.) are tool-specific. AGENTS.md is the tool-agnostic briefing many agents already look for. Keep it short; link out for depth. Don't duplicate a novel.

2. How long should it be?

Short enough that an agent (and a human) will still trust every line. Prefer commands you can run, paths that exist, and guardrails that bite. If a section can't be verified against the tree or a one-line rule, cut it or move it.

3. What's the #1 failure mode?

Stale truth that still looks official. Renamed scripts, dead test commands, structure maps that lag the tree — the agent obeys them at full confidence. Part III is the whole point. Freshness is not a nicety; it's the product.

4. Should every line be auto-generated?

No. Generate (or check) what the repo can prove: package names, scripts, layout, CI commands. Keep human what only a human owns: judgment, product "why," team norms that aren't in the tree, "never do X" that isn't a linter rule yet. Part V is the endgame for the facts half — not a replacement for judgment.

5. Where do I start if I have nothing?

Part I — shape and anti-patterns
Part II — write one and verify with an agent
When it starts lying, IV then V

Don't skip III forever — you'll meet it the hard way.

My lesson: facts block vs unique prose

If the series leaves one idea standing, make it this.

	Facts block	Unique prose
What	Things the repo already knows or can prove	Things only a human should assert
Examples	Build/test commands, package layout, entrypoints, CI checks	Why the product exists, team taste, soft norms, hard "never" that isn't encoded yet
Failure mode	Drift (tree moves, file doesn't)	Vagueness or lecture that no agent can act on
Fix	Author/check from the tree; fail CI on drift (V)	Write short, actionable, owned by a human; same PR as the change when norms move (IV)

BETTER AGENTS.md = facts that match the tree plus prose that earns its tokens.

I used to treat the whole file as "documentation I should maintain." The series taught me to split the job: automate honesty for the map; reserve human attention for judgment. That's the difference between a file that exists and a file that deserves to be trusted.

What "good" vs "BETTER" looks like in practice

	Good	BETTER
File exists at repo root	✓	✓
Agent can follow setup/test	Often	Commands match `package.json` / `just` / CI today
Structure / map	Hand-wavy or partial	Matches live tree (or deliberately points at it)
Stale lines	"We'll fix later"	Same PR as the change, or regenerate facts
Length	Long and impressive	Short and true

Goose, Cursor, Claude Code, Copilot, Codex — none of them need your autobiography. They need a briefing that won't send them into a renamed script at full confidence.

Q&A / feedback

This wraps the series for the AAIF Ambassador program — A practical, vendor-free AGENTS.md guide.

I'd like to hear from you:

Where does your AGENTS.md rot first (commands, structure, guardrails, something else)?
Did you try authoring from facts (Part V) — what broke?
What's still missing from the open AGENTS.md conversation that these five parts didn't touch?

Comment on this post, or open a discussion on a project you care about (for example: keep that repo's Structure true to crates/ / src/). The standard gets better when real trees push back on pretty docs.

Series index (bookmark this)

AGENTS.md: The One File That Makes AI Coding Agents Actually Useful — field guide
AGENTS.md, Hands-On: Build One Step by Step — tutorial
Your AGENTS.md Is Already Stale (And Your Agent Trusts It Completely) — the threat
AGENTS.md Kept True: Stop the Rot Step by Step — discipline
AGENTS.md From Facts: Author One That Can't Drift — endgame tool path
This post — wrap · FAQs · facts vs prose

Further reading: the standard itself at agents.md, and a section-by-section field guide — what earns a line, ordering, length, the anti-patterns — at faf.one/agents.

Thanks for reading the series.
Ship a short true file.
Then keep it true.
👍

AGENTS.md From Facts: Author One That Can't Drift (Step by Step)

wolfejam.dev — Fri, 24 Jul 2026 12:00:00 +0000

TL;DR — Parts I–IV got you a real AGENTS.md and the discipline to keep it honest. This is the endgame Part IV pointed at: stop hand-maintaining lines the repo already knows. Author a minimal file from detected facts, protect human notes outside markers, fail CI when it drifts, point an agent at it. Six steps. One CLI. Facts only.

Series: I · field guide → II · hands-on → III · stale → IV · keep it true → you're on V.

Why the file still earns its keep

Twenty seconds on why AGENTS.md exists before we automate it:

Benefit	What the agent gets
Faster first move	Real setup / build / test commands — no guessing the runner
Self-check loop	Tests as the bar for "done" — re-derive truth from the world
Less interruption	Map + conventions — fewer "where do routes go?" questions
Fewer expensive mistakes	Guardrails (always / ask first / never) + definition of done
One briefing, many tools	Tool-agnostic Markdown — Cursor, Claude Code, Codex, Copilot, goose, Grok, peers

Short. Current. Specific. Actionable. Parts I–II covered what and how to write it. Parts III–IV covered why it dies and the human discipline that keeps it alive.

Part IV Step 5's honest endgame: regenerate from the repo so the file can't drift. This is that tutorial.

In one line: Part II taught you to write the file · Part IV taught you to keep it true · Part V hands you the tool — stop hand-maintaining what the tree already knows. Ready?

The trap

Two failure modes, both real:

Hand-written and left alone → it rots. You rename a script; the agent still runs the old one at full confidence.
"Let an AI write the whole file" → it bloats. Research (Gloaguen et al., 2026) found LLM-written instruction files can reduce task success and raise cost — plausible padding the agent over-obeys.

The fix is not more vibes. Facts only: every managed line traces to something the tree already declares — real scripts, real configs, real entry points. Nothing invented. Nothing padded.

That's agents-md-facts: a small CLI that authors a minimal AGENTS.md from repo facts. Open a real project and follow along.

Step 1 — Dry-run first

Any repo with a real package.json, pyproject.toml, Cargo.toml, or go.mod:

npx agents-md-facts --dry-run

You get the plan — orientation, setup/build, tests, map, conventions, guardrails, definition of done — without writing a file. Sanity-check: are those the commands you actually run? If not, fix the scripts/config (source of truth), not the prose later.

Optional — managed block only:

npx agents-md-facts --stdout

Step 2 — Author (or refresh)

npx agents-md-facts

Writes or refreshes AGENTS.md at the repo root. Managed region:

<!-- agents:from-facts:start -->
<!-- authored by agents-md-facts — from your repo's facts, never guessed · re-run to refresh -->

# AGENTS.md — your-project

…

<!-- agents:from-facts:end -->

Non-destructive: everything outside those markers is yours. Re-run anytime; hand-written notes survive. Put tool quirks, domain gotchas, and "don't touch this without a human" outside the block. Author the rest from facts.

Step 3 — Read it like an agent

Open the file. Shape for a small Node/TS example (exact style from the tool's examples):

Orientation

TypeScript · Node.js · npm package manager · v1.0.0

Setup & build

npm install    # install dependencies
npm run build    # build
npm run dev    # dev

Run the tests

npm run test
npm run lint

Where things live

package.json
src/index.ts
tsconfig.json

Conventions

TypeScript strict mode (tsconfig.json)
ESM modules (type: module)
Style enforced by ESLint · Prettier — obey the configs

Guardrails

Always OK: read files, run the tests (npm run test), build the project.
Ask first: dependency installs, deletions, migrations / schema changes.
Never: force-push, commit secrets.

Definition of Done

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

Part IV rules, automated:

Commands copy-pasteable and backticked as literals
Tests where the agent needs a feedback loop
Conventions point at configs — don't restate "use 2 spaces"
Guardrails enable-first (always / ask / never)
Definition of Done mechanically checkable

If a line wouldn't resolve an ambiguity for a fresh agent, the tool drops it. Short by construction.

Step 4 — Human layer (outside the markers)

Facts can't know product judgment. Below the end marker (or above the start), add what only you know:

<!-- agents:from-facts:end -->

## Project notes (human)

- Prefer the query builder in `src/db/` — no raw SQL in handlers.
- Feature flags live in `src/flags.ts`; don't hardcode rollout in routes.
- Billing code is off-limits without a human in the loop.

Next refresh leaves this intact. Machine-owned facts inside · human-owned judgment outside.

Step 5 — Make drift a build failure

Part IV's anti-rot rule: AGENTS.md changes in the same PR as the code. Automate it.

Local / CI:

npx agents-md-facts --check

Exits 1 if missing or the managed block is stale vs the repo.

GitHub Action:

# .github/workflows/agents-md.yml
name: AGENTS.md
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Wolfe-Jam/agents-md-facts@v0.1.0

Pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Wolfe-Jam/agents-md-facts
    rev: v0.1.0
    hooks:
      - id: agents-md-facts

Then: pre-commit install.

When scripts or layout change, fix in the same PR:

npx agents-md-facts

Treat the file like code — because your agent already does.

Step 6 — Verify with an agent

Same proof as Parts II and IV. Small real task:

"Add a tested /health endpoint."

Watch for:

It reads AGENTS.md first.
It runs the exact test/lint commands from the file.
It respects Always / Ask / Never.
It hits Definition of Done without you re-explaining the toolchain.

If it runs the wrong command or ignores a convention, the file (or the underlying scripts) lied — fix the fact source, re-author, re-check. Don't scold the agent for trusting the briefing you gave it.

What this does not replace

Still yours	Why
Judgment outside markers	Facts don't know billing, legal, or when to "ask the Owner first"
README for humans	AGENTS.md = how to work; README = what/why
Code review	A true file helps the agent; humans still ship
Lint of your prose	Complements bloat-linters — this authors clean from truth

You can still hand-write the whole file (Part II). You can still run Part IV without a generator. The CLI is for lines that should never have been hand-copied from package.json in the first place.

The loop, closed

Part	What you learned
I	What belongs · anti-patterns · short > complete
II	Build section by section · watch an agent use it
III	Stale cache worse than empty · facts only
IV	Same-PR updates · point-at-config · enable-first guardrails
V (this)	Author from facts · markers · `--check` · CI · agent verify

Short. Current. Specific. Actionable. And now re-derivable from the tree — so the agent stops inheriting last sprint's lies.

Where to go deeper

Series: I · II · III · IV · V (you are here)

Tool (source + stars) — github.com/Wolfe-Jam/agents-md-facts · npx agents-md-facts
Standard — agents.md
Field guide (what earns a line, length, anti-patterns) — faf.one/agents

⭐ If this saved you a hand-written or LLM-bloated AGENTS.md, a star on the repo helps others find it.

Keep the facts honest. Your agent only ever trusts the last true thing you told it.

AGENTS.md, Kept True: Stop the Rot Step by Step (and Watch Your Agent Trust It)

wolfejam.dev — Sat, 11 Jul 2026 17:56:44 +0000

TL;DR — A good AGENTS.md isn't written, it's maintained — and the maintenance is where every one dies. Here's the exact discipline that keeps yours true: tie every line to a fact in the repo, verify it runs, and make it change in the same PR as the code. Six steps, one worked example, and an agent that stops guessing.

You've got an AGENTS.md — maybe you built one step by step. The problem now isn't writing it. It's that, as we covered, it goes stale the day you write it — it starts lying the moment your code moves, and your agent believes it anyway. So let's harden it. Open a repo and follow along.

Step 1 — Start from the truth, not a template

Before you write a line, list what's actually real:

cat package.json | jq .scripts     # your real commands
ls src/                            # your real entry points
ls .eslintrc* tsconfig.json 2>/dev/null   # your real conventions (the configs)

Rule for the whole file: if it isn't in the repo, it doesn't go in the AGENTS.md. No aspirations, no "we should probably." Facts only.

Step 2 — Write the commands copy-pasteable, then RUN them

Don't type npm build from memory. Run it, and paste what actually works:

npm run build && npm test

Put the exact strings in the file. If the command in your AGENTS.md doesn't run, your agent's first move fails — and it won't know why. Tests go above build: they're the agent's only way to check its work against reality.

And wrap every tool and command name in backticks — mypy, ruff, npm test. A formatted token reads as a literal to run, not a vague suggestion the model can paraphrase away when the context is saturated.

Step 3 — Point at the config; don't restate it

You already have a linter and a formatter. So don't write "use 2 spaces, prefer const, strict types." Write:

## Conventions
- Style is enforced — run `npm run lint`. Obey the config, don't hand-format.
- TypeScript strict mode (tsconfig.json).

Restating a rule your linter owns is how the file goes stale (you change the config, the prose lies). Point at the source of truth instead. One line, can't rot.

Step 4 — Guardrails in three tiers + a Definition of Done

Give the agent a safety map and a finish line:

## Guardrails
- **Always:** read files, run the tests, build.
- **Ask first:** dependency installs, deletions, migrations.
- **Never:** force-push, push to `main`, commit secrets.

## Definition of Done
Done when: `npm run lint` exits 0 · `npm test` passes · committed with a conventional message.

Now the agent can know it's finished, not guess — and it knows which moves need a human.

One phrasing note that punches above its weight: lead with the enable, not the prohibition. "Branch and open a PR" hands the agent the safe path; a bare "don't push to main" hands it only the landmine — and a naked negative can prime the very move it's warning against. Say what to do, then the boundary.

Step 5 — The anti-rot rule: it changes in the same PR as the code

This is the step everyone skips, and it's the whole game. Make drift a bug, not a someday:

Add it to your PR template: "Touched build/test scripts? Update AGENTS.md."
Or a CI check that fails if package.json scripts changed but AGENTS.md didn't.
Or — the honest endgame — regenerate the file from the repo so it can't drift (more on that below).

Treat AGENTS.md like code, because your agent already does.

Step 6 — Verify: point your agent at it and watch

Give the agent a small, real task ("add a tested /health endpoint"). Watch it: read the file, run the tests you listed, respect the guardrails, hit your Definition of Done. If it does the wrong thing — wrong command, ignored convention — your file lied. Fix the line, not the agent.

That loop — task, watch, fix the line — is how an AGENTS.md earns trust. A true one becomes the most reliable thing in your repo.

Where to go deeper

The series: 1 · the field guide → 2 · build one, hands-on → 3 · why it goes stale → you're on 4.

The AGENTS.md standard — agents.md (the spec itself).
Section-by-section definitions + a field guide — faf.one/agents (what earns a line, ordering, length, and the anti-patterns).
Why "generated from truth" beats hand-writing and AI-slop — the research and the deeper dive, same place.

Keep it honest, and your agent stops guessing. That's the whole point of the file.

Your AGENTS.md Is Already Stale — And Your Agent Trusts It Completely

wolfejam.dev — Fri, 10 Jul 2026 17:43:45 +0000

TL;DR — A hand-written AGENTS.md rots the day you write it. And unlike a stale README (which a human skims skeptically), a stale AGENTS.md is obeyed by your coding agent with full confidence: wrong build command, missing guardrail, dead convention — followed to the letter. The fix isn't more discipline. It's writing the file so every line traces to a fact you can verify, and refusing to let it drift.

In the field guide, I covered what an AGENTS.md is and what belongs in it. In the build-along, we wrote a complete one against a real repo and watched an agent use it. This is the part nobody warns you about — the part that decides whether all of that pays off: keeping it true.

Why you need to know this

You probably already have an AGENTS.md — or you're about to. Here's the part nobody says out loud: it's a cache, and a stale cache is worse than an empty one.

A human reads a stale README and thinks "hmm, that looks old." An agent reads your AGENTS.md and acts on it — it runs the build command you renamed three sprints ago, skips the guardrail you added last week, follows the convention you already abandoned. Confidently. No second-guessing.

So the real question isn't "should I have an AGENTS.md." (Yes.) It's "how do I keep it true?"

How to do it

A good AGENTS.md answers exactly one question: how do I work in this repo? Not what the project is — that's the README. How to actually operate here. Six moves:

1. Orientation — one line. What it is, the language, the stack. Then stop.

2. The real commands. Setup, build, and — most important — how to run the tests. Copy-pasteable. Tests rank above build, because tests are the agent's only way to check its work against reality instead of trusting a stale belief.

3. Where things live. Entry points and key directories — not a file dump (the agent can run ls). Just the non-obvious "start here."

4. Conventions — only what resolves ambiguity. "Validate input at the route boundary with Zod" is useful. "Write clean code" is ignored. And if a rule is already enforced by your linter or formatter, point at the config — don't restate it.

5. Guardrails — what NOT to do. The landmines. Three tiers is the sweet spot: what's always safe, what to ask first, what to never do (force-push, touch prod, commit secrets).

6. A definition of done. "Done when lint passes, tests pass, changes committed." Make it mechanically checkable — the agent should be able to know it's finished, not guess.

Keep it short — 20–50 lines. Every line earns its place by one test: does it resolve a real ambiguity, or save the agent an expensive hunt? If it does neither, cut it. (Past ~150 lines you're adding cost with no gain.)

The part almost everyone gets wrong

There are two failure modes, and they're opposite:

Hand-written and left alone → it rots. You change the code; the file quietly lies.
"Let an AI write it for me" → it bloats. The research here is blunt: auto-generated instruction files measurably reduce task success and add cost, because the model pads them with plausible-sounding requirements the agent then over-obeys.

The fix is the same for both: every line should trace to a fact. A real command. A real file. A real constraint. Not prose, not padding, not guesses. And when the code changes, the file changes in the same PR — treat it like code, because your agent already does.

Get those two things right — facts only, kept current — and your AGENTS.md stops being a liability and starts being the most reliable thing in the repo.

Why we care about this

We maintain a lot of repos, and we kept paying the same tax: the AGENTS.md goes stale, everywhere, every week. Getting the file right is an afternoon. Keeping it true is the harder half — and it's the half that actually decides whether your agent helps you or confidently ships you the wrong thing.

Write one well. Keep it honest. Your agent is only as good as the last true thing you told it.

Further reading: the standard itself at agents.md, and a section-by-section field guide — what earns a line, ordering, length, the anti-patterns — at faf.one/agents.

Coming next: the exact discipline to keep it true — step by step, stopping the rot, with an agent you can watch trust it.

AGENTS.md, Hands-On: Build One Step by Step (and Watch an Agent Use It)

wolfejam.dev — Sat, 04 Jul 2026 03:31:12 +0000

In the field guide I covered what an AGENTS.md is and what belongs in it. This is the hands-on follow-up: we'll build a complete AGENTS.md for a real project, one section at a time, then point an AI coding agent at it and watch the difference it makes. By the end you'll have a working file — and you'll have seen it pay off.

New to AGENTS.md? It's a single Markdown file at the root of your repo that tells AI coding agents how to work in it — build steps, tests, conventions, guardrails. The "why" behind each section is in the field guide.

The project we'll use

We'll write the AGENTS.md for a small but real service: a URL shortener API in Python — FastAPI, SQLite, pytest. A couple of endpoints, a thin data layer, a test suite. Follow along with this, or swap in your own repo — the steps are identical.

Its shape:

linkshort/
  app/
    main.py        # FastAPI routes
    db.py          # SQLite access
    models.py      # Pydantic models
  migrations/      # generated SQL — not hand-edited
  tests/
  requirements.txt

Step 0 — Start with an empty file

At the repo root:

touch AGENTS.md

That's the whole step. We'll fill it in one section at a time, building toward a file an agent can read in thirty seconds.

Step 1 — Orientation: one line

Tell the agent what it's looking at. Add:

# AGENTS.md

A URL shortener API in Python — FastAPI, SQLite, pytest.

One sentence sets the agent's priors: it knows the language, framework, and storage before it reads a single line of code.

Step 2 — Setup and run

The agent can't help if it can't start the project. Add the real, copy-pasteable commands:

## Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

## Run
uvicorn app.main:app --reload   # http://localhost:8000

Use the commands that actually work in your repo — no placeholders.

Step 3 — Tests: the agent's feedback loop

This is the most important section, because tests are how the agent checks its own work. Add:

## Test — all must pass before a change is done
pytest
ruff check .
mypy app

Now the agent knows how to verify a change and the bar it has to clear. An agent that knows pytest will run it; one that doesn't hands you a broken branch.

Step 4 — The map: where things live

A short map so the agent finds its way without spelunking the whole tree:

## Structure
- app/main.py    route handlers
- app/db.py      SQLite access (parameterized queries only, never string-built SQL)
- app/models.py  Pydantic request/response models
- migrations/    generated SQL — do not hand-edit
- tests/         pytest, mirroring app/

Notice we're already slipping a convention ("parameterized queries only") and a guardrail ("do not hand-edit") in right where they're relevant.

Step 5 — Conventions: the house style

The patterns you want followed. Be specific — vague rules are noise:

## Conventions
- Validate all input with Pydantic models at the route boundary.
- Raise HTTPException for client errors; never return raw dicts on failure.
- Type everything; mypy must stay clean.
- Match the style of the surrounding file.

"Type everything; mypy must stay clean" tells the agent exactly what to do. "Write good code" wouldn't.

Step 6 — Commits and PRs

If your agent opens PRs, give it the house rules:

## Commits & PRs
- Conventional Commits (feat:, fix:, chore:).
- One logical change per PR; update CHANGELOG.md.

Step 7 — Guardrails: the landmines

The "don'ts" that prevent expensive mistakes:

## Don't
- Don't hand-edit migrations/ — they're generated.
- Don't commit directly to main — branch and open a PR.
- Never run the seed script against a non-local database.

Your finished AGENTS.md

Put it together and you have a complete, copy-pasteable file:

# AGENTS.md

A URL shortener API in Python — FastAPI, SQLite, pytest.

## Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

## Run
uvicorn app.main:app --reload   # http://localhost:8000

## Test — all must pass before a change is done
pytest
ruff check .
mypy app

## Structure
- app/main.py    route handlers
- app/db.py      SQLite access (parameterized queries only, never string-built SQL)
- app/models.py  Pydantic request/response models
- migrations/    generated SQL — do not hand-edit
- tests/         pytest, mirroring app/

## Conventions
- Validate all input with Pydantic models at the route boundary.
- Raise HTTPException for client errors; never return raw dicts on failure.
- Type everything; mypy must stay clean.
- Match the style of the surrounding file.

## Commits & PRs
- Conventional Commits (feat:, fix:, chore:).
- One logical change per PR; update CHANGELOG.md.

## Don't
- Don't hand-edit migrations/ — they're generated.
- Don't commit directly to main — branch and open a PR.
- Never run the seed script against a non-local database.

Thirty seconds to read. Now let's see if it works.

Step 8 — Prove it: point an agent at it

This is the part that matters. Open your repo in an AI coding agent — Claude Code, Cursor, Codex, whatever you use — and give it a real task:

"Add a DELETE /links/{code} endpoint that removes a link, with a test."

Watch what it does with the AGENTS.md in place:

It reads the file first — it knows the stack and where routes live.
It adds the handler in app/main.py, validating input the way your conventions require.
It writes a pytest test in tests/, mirroring the structure.
It runs pytest, ruff, and mypy — because you told it that's the bar — and fixes what fails.
It doesn't touch migrations/, and it doesn't commit to main — it opens a branch.

Now picture the same task without the file. The agent has to guess: Which test runner? Where do routes go? Is there a lint step? So it asks you, or it guesses wrong, or it edits a generated file you'll have to revert. The AGENTS.md is the difference between an agent that interrupts you and one that just ships.

That's the whole payoff — and you can watch it happen in real time.

Keep it alive

One habit before you go: treat the file like code. When the test command changes, or you add a directory, or you catch yourself telling the agent the same thing twice — update AGENTS.md in the same breath. A stale file is worse than none, because the agent trusts it.

That's the loop

You started with an empty file, added eight short sections, and watched an agent use every one of them to land a correct, tested change without hand-holding. Write it once, and every agent that walks into your repo gets the same briefing.

This was the hands-on build. For the principles behind each section — what belongs, the anti-patterns, why short beats complete — see the field guide.

AGENTS.md: The One File That Makes AI Coding Agents Actually Useful

wolfejam.dev — Tue, 30 Jun 2026 01:51:07 +0000

If you’ve used Claude Code, Cursor, Codex, Aider, Gemini CLI, GitHub Copilot, Grok, goose, or similar tools, you’ve seen the same pattern: the agent’s first priority is context. What is this project? How do I build it? How do I run the tests? What conventions should I follow? What must I not break?

AGENTS.md is the open answer. It’s a single Markdown file placed at the root of your repository that serves as a dedicated, predictable briefing for AI coding agents. Think of it as a README written specifically for the agent instead of a human. The format is deliberately simple and tool-agnostic — one file that works across many agents.

AGENTS.md was pioneered by OpenAI's Codex and shaped alongside tools like Cursor, Amp, Factory, and Google's Jules. In December 2025 it was donated to the Agentic AI Foundation under the Linux Foundation, where it's now stewarded as an open standard.

Most AGENTS.md files fail in one of two ways: they’re either too thin to be useful or they’re long, rambling documents the agent skims and mostly ignores. A good AGENTS.md sits in the middle — short, current, specific, and actionable.

README is for humans. AGENTS.md is for the agent.

This distinction determines everything that belongs in the file.

README.md answers what and why: what the project is, why it exists, and how a human gets started.
AGENTS.md answers how to work here: the exact commands, conventions, and guardrails an agent needs to make changes and verify them without asking questions.

Do not duplicate content from the README. If the agent doesn’t need it to act effectively, leave it out. Every non-essential line dilutes the signal.

What actually belongs in AGENTS.md

The highest-value sections, in rough priority order.

One-line orientation. A single sentence telling the agent what the project is and what stack it uses — for example, “A TypeScript REST API on Node 20 with Postgres, deployed to Fly.io.”

Setup and build commands. The single most valuable section. Give the real, copy-pasteable commands:

npm install
npm run build
npm run dev

How to run tests. Even more important than build commands — tests are how the agent verifies its own work:

npm test          # all tests must pass before considering a change complete
npm run lint
npm run typecheck

Where things live. A short, focused map of key directories and entry points — not a full tree dump.

Conventions. Specific patterns you want followed: validation approach, error handling, naming, preferred libraries, architectural decisions. Vague statements like “write clean code” are useless; specific rules like “Validate all input with Zod at the route boundary” are useful.

Commit and PR rules. Message format, branch naming, changelog updates, and any other process requirements.

Guardrails — what NOT to do. The landmines that prevent expensive mistakes: don’t edit files in /generated, never run migrations against production config, and don’t commit directly to main.

The anti-patterns that make it worse than nothing

A bad AGENTS.md doesn’t just fail to help — it actively misleads the agent.

The novel: Too long. The agent skims and important instructions get lost. Cut anything that isn’t load-bearing.
The stale file: An outdated command or path is worse than no file at all. The agent will confidently do the wrong thing.
Vagueness: “Follow best practices” gives the agent nothing actionable.
Secrets: Never put credentials, keys, or tokens in AGENTS.md. Point to where they come from (.env, secrets manager) instead.
README duplication: Wasted tokens and maintenance burden.

Keep it alive — treat AGENTS.md like code

AGENTS.md files rot when no one owns them. Treat the file the same way you treat production code:

Review changes to it in pull requests.
Update it the moment reality changes (new test command, new directory structure, new convention).
Watch what the agent actually does. When it guesses, asks unnecessary questions, or touches something it shouldn’t, that’s usually a missing or stale instruction.

A useful habit: every time you find yourself giving the same instruction to an agent twice in chat, move that instruction into AGENTS.md.

One file, many agents

The strength of AGENTS.md is that it isn’t tied to any single tool. Most major coding agents either read it directly or converge on the same root-level instruction pattern. Write plain Markdown with tool-agnostic instructions. Avoid “if you are using X tool” branching.

For monorepos, you can place additional AGENTS.md files in subdirectories. Most agents use the nearest file to the code they’re working on.

A minimal, complete example

# AGENTS.md

A TypeScript REST API on Node 20, Postgres, deployed to Fly.io.

## Setup
npm install
cp .env.example .env   # fill in DATABASE_URL

## Build & run
npm run build
npm run dev            # http://localhost:3000

## Test — all must pass before a change is considered done
npm test
npm run lint
npm run typecheck

## Structure
- src/routes/     HTTP handlers
- src/db/         Postgres queries (use the query builder, no raw SQL)
- src/lib/        shared utilities
- test/           Vitest tests, mirroring src/ structure

## Conventions
- Validate all input with Zod at the route boundary
- Throw AppError (from src/lib/errors.ts), never a bare Error
- Match the style and patterns of the surrounding file

## Commits & PRs
- Use Conventional Commits (feat:, fix:, chore:)
- One logical change per PR
- Update CHANGELOG.md when relevant

## Don't
- Don't edit anything in src/generated/ (regenerated from schema)
- Don't commit directly to main — always branch and open a PR
- Never run db:reset against a non-local DATABASE_URL

An agent (or a new human teammate) can read this in under 30 seconds and start being productive.

The real test of a good AGENTS.md

You’ll know it’s working when a fresh agent can land a correct, tested change in your repository without asking how to build, how to test, or which conventions to follow — and without touching the one thing you explicitly told it not to touch.

Short. Current. Specific. Actionable. That’s the entire job.

This was the field guide — the why and the what.

Coming next in the series: a step-by-step build-along, where we’ll write a complete AGENTS.md against a real repo, then point an agent at it and watch it build, test, and respect the guardrails without being asked. (A day or two out.)

DEV Community: wolfejam.dev

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

Steal the pattern

Further reading

Close

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

The honest starting number

Dogfooding it for real

What it got right

What it missed — twice, same shape

Why — and it isn't a bug

What this means beyond this one tool

What I'm changing because of this

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

The problem with trusting a README

Build the lie on purpose

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

Steal the pattern

Further reading

Close

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

Same name, different machine

GOOD habits (pre-7/28 muscle memory)

BETTER after 7/28 (checklist you can audit)

If MCP had an AGENTS.md

10-minute textbook: mcp-better

Step 1 — Install

Step 2 — Run stdio (default)

Step 3 — Optional HTTP road (same era)

Step 4 — What you just proved

What this is not

Further reading (one hop)

Close

AGENTS.md Series Wrap: Five Lessons, FAQs, and What I'd Do Differently

What we covered

Step-through: how the arc fits

Five FAQs

1. Do I need AGENTS.md if I already have README / CONTRIBUTING / CLAUDE.md?

2. How long should it be?

3. What's the #1 failure mode?

4. Should every line be auto-generated?

5. Where do I start if I have nothing?

My lesson: facts block vs unique prose

What "good" vs "BETTER" looks like in practice

Q&A / feedback

Series index (bookmark this)

AGENTS.md From Facts: Author One That Can't Drift (Step by Step)

Why the file still earns its keep

The trap

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`