In MCP, what does the error -32021 MissingRequiredClientCapabilityError mean?

## The problem it solves Since revision 2026-07-28, MCP has no handshake. A client states its capabilities in `io.modelcontextprotocol/clientCapabilities` inside `params._meta` on **every** request, and the server evaluates that declaration per request. That creates a failure mode the handshake era did not have in the same shape: a request can be perfectly well-formed and still be unservable, because the work the server would have to do requires something of the client that this request did not offer. `-32021` `MissingRequiredClientCapabilityError` is the error for exactly that case. ## Well-formed but insufficient It is worth separating three distinct failures, because interviewers like to see the distinction drawn cleanly: - **Malformed metadata** — a required `_meta` key such as `clientCapabilities` is absent entirely. That is `-32602` invalid params (HTTP 400 over Streamable HTTP). - **Well-formed but insufficient** — the capability object is present and valid, but does not contain what this request needs. That is `-32021`. - **Method does not exist** — `-32601`, with HTTP 404 on the HTTP transport. So `-32021` is not a schema-validation error. The client sent a legal declaration; it simply declared too little for what it then asked for. ## What the error carries The error's `data` object carries `requiredCapabilities`. That field is what makes the error useful: rather than the client guessing, the server names the capabilities the request would have needed. A client can compare that list against what it actually supports and decide, mechanically, whether a retry can possibly succeed. ## The client's options There are only two sensible reactions: 1. **The client does support the named capability but did not declare it on this call** — perhaps a code path built `_meta` from a narrower template, or the client suppresses interactive capabilities on background work. It re-issues the request with the capability declared. Because the request carries a new JSON-RPC id, this is an ordinary new request; nothing about the first attempt is remembered on the server. 2. **The client genuinely does not support it** — retrying is pointless. The right move is to surface the failure to the user or the calling agent with the server's `requiredCapabilities` in the message, so the human sees "this tool needs to be able to ask you questions and this client cannot". What is *not* a correct reaction is tearing down the transport. There is no session to reset, and reconnecting changes nothing: the next request would carry the same insufficient declaration. ## Why it exists in a stateless world Under the old handshake model a server learned client capabilities once and could refuse to expose incompatible functionality up front. Statelessness removes that vantage point — the server does not know, when it lists tools, what a future call will declare. So the check moves to call time, and the protocol needs a specific, machine-readable way to say "not with these capabilities". A generic invalid-params error would force clients to parse prose. A useful design consequence: capability requirements are a property of the *request*, not of the connection. The same client may legitimately declare interactive capabilities on a user-facing call and none at all on a background one, and the server evaluates each on its own terms. ## The reserved code band JSON-RPC leaves the `-32000` to `-32099` range to the application. MCP claims `-32020` through `-32099` for the specification itself, so implementations should not mint private errors in that band. Neighbouring specification codes include `-32020` for a header mismatch on the HTTP transport and `-32022` for an unsupported protocol revision. Grouping them makes the band easy to recognise: an error in the low `-320xx` range is the protocol talking, not the tool. ## Implementation guidance On the server side, check capability requirements before doing expensive work — you do not want to run half a tool and then discover the client cannot answer the question you need to ask. Populate `requiredCapabilities` accurately; a server that returns the error with an empty or vague `data` block gives the client nothing to act on. On the client side, treat `-32021` as a retryable-with-changes error in your error taxonomy, distinct from both hard failures and transient ones. Log the `requiredCapabilities` list, because in practice it is the fastest way to spot that some code path is building `_meta` incorrectly. And do not retry blindly in a loop: if the capability is one you do not implement, the second attempt will fail exactly like the first.