-32002 becomes -32602: the change that breaks clients silently

This is the smallest change in the MCP 2026-07-28 spec, and the one that generates the most annoying tickets.

MCP had introduced -32002 as a custom error code for a missing resource. JSON-RPC 2.0 already had -32602 for invalid params. The two overlapped. The new revision drops the duplicate and keeps the standard code.

Why it hurts

Because nothing crashes.

A client that compares against the literal -32002 to detect a missing resource does not throw when the code changes. It just falls into its generic branch. Depending on how it is written, that gives you:

• a raw error string shown to the user instead of a domain message
• retry logic firing where it should not, because the error is no longer identified as terminal
• a silent fallback returning an empty result instead of an error
• an alert that never fires, because technically nothing failed

None of this shows up on an error dashboard. It shows up three weeks later in a support ticket saying the agent "sometimes answers nonsense".

What to search for

A string search across the whole repository for 32002. Not just the server.

Also check:

• your in-house clients and integration scripts
• internal SDKs or wrappers around the official SDK
• tests, including fixtures and mocks that freeze the old code
• public documentation, if you document error codes
• alerting rules, if you count errors by code

Tests are the sneakiest case. A test asserting your server returns -32002 keeps passing if you change nothing, and fails the moment you fix the server. Plenty of teams then fix the test in the wrong direction, by putting the old value back.

The fix

Server side, replace emission of -32002 with -32602.

Client side, two options. The fastest is to accept both values during the transition, which lets you talk to migrated and unmigrated servers. The cleanest is to stop comparing raw numeric codes at all and go through a constant or an SDK helper, so the next change costs you one place instead of twenty.

If you only do one thing: stop leaving numeric literals in branching logic. That is what made this change expensive.

The test that verifies it

Call a tool with a reference to a resource that does not exist, and look at what the client shows the end user. Not what the server returns, what the user sees.

If the message is generic where it should be domain-specific, your error handling chain no longer recognises the error.

How many are left in your code

This is one of seven changes in the 2026-07-28 revision. The audit combs the repository, including in-house clients and tests. Within 24 business hours you get the list and a quote.

Ready to check? Get my MCP server audited →

Related reading

• How to migrate an MCP server to the 2026-07-28 spec
• The 12-point MCP migration audit checklist