Backwards compatibility and MCPGODEBUG

June 17, 2026 · View on GitHub

According to our compatibility promise, we can't break backward compatibility of the SDK API. However, sometimes we need to change the behavior of the SDK in a backward-incompatible way in order to fix bugs or security issues. In those cases we introduce temporary compatibility parameters, that can be used to opt-out of the new behavior. They are usually maintained for two minor release cycles and then removed.

The compatibility parameters are provided via the MCPGODEBUG environment variable. The value of the variable is a comma-separated list of parameter value assignments, e.g.:

MCPGODEBUG=parameter1=value1,parameter2=value2

`MCPGODEBUG` history

1.7.0

Options listed below were added and will be removed in the 1.9.0 version of the SDK.

customresnotfounderrcode added. If set to 1, ResourceNotFoundError will use the custom error code -32002 instead of the standard -32602 (Invalid Params), restoring the previous behavior. The default behavior was changed to align with SEP-2164 and the JSON-RPC specification.
hintomitempty added. If set to 1, ToolAnnotations JSON marshaling will omit ReadOnlyHint and IdempotentHint when their value is false, restoring the previous behavior. The default behavior was changed to always serialize these fields, since their Go types are bare bool (not *bool) and omitting false made it indistinguishable from unset.
allowsessionsinstateless added. If set to 1, stateless streamable HTTP servers will read the Mcp-Session-Id request header (or generate one via GetSessionID), set it on response headers, and accept DELETE requests, restoring the previous behavior. The default behavior was changed so that stateless servers ignore session IDs entirely and reject DELETE with 405.
nomethodnotfoundcodeinerror added. If set to 1, the jsonrpc2 layer will not include the MethodNotFound Error (-32601) in the error response when the requested method in STDIO transport is not found. The default behavior was changed to include the MethodNotFound Error in the error response when the requested method in STDIO transport is not found.
noprotocolerrorbody added. If set to 1, the streamable HTTP client will not attempt to decode the JSON-RPC error body of a non-2xx HTTP response, restoring the previous behavior. The default behavior was changed so that the client always attempts to surface the underlying JSON-RPC error.

1.6.1

Options listed below were added and will be removed in the 1.8.0 version of the SDK.

disablecontenttypecheck added. If set to 1, Content-Type validation on HTTP POST requests will be disabled, allowing requests with non-JSON or missing Content-Type headers. The default behavior is to validate that HTTP POST requests have Content-Type: application/json.

1.6.0

Options listed below were added and will be removed in the 1.8.0 version of the SDK.

seterroroverwrite added. If set to 1, SetError will always overwrite Content with the error text, restoring the previous behavior. The default behavior was changed to preserve existing Content if it has already been populated.
enableoriginverification added. If set to 1, default (zero-value) cross-origin protection will be applied when StreamableHTTPOptions.CrossOriginProtection is nil, restoring the behavior from v1.4.1-v1.5.0. The default behavior was changed to not enable cross-origin protection.
disablelocalhostprotection removal was postponed until 1.8.0, as it is now also used in the SSE transport.

Options below were removed:

jsonescaping, according to plan,
disablecrossoriginprotection, it was replaced by enableoriginverification after the default was changed to not enable cross-origin protection.

1.4.1

Options listed below will be removed in the 1.6.0 version of the SDK.

disablecrossoriginprotection added. If set to 1, newly added cross-origin protection will be disabled. The default behavior was changed to enable cross-origin protection.

1.4.0