MCP 2026-07-28 one lesson per page
23 lessons
ReviewAll domainsTrack 2 · 14 / 14

Putting it together: migrating one server

The whole revision as a to-do list, in the order you'd actually do it. If you can explain each line without scrolling back, you're ready.

Listen to this lessonAudio overview in Gemini Notebook · about 15–25 min · opens in a new tab

The migration, in order

  1. Find all per-session state. Turn each item into a handle passed as a tool argument, or remove it.
  2. Find every place the server talks first (elicitation, sampling, roots) and turn it into input_required with a protected requestState.
  3. Make handlers re-entrant, so a retry carrying inputResponses resumes instead of restarting.
  4. Implement server/discover. It's mandatory.
  5. Read version and capabilities from each request's _meta. Return -32602, -32021 or -32022 correctly.
  6. Add resultType to every result, and ttlMs plus cacheScope to lists, reads and discovery.
  7. Validate HTTP headers against the body: 400 with -32020 on mismatch.
  8. Replace GET and subscribe with subscriptions/listen, tagging notifications with subscriptionId.
  9. Treat a closed stream as cancellation, and delete replay and Last-Event-ID code.
  10. Remove ping and setLevel, log only when logLevel is present, and switch not-found to -32602.
  11. Move long-running work to the Tasks extension where it fits.
  12. Decide: dual-era or modern-only. If modern-only, make the error to initialize name your supported versions.

Error codes to know

-32020 header mismatch · -32021 missing client capability · -32022 unsupported version · -32602 invalid params and resource not found · -32601 method not found (HTTP 404)

The one-line summary

Every request stands alone, the server never initiates, and state is an explicit handle.

Next

Read the official changelog once more, then move on to security best practices: Security & Governance is 24% of the MCPA exam.

Check yourself

Answer all 2 correctly and this lesson is marked as learned.

Q1A legacy client sends initialize to a modern-only HTTP server. What is the most useful thing the server can do?

Q2Which of these is still allowed in 2026-07-28?

Read the spec

Key changes (changelog) ↗Full specification ↗

Feedback or a correction? Email diego [at] diegozuluaga [dot] dev or open an issue on GitHub.

Content CC BY 4.0 · Code MIT

Tip: ← and → move between lessons. Hover any heading and press # to copy a link to it.