# Mcp Migration > Diagnose and carry out the migration of an MCP server to the 2026-07-28 specification — the revision that made the transport stateless, formalized OAuth 2.1, and deprecated the logging, sampling, and roots capabilities. Use this skill whenever someone mentions migrating, upgrading, or checking an MCP server against the 2026-07-28 spec; asks whether their MCP server still works, is "ready", or wil… - **Type:** Skill - **Install:** `agentstack add skill-alpayc-mcp-migration-check-mcp-migration` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [AlpayC](https://agentstack.voostack.com/s/alpayc) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [AlpayC](https://github.com/AlpayC) - **Source:** https://github.com/AlpayC/mcp-migration-check/tree/main/skill/mcp-migration - **Website:** https://mcp-migration-check.alpaycelik.workers.dev/ ## Install ```sh agentstack add skill-alpayc-mcp-migration-check-mcp-migration ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # MCP 2026-07-28 migration The 2026-07-28 revision is a refactor, not a version bump. Four things this checker looks for break existing servers: 1. **The transport is stateless.** The `initialize`/`notifications/initialized` handshake and the `Mcp-Session-Id` header are gone. Every request carries its own protocol version and client capabilities in `_meta`. 2. **OAuth 2.1 is formalized** for remote servers: a protected MCP server acts as an OAuth 2.1 resource server and **MUST** implement RFC 9728 protected-resource metadata. 3. **`logging`, `sampling`, and `roots` are deprecated** — still functional, with a twelve-month minimum window, but new implementations should not adopt them. 4. **The TypeScript SDK moved to v2 under new package names.** `@modelcontextprotocol/sdk` is the v1 line and stops at 1.30.0. v2 ships as `@modelcontextprotocol/server` + `@modelcontextprotocol/client` (plus `/core` and an `/express`, `/fastify` or `/hono` adapter). The revision changed more than the checker covers: `server/discover` is now mandatory, all results carry a required `resultType`, the GET stream and `resources/subscribe` are replaced by `subscriptions/listen`, `ping` and `logging/setLevel` are gone, SSE resumability is removed, and `Mcp-Method` / `Mcp-Name` headers are required. **A clean checker run is not a migration.** Read the [changelog](https://modelcontextprotocol.io/specification/2026-07-28/changelog) before declaring a server done. **Do not tell anyone to upgrade `@modelcontextprotocol/sdk` to `^2`.** That package has never published a 2.x — the migration is to the new package names above. There *is* an official codemod, and it is a separate package: ```bash npx @modelcontextprotocol/codemod@latest v1-to-v2 . ``` The other Tier 1 SDKs moved differently: Python and C# to 2.x majors, Go to a 1.x minor. Check the actual package before advising a version. Work in this order: diagnose, triage, remediate, re-verify. The diagnosis step is scripted so it gives the same answer every time — resist the urge to skip it and eyeball the code, because the rule ids it emits are what the remediation guidance keys off. ## Step 1 — Diagnose Run the bundled checker. It needs nothing but Node — no install step. ```bash # Scan a repository (the richest signal; this is the one to start with) node scripts/mcpcheck.mjs --source /path/to/the/server # Probe a running endpoint node scripts/mcpcheck.mjs https://example.com/mcp # Probe a local dev server (disables the SSRF guard) node scripts/mcpcheck.mjs --local http://localhost:3000/mcp # Machine-readable, if you want to process the findings node scripts/mcpcheck.mjs --source . --json ``` Run **both** the source scan and a live probe when a server is actually running. They see different things and neither is a superset of the other: | | Source scan | Live probe | |---|---|---| | Sees | the code, `package.json`, `file:line` | headers, advertised capabilities, OAuth posture | | Finds | MCP001–005, **MCP007** (SDK line) | MCP001–005, **MCP006** (OAuth posture) | | Needs | a checkout | a reachable endpoint | Exit codes: `0` no critical findings · `1` at least one critical · `2` inconclusive (unreachable, blocked, or nothing to scan). ## Step 2 — Triage before you touch anything The source scan is **regex-based**. It greps for the patterns that correlate with each hazard, which means it reports signals, not proof. Two consequences worth internalising before you start editing: - **False positives are normal.** A file that merely mentions `initialize` in a comment, or a variable coincidentally named `sessionId`, will be flagged. The checker's own source flags itself for all five code rules, because the rules file contains the very strings it searches for. - **A clean scan is not a guarantee.** Session state can be spelled in ways the patterns don't catch — a `Map` keyed by something the code calls `clientKey`, for instance. So read each finding at its `file:line`, decide whether it is real, and say so explicitly before changing anything. A short triage table is a good artefact to produce here: rule, location, real or false positive, and why. Findings are graded: 100 minus 30 per critical, 15 per warning, 5 per info. Treat the letter grade as a headline for humans, not as the thing to optimize. Fixing the two criticals matters far more than the score moving from D to B. ## Step 3 — Remediate Read `references/remediation.md` for the per-rule guidance. It is organised by rule id, so go straight to the sections your findings named rather than reading it end to end. Sequence matters. Do it in this order, because later steps depend on earlier ones: 1. **MCP007 first** — move to the v2 packages and run the codemod. Doing this before the code changes means you refactor against the API you are going to keep, instead of refactoring twice. The codemod handles renames, not architecture; the type errors it leaves behind point straight at the MCP002 work. 2. **MCP002 (session state)** — the deepest change, and the one most likely to surface hidden design assumptions. 3. **MCP001 (handshake)** — largely mechanical once state is gone. 4. **MCP003/004/005 (deprecated capabilities)** — removals, each one localised. These are `warning`, not `critical`, and the deprecation window is at least twelve months. If the migration is already large, deferring them is a defensible call — say so rather than silently skipping them. 4. **MCP006 (OAuth posture)** — deployment-facing; independent of the rest. After each step, re-run the scan. Watching one rule at a time go quiet is a much better signal than a single run at the end where you can't tell which change fixed what. ## Step 4 — Verify Re-run both the source scan and, if a server is running, the live probe. Then check the things the scanner structurally cannot see: - Does the server still behave correctly when two consecutive requests land on **different instances**? This is the real test of statelessness, and no static scan can answer it. Run two instances behind anything that round-robins, or restart the process between requests. - Do the tests still pass, and do they still cover the paths you changed? - If you removed `sampling`, has the model-calling responsibility actually moved to the client, or has it just been deleted? ## Reporting back Close with a short summary in this shape — it is what someone reviewing the migration needs, and nothing more: ``` ## Migration summary - Before: — findings ( critical) - After: — findings ( critical) ## Changed - : ## Dismissed as false positives - at : ## Still open - ``` The "dismissed" section is the one people skip and later regret. If you decided a finding was noise, the reasoning needs to survive past the end of the session. ## A note on the spec itself The findings link to the canonical spec at `https://modelcontextprotocol.io/specification/2026-07-28`. When a fix involves an exact API signature or a precise header name, check it there rather than trusting a remembered detail — this skill describes the shape of each change, not a frozen copy of the specification. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [AlpayC](https://github.com/AlpayC) - **Source:** [AlpayC/mcp-migration-check](https://github.com/AlpayC/mcp-migration-check) - **License:** MIT - **Homepage:** https://mcp-migration-check.alpaycelik.workers.dev/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-alpayc-mcp-migration-check-mcp-migration - Seller: https://agentstack.voostack.com/s/alpayc - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.