The 12-point MCP migration audit checklist, before you touch any code
Twelve checks to run on an MCP server before migrating to the 2026-07-28 spec. The list I use on audits, with the warning signs that should stop you.
Most failed MCP migrations do not fail on the code. They fail because the team started writing before they knew what their server actually did.
Here is the list I run before quoting a migration. It is designed to be executed in a day on a mid-sized server, without changing anything. A static audit does not prove compatibility, it tells you where to look and what it will cost.
Part 1: hidden state
1. Every session read
Search for Mcp-Session-Id, sessionId, session_id and variants across the server, in-house clients, gateways and deployment config. Record each hit with file and line.
Warning sign: zero results on a server that has multi-step workflows. That means the state is there under a different name.
2. In-process state
Module-level variables, singletons, file-scope caches, global maps. For each one, answer a single question: does the correctness of the server depend on this value, or is it only an optimisation?
If correctness depends on it, it is state to externalise. If it is an optimisation, verify the no-cache path is tested.
3. Multi-call workflows
List the pairs or triples of tools that must be called in order. For each, note what travels between calls and where it lives.
This takes the longest and tells you the most. If nobody on the team can answer for a given workflow, that is where the migration will stall.
4. Background subscriptions and tasks
They held state, they are off the main request path, and they get missed every time. Check whether they survive an instance restart and an instance change.
5. User context
Where are tenant, plan, permissions and quotas resolved? If the answer is "at handshake", it now has to be rebuilt per request, and you need to estimate the extra database load.
Part 2: protocol conformance
6. The handshake
Find everything initialised once per connection and reused. See point 5, but also version negotiation and capabilities.
7. Lists that vary per client
Does tools/list return the same thing to everyone? If the list depends on plan or a feature flag, that is a product behaviour change to decide on, not just a technical fix.
8. The -32002 error code
String search for 32002, including tests, mocks, fixtures, public documentation and alerting rules.
9. The Mcp-Method and Mcp-Name headers
Two questions: does your server require them, and does it reject a request whose header does not match the body? The second is a security question, not a conformance one.
10. Deprecated capabilities
Inventory uses of sampling, roots and logging. Sampling is the only one with cost and compliance impact, so it gets handled separately.
Part 3: infrastructure and authorization
11. Session affinity
Look at the actual load balancer and gateway configuration, not the internal documentation. Sticky sessions, shared session store, body inspection for routing. Each of the three is a symptom, and each can disappear once state is externalised.
12. The OAuth chain
Three checks from the new revision: is the iss parameter present in authorization responses and validated client-side, is application_type specified at registration, are credentials stored keyed by issuer. And if you rely on Dynamic Client Registration, note that it is formally deprecated in favour of Client ID Metadata Documents.
The test that closes the audit
Once the list is filled in, one check remains, and it is the only one that proves anything.
Run a real multi-step scenario, round-robin across at least two instances, with no affinity, and kill an instance mid-scenario.
If it completes, externalisation is done. If it fails, hidden state remains, and the failing call tells you exactly where.
This test belongs in CI. Both failure modes of this migration, sticky affinity and dead deprecated code, stay silent until production. A single instance in development hides the first, a host with a model configured hides the second.
What the audit actually gives you
At the end of the twelve points you have three things you did not have:
- a finite list of files to change, which means a quote instead of a guess
- an order of operations, because some fixes unblock others
- a clean split between what is urgent (transport, headers, error code) and what has twelve months on it (deprecations)
That split is the difference between a two-week migration and a project that drags across a quarter.
Run it yourself, or send it to me
This checklist is public and it is complete. If you have the time, take it and work through it. It works.
If you would rather have someone who does only this run it for you: send me your repository or access to your server. Within 24 business hours you get a written diagnostic with all twelve points filled in, the files involved, the order of operations and a quote for the work. Free, no strings.
If you then decide to do the migration yourself using that report, that is fine too.
Ready to check? Get my MCP server audited →
Related reading
Got an MCP server to audit?
Five minutes to describe it. I reply within one business day with a first written diagnosis, free of charge.
Get my MCP server audited