Table of Contents

Enum McpErrorCode

Namespace
ModelContextProtocol
Assembly
ModelContextProtocol.Core.dll

Represents standard JSON-RPC error codes as defined in the MCP specification.

public enum McpErrorCode

Fields

HeaderMismatch = -32020

Indicates that HTTP headers do not match the corresponding values in the request body, or that required headers are missing or malformed.

This error is returned when a Streamable HTTP request fails header validation. Validation failures include:

  • A required standard header (Mcp-Method, Mcp-Name) is missing.
  • A header value does not match the corresponding request body value.
  • A Base64-encoded header value cannot be decoded.
  • A header value contains invalid characters.

This error code is in the JSON-RPC implementation-defined server error range (-32000 to -32099).

InternalError = -32603

Indicates that an internal error occurred while processing the request.

This error is used when the endpoint encounters an unexpected condition that prevents it from fulfilling the request.

InvalidParams = -32602

Indicates that the request parameters are invalid at the protocol level.

In MCP, this error is returned for protocol-level parameter validation failures in various contexts:

  • Tools: Unknown tool name or invalid protocol-level tool arguments.
  • Prompts: Unknown prompt name or missing required protocol-level arguments.
  • Resources: Unknown or unresolvable resource URI.
  • Pagination: Invalid or expired cursor values.
  • Logging: Invalid log level.
  • Tasks: Invalid or nonexistent task ID or invalid cursor.
  • Elicitation: Server requests an elicitation mode not declared in client capabilities.
  • Sampling: Missing tool result or tool results mixed with other content.

Note: Application-layer validation errors within tool/prompt/resource arguments should be reported as execution errors (for example, via IsError) rather than as protocol errors, allowing language models to receive error feedback and self-correct.

InvalidRequest = -32600

Indicates that the JSON payload does not conform to the expected Request object structure.

The request is considered invalid if it lacks required fields or fails to follow the JSON-RPC protocol.

MethodNotFound = -32601

Indicates that the requested method does not exist or is not available.

In MCP, this error is returned when a request is made for a method that requires a capability that has not been declared. This can occur in either direction:

  • A server returning this error when the client requests a capability it doesn't support (for example, requesting completions when the completions capability was not advertised).
  • A client returning this error when the server requests a capability it doesn't support (for example, requesting roots when the client did not declare the roots capability).
MissingRequiredClientCapability = -32021

Indicates that a request requires a client capability that was not declared in the request's _meta/io.modelcontextprotocol/clientCapabilities field.

Introduced by the 2026-07-28 protocol revision (SEP-2575). The error data MUST include a requiredCapabilities object describing the capabilities the server requires from the client to process the request. For HTTP, the response status code is 400 Bad Request.

ParseError = -32700

Indicates that the JSON received could not be parsed.

This error occurs when the input contains malformed JSON or incorrect syntax.

ResourceNotFound = -32002

Indicates that the requested resource could not be found.

Legacy error code for unresolvable resource URIs. Newer protocol versions report this condition with the standard JSON-RPC InvalidParams (-32602) instead. The SDK selects between the two automatically based on the negotiated protocol version, so older clients still see ResourceNotFound (-32002) and newer ones see InvalidParams.

New user code throwing McpProtocolException directly for unknown-resource conditions should prefer InvalidParams; the SDK will pass the value through unchanged.

UnsupportedProtocolVersion = -32022

Indicates that the request's declared protocol version is not supported by the server.

Introduced by the 2026-07-28 protocol revision (SEP-2575). The error data MUST include a supported array of protocol version strings the server supports and the original requested protocol version. For HTTP, the response status code is 400 Bad Request.

UrlElicitationRequired = -32042

Indicates that URL-mode elicitation is required to complete the requested operation.

This error is returned when a server operation requires additional user input through URL-mode elicitation before it can proceed. The error data must include the `data.elicitations` payload describing the pending elicitation(s) for the client to present to the user.

Common scenarios include OAuth authorization and other out-of-band flows that cannot be completed inside the MCP client.

Edit this page