MCP Error -32602: Fix Invalid Params Without Guessing
Error -32602 means a known method rejected the request shape; inspect the exact schema and error data instead of randomly renaming fields.
Table of contents
- What -32602 means
- Protocol params or tool arguments?
- A deterministic debugging workflow
- The mistakes that waste time
- Unknown tools and stale schemas
- Verification checklist
- FAQ
What -32602 means
-32602 is JSON-RPC Invalid Params: the method exists, but its parameters fail protocol or schema validation. The error concerns the request’s shape, not necessarily the server’s availability or your credentials.
JSON-RPC distinguishes “method not found” from “invalid method parameters.” A response with code -32602 therefore points you toward the parameter object: inspect its property names, nesting, required fields, and JSON types before changing anything else. The specification also permits an error object to include additional data, so preserve that detail instead of reducing the message to “bad request.” JSON-RPC 2.0 specification
In an MCP context, rejected parameters may belong to a lifecycle method, a protocol method, or a tool invocation. “MCP error invalid request parameters” and “MCP error 32602” describe the same diagnostic class, but the repair depends on which method returned it.
The practical rule is simple: identify the method, read the complete error, and compare the exact request with the schema currently advertised by the connected server.
Protocol params or tool arguments?
First determine whether the rejection happened during initialize, in another protocol method, or inside tools/call. The same code covers different layers, so a tool argument error and an initialization error can require completely different comparisons.
During initialization, inspect the protocol-level request and response expectations. MCP’s lifecycle specification defines initialization as the step where client and server establish protocol details and capabilities. A malformed initialization payload should therefore be investigated at that boundary rather than inside a tool definition. MCP lifecycle specification
For a protocol method such as tools/list, compare the method name, parameter envelope, optional values, and JSON types. For tools/call, inspect both the tool name and the arguments object. The method can be valid while one nested value is not.
| Failure location | Compare first | Typical evidence |
|---|---|---|
initialize | Protocol fields and JSON types | Error during connection setup |
| Protocol method | Method parameter envelope | Error before a tool runs |
tools/call | Tool name and arguments schema | Tool-specific Invalid Params |
Transport is a separate layer. The MCP transport specification describes how messages move between client and server; changing transport does not correct a malformed JSON object already rejected by the method handler. MCP transport specification
A deterministic debugging workflow
Capture tools/list, compare required names and JSON types, remove stale cached schemas, then replay the smallest request. The aim is to isolate one structural mismatch while preserving enough evidence to explain why the correction worked.
-
Save the evidence. Record the method, request parameters, response code, message, and any error data. Redact secret values in notes, but do not casually rewrite the request shape being investigated.
-
Locate the failing layer. Determine whether the error arrived during
initialize, a protocol method, ortools/call. This prevents a tool-schema investigation from distracting you from a lifecycle mismatch. -
Fetch a fresh tool list. When the failing method involves tools, obtain the current
tools/listresult from the connected server. Treat that response as the source of truth for available names and input schemas. -
Compare structure, not intent. Check exact property names, required versus optional fields, nesting, arrays versus objects, and JSON types. A human-readable value such as
"42"is not automatically equivalent to the number42. -
Remove stale state. Refresh cached tool definitions after a reconnect, server update, configuration change, or capability change. If the client continues sending an older schema, the server can reject a request that once worked.
-
Replay the smallest request. Change one structural detail, send the same method again, and compare the new response with the original. If the request succeeds, preserve the before-and-after evidence before making another change.
The official MCP debugging guide and the MCP Inspector repository are useful references when you need to observe requests and responses interactively. The discipline remains the same: inspect first, change one layer, and replay.
The mistakes that waste time
Changing transport, rotating credentials, or reinstalling the server cannot fix a field-name or JSON-type mismatch. Those actions may alter the environment, but they do not make an invalid parameter object conform to the method or tool schema.
A transport change is relevant when messages cannot be delivered or responses cannot be read. It is not the first explanation when the server returns a structured JSON-RPC error. Credential changes address authentication or authorization evidence, not a request whose property is misspelled or whose value has the wrong type.
Reinstallation can erase useful version and configuration evidence. Before changing versions, preserve the failing request, the fresh tool list, and the error data. If a version change becomes necessary, you can then distinguish a genuine server change from a repair that merely hid the original mismatch.
Avoid broad fixes that weaken security, such as disabling certificate verification to suppress a connection warning. Keep certificate validation and access controls intact while diagnosing the request shape. The MCP transport guidance helps separate message delivery concerns from protocol-level parameter validation. MCP transport specification
Unknown tools and stale schemas
An unknown tool can surface as -32602 because the tools/call method is valid but its name parameter is not. If the requested name is absent from the latest tools/list response, treat that absence as the primary evidence.
First refresh the server’s tool list and compare the exact name, including capitalization and punctuation. Then verify that the client is using the refreshed result instead of a cached definition. A stale schema can preserve an old tool name, old required fields, or an old argument type after the server’s available tools have changed.
The terminology is also worth checking when teams use “tool,” “resource,” and “prompt” interchangeably. MCPtrove’s MCP tool glossary can provide shared vocabulary, while the configuration validator and configuration doctor are practical next steps for narrowing configuration inconsistencies.
Do not infer that a tool is available because it appeared in an earlier session, documentation page, or local cache. The connected server’s current response is the relevant contract for the call you are about to make. The MCP official debugging guide likewise emphasizes observing the actual interaction rather than relying only on assumptions.
Verification checklist
A correct fix survives reconnect, a fresh tools/list, and both valid and deliberately invalid test inputs. Verification should show that the accepted request matches the current contract and that invalid input is still rejected safely.
Use this checklist:
- Reconnect the client and server without changing unrelated settings.
- Complete initialization successfully and preserve the response evidence.
- Fetch a fresh
tools/listresult after reconnect. - Confirm the target tool name and every required argument.
- Check each value’s JSON type, nesting, and array/object shape.
- Replay the smallest valid request with the same method and intended data.
- Send a deliberately invalid test input in a controlled test context and confirm that the server returns an appropriate validation error rather than executing the operation.
- Record the final request shape and the schema version or session context that produced it.
For a repeatable test plan, use MCPtrove’s guide on how to test an MCP server. If the error remains, compare the new error data with the original and return to the first layer where the payload diverges.
An initialization-specific -32602 can also be timing-related rather than a tool-argument mistake. The Python SDK issue documenting an initialization race is a reminder to inspect lifecycle sequencing before assuming every Invalid Params response came from tools/call. Python SDK initialization race report