modelcontextprotocol/go-sdk
Watch
1
0
Fork
You've already forked go-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
go-sdk/internal/docs/mcpgodebug.src.md
Yaroslav 2b7c9937e6
 mcp: align resource not found error code with sep-2164 (#931) 
Change the error code returned by ResourceNotFoundError from -32002 to
-32602 (jsonrpc.CodeInvalidParams), aligning with
[SEP-2164](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2164).

* Not gated with a protocol version check, because the previous error
code was never formally specified and the behaviour varied across SDKs.
* In case clients which rely on the old error code exist, the previous
behaviour can be restored with `MCPGODEBUG=customresnotfounderrcode=1`.
* `CodeResourceNotFound` deprecated since its only purpose going forward
is backward compatibility. The new code should use
`jsonrpc.CodeInvalidParams` directly.
* `CodeResourceNotFound` changed to `var` so it can stay in sync with
`ResourceNotFoundError` and existing code doing `code ==
mcp.CodeResourceNotFound` keeps working in both the default and compat
modes.
2026-05-05 16:20:02 +02:00

3.1 KiB
Raw Blame History

Backwards compatibility and MCPGODEBUG

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.

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

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

  • jsonescaping added. If set to 1, JSON marshaling will preserve the previous behavior of escaping HTML characters in JSON strings. The default behavior was changed to not escape HTML characters, to be consistent with other SDKs.

  • disablelocalhostprotection added. If set to 1, newly added DNS rebinding protection will be disabled. The default behavior was changed to enable DNS rebinding protection. The protection can also be disabled by setting the DisableLocalhostProtection field in the StreamableHTTPOptions or SSEOptions struct to true, which is the recommended way to disable the protection long term. Removal of this option was postponed until 1.8.0.