MCP Error Code Lookup. What the number means and what to try.
Type an error code or words from the message. See what it means, the usual cause in MCP and what to try, including the codes the 2026-07-28 specification added and retired.
Look up an error code
With or without the minus sign. Codes checked against the 2026-07-28 specification.
12 codes and ranges
-32700 Parse error
JSON-RPC 2.0The receiver got text that is not valid JSON.
- Why you see it
- A message was cut off or mangled. On stdio, the usual cause is a server that prints logs or banners to stdout, which must carry only MCP messages.
- What to try
- Send logs to stderr, not stdout. Check proxies or wrappers that might change the body.
Source · Our guide: The stdio transport
-32600 Invalid Request
JSON-RPC 2.0The JSON is valid but is not a valid request object.
- Why you see it
- A missing "jsonrpc": "2.0", a missing method, or an id of null. MCP adds a rule that request IDs must not be null.
- What to try
- Compare the message with the request shape in the spec. Use an official SDK rather than building messages by hand.
Source · Our guide: JSON-RPC messages in MCP
-32601 Method not found
JSON-RPC 2.0The receiver does not support the method that was called.
- Why you see it
- The server does not offer that feature, such as completion, or the client calls a method that a newer spec removed (for example ping or logging/setLevel in 2026-07-28).
- What to try
- Check the server’s capabilities before calling, and check which spec version each side speaks.
Source · Our guide: MCP capabilities
-32602 Invalid params
JSON-RPC 2.0The method exists but its parameters are wrong.
- Why you see it
- An unknown tool or prompt name, missing required arguments, a missing required _meta field (the 2026-07-28 spec requires the protocol version and client capabilities on every request), an invalid cursor, an unknown log level, or a resource that does not exist.
- What to try
- Read the error message and data. For a missing resource, the URI is usually in data. For a bad cursor, restart the listing without one.
- History
- Since 2026-07-28 this is also the code for "resource not found", which used to be -32002.
Source · Our guide: MCP resources explained
-32603 Internal error
JSON-RPC 2.0Something failed inside the receiver.
- Why you see it
- An unhandled exception in the server code, or an SDK turning a plain error into a JSON-RPC error.
- What to try
- Check the server’s logs (stderr for stdio servers). Problems a model could fix, such as a bad date, belong in a tool result with isError: true instead.
Source · Our guide: MCP tool errors
-32020 HeaderMismatch
MCPOn Streamable HTTP, the MCP request headers do not match the JSON-RPC body.
- Why you see it
- The Mcp-Method or Mcp-Name header is missing or disagrees with the method or name in the body. The 2026-07-28 spec requires these headers and has servers reject mismatches with HTTP 400.
- What to try
- Update the client SDK, or check that a proxy is not rewriting the body or dropping headers.
- History
- New in 2026-07-28. It was numbered -32001 while that version was a draft.
Source · Our guide: Streamable HTTP
-32021 MissingRequiredClientCapability
MCPThe request needs a client capability the client did not declare.
- Why you see it
- For example, a tool that has to ask the user a question (elicitation), sent by a client whose request did not list that capability. The error’s data.requiredCapabilities lists what is missing. On HTTP the status is 400.
- What to try
- Use a client that supports the capability and declares it, or change the server so it can work without it.
- History
- New in 2026-07-28. It was numbered -32003 while that version was a draft.
Source · Our guide: MCP capabilities
-32022 UnsupportedProtocolVersion
MCPThe server does not support the protocol version named in the request.
- Why you see it
- The client and server speak different spec versions. The error’s data lists the versions the server supports and the one requested.
- What to try
- The client should retry with a version from the supported list, or tell the user if none match. Getting this code means the server is a modern (2026-07-28 or later) server.
- History
- New in 2026-07-28. It was numbered -32004 while that version was a draft.
Source · Our guide: MCP versioning and deprecation
-32002 Resource not found (retired)
MCPRetiredA resources/read for a URI that does not exist, in spec versions up to 2025-11-25.
- Why you see it
- You are talking to a server that implements an older spec version.
- What to try
- Servers on 2026-07-28 must return -32602 instead and must not emit -32002. Clients should still accept -32002 from older servers.
- History
- Used up to 2025-11-25. Replaced by -32602 in 2026-07-28 and reserved so it is never reused.
Source · Our guide: MCP resources explained
-32042 URL elicitation required (retired)
MCPRetiredIn 2025-11-25 only, the server needed the user to complete a step at a URL first.
- Why you see it
- You are talking to a 2025-11-25 server that uses URL-mode elicitation.
- What to try
- In 2026-07-28 a server asks for input with an input_required result instead (multi round-trip requests). Implementations of 2026-07-28 must not emit -32042.
- History
- Defined in 2025-11-25 only, then retired and reserved.
Source · Our guide: MCP elicitation
-32000 to -32019 Legacy implementation-defined range
Reserved rangeCodes SDKs and servers used before MCP set an allocation policy.
- Why you see it
- An SDK or server is using its own code, such as a timeout or a connection error. Apart from -32002, the spec says receivers must not assume these codes mean anything specific.
- What to try
- Read the error message and the server or SDK docs. New implementations should not use this range.
-32020 to -32099 Reserved for the MCP specification
Reserved rangeCodes only the MCP spec can define.
- Why you see it
- If you see a code here that is not listed above, the server is breaking the spec, which forbids emitting undefined codes in this range, or it implements a newer version.
- What to try
- Check the latest specification. Your own application errors should use codes outside -32768 to -32000.
Not every failure is a JSON-RPC error. When a tool runs but fails (an API error, a bad date), MCP servers return a normal result with isError: true so the model can read it and try again. See MCP tool errors.
Sources: JSON-RPC 2.0 specification, the MCP 2026-07-28 error codes section and changelog, checked 28 October 2026.
How to use it
How to use the MCP Error Code Lookup
Paste the number from the error, with or without the minus sign, or a word from the message such as header or not found. The list filters as you type.
Each code shows where it comes from (JSON-RPC 2.0 or MCP), the usual cause, what to try and any history, such as resource not found moving from -32002 to -32602.
Limits
What it can't tell you
It explains codes defined by JSON-RPC 2.0 and the MCP specification. Servers and SDKs can return their own codes too, especially between -32000 and -32019, and those mean whatever that software says.
Many failures are not JSON-RPC errors at all. A tool that runs but fails returns a normal result with isError: true, and HTTP problems such as 401 or 403 come from the transport and sign-in layer.
FAQ
Common questions
What is error -32602 in MCP?
What does -32022 mean?
What happened to -32002?
Why do I get -32601 Method not found?
Project Managers who will work with you on your project!
Irina S.
Benjamin G.
David G.
Jeanette M.
Mark S.
Maryna P.
Wondering what this costs? Every service has published pricing, and you don't need a discovery call to see it.
View pricingBuilding an MCP server?
We build MCP servers and integrations with Claude Code, tested against the current specification and reviewed by an engineer before anything ships.
See MCP Development →
