mcp-stateless-migration

An Agent Skill for migrating an MCP server to the stateless MCP specification published on 2026-07-28.

Install

# into ./.claude/skills/mcp-stateless-migration/
npx -y --allow-git=all github:efaimo-ai/mcp-stateless-migration

# into ~/.claude/skills/mcp-stateless-migration/, for every project
npx -y --allow-git=all github:efaimo-ai/mcp-stateless-migration --global

# installed already, and still current?
npx -y --allow-git=all github:efaimo-ai/mcp-stateless-migration --check

That is the repository, not the registry, and it is deliberate: mcp-stateless-migration is not on npm yet, and printing npx mcp-stateless-migration today would advertise a command that 404s.

--allow-git=all is there because npm 12 refuses git specs by default (EALLOWGIT), and it is the only value that helps: a narrower --allow-git=<spec> is still refused. You should not enjoy typing it. Switching off a protection npm added on purpose is a poor way to install anything, and the honest alternative is that this skill is markdown: copy SKILL.md and its references/ into .claude/skills/mcp-stateless-migration/ and you are done, with nothing to trust.

Both of those go away when the package publishes, because npx mcp-stateless-migration needs no flag on either npm major. This README is regenerated from a committed registry probe, so that sentence changes itself rather than waiting for someone to remember it.

The package is the skill: SKILL.md and its references/, nothing else. The installer copies them, reads every byte back, and fails if what landed is not what it wrote. It refuses to overwrite a directory whose contents differ unless you pass --force, and installing the same version twice is a success rather than a conflict.

Or take it by hand. It is markdown; npx -y --allow-git=all github:efaimo-ai/mcp-stateless-migration --print writes SKILL.md to stdout, and the repository is the whole thing.

What moves

flowchart LR
    subgraph OLD["before 2026-07-28"]
        A1["initialize<br/>Mcp-Session-Id"]
        A2["Sampling, Roots, Logging"]
        A3["elicitation/create"]
        A4["ping, Last-Event-ID"]
        A5["resources/subscribe"]
    end
    subgraph NEW["2026-07-28, stateless"]
        B1["no handshake<br/>server/discover"]
        B2["provider API, tool args, stderr"]
        B3["MRTR<br/>resultType input_required"]
        B4["removed"]
        B5["subscriptions/listen"]
    end
    A1 --> B1
    A2 --> B2
    A3 --> B3
    A4 --> B4
    A5 --> B5

Thirteen changes in total. Two of them have no readiness rule behind them and have to be checked by hand; the skill says which two where an agent will read it.

Why a skill and not a blog post

The revision published on 2026-07-28, later than many model training cutoffs, so a coding agent asked to "make this server 2026-07-28 ready" is working from the old protocol or from guesses.

There is a second trap underneath that one. For the 68 days between the Release Candidate locking on 2026-05-21 and the spec publishing, the RC was the only thing there was to read, and it is not the published spec: server identity moved into _meta, DiscoverResult became cacheable, and three error codes were renumbered. You do not have to take that on trust, and you do not need a survey of the internet to apply it. It is a one line test on any source you are about to follow: if it names DiscoverResult.serverInfo, or error -32003 or -32004, it is reading the RC.

We know the trap is real because we fell into it. efaimo's own readiness rules were written against the RC, and for four days after the spec published they reported "identity unknown" for exactly the servers that had finished migrating. The fix, and the diff that found it, are what this skill packages.

This skill carries the published shapes, the deltas from the RC, and the two commands that prove the migration landed.

Everything in it is verified against schema/2026-07-28/schema.ts at tag 2026-07-28 in modelcontextprotocol/modelcontextprotocol, not against a summary. references/rc-vs-final.md includes the commands to reproduce the RC-to-final diff yourself.

Install

Copy the directory into your skills location, for example:

git clone --depth 1 https://github.com/efaimo-ai/mcp-stateless-migration \
  ~/.claude/skills/mcp-stateless-migration

What is in it

file	loaded	contents
SKILL.md	on trigger	the three-step procedure: measure, change, prove
references/changes.md	on demand	all thirteen changes with their SEP or PR, and the shapes to emit
references/rc-vs-final.md	on demand	what moved between the locked RC and the published spec
references/verify.md	on demand	how to prove it landed, and what a passing suite still misses

Its own numbers

Audited by efaimo, which is the same tool this skill tells you to run:

This is the beginning of the README. Read the rest at the original. Read the full README ↗