This release marks the completion of the full 2025-11-25 specification implementation, by introducing the support for Sampling with Tools and experimental client-side OAuth support. It also contains multiple bug fixes and improvements. Thanks to all contributors!
Client-side OAuth support
This release introduces experimental support for OAuth on the client side of the SDK. It aims to support the full scope of the current MCP specification for authorization. To use it, you need to compile the SDK with the -tags mcp_go_client_oauth flag. Some changes may still be applied to this new API, based on developer feedback. The functionality is planned to become stable in v1.5.0 release, expected by the end of March 2026. More details can be found at https://github.com/modelcontextprotocol/go-sdk/blob/main/docs/protocol.md#client.
- all: client side OAuth support by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/785
Sampling with Tools
Starting from this release, the server use the new CreateMessageWithTools method to create a sampling request to the client that contains tools that can be used by the client. On the client side, CreateMessageWithToolsHandler may be used to handle such requests and issue ToolUse responses to the server.
- mcp: implement sampling with tools by @findleyr in https://github.com/modelcontextprotocol/go-sdk/pull/699
Behavior changes
We have two important behavior changes that were introduced to fix a bug or improve security posture. They can be temporarily turned off by specifying a special MCPGODEBUG environment variable when running the SDK. Different options can be added together, separated by a comma.
Introduced DNS rebinding protection
The requests arriving via a localhost address (127.0.0.1, [::1]) that have a non-localhost Host header will be rejected to protect against DNS rebinding attacks. The protection can be disabled by specifying StreamableHTTPOptions.DisableLocalhostProtection, but it should be done only if security implications are understood (see documentation for the option).
This protection is a behavior change, as the protection is now enabled by default. Because of that, we have introduced an MCPGODEBUG option to bring back the previous default behavior for users that need more time to adjust. However, if possible, we recommend specifying DisableLocalhostProtection described above, as it is a more future-proof solution. The MCPGODEBUG option to remove this protection (disablelocalhostprotection=1) will be removed in v1.6.0.
- feat: add automatic DNS rebinding protection for localhost servers by @pcarleton in https://github.com/modelcontextprotocol/go-sdk/pull/760
Removed JSON content escaping when marshaling
By default encoding/json escapes the contents of the objects, which causes some servers to fail. We switched to no escaping by default, to be consistent with other SDKs. Since this is a behavior change, we introduced an MCPGODEBUG option to bring back the previous behavior for users that need more time to adjust to it. That option (jsonescaping=1) will be removed in v1.6.0.
- mcp: update JSON marshaling to not HTML-escape messages by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/769
Bug fixes
Security vulnerability caused by the case insensitive parsing behavior of encoding/json has been submitted (also release as a cherry pick in v1.3.1). Security advisory has been posted.
- all: use case-sensitive JSON unmarshaling by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/807
Other fixes:
- mcp: validation only for accept action by @CocaineCong in https://github.com/modelcontextprotocol/go-sdk/pull/766
- mcp: allow SSE messages with empty data (SEP-1699) by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/779
- jsonrpc2: fix Content-Length header parsing to be case-insensitive by @nithinputhenveettil in https://github.com/modelcontextprotocol/go-sdk/pull/789
- mcp: fix multi-select enum elicitation by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/795
- mcp: return 400 instead of 500 when body read fails in stateless mode by @roncodingenthusiast in https://github.com/modelcontextprotocol/go-sdk/pull/817
Enhancements
Notably, the SDK now supports the extensions field in client and server capabilities, which should enable creation of MCP Apps.
- mcp: add Extensions field to capabilities per SEP-2133 by @ymmt2005 in https://github.com/modelcontextprotocol/go-sdk/pull/794
Other enhancements:
- mcp: enforce retry limit when SSE stream makes no progress by @majiayu000 in https://github.com/modelcontextprotocol/go-sdk/pull/742
- mcp: export session missing error by @CocaineCong in https://github.com/modelcontextprotocol/go-sdk/pull/771
- fix: add JSON tags to ElicitationCapabilities fields by @awschmeder in https://github.com/modelcontextprotocol/go-sdk/pull/774
- mcp: improve http transports error handling and make transport work with any size message by @alexbumbacea in https://github.com/modelcontextprotocol/go-sdk/pull/734
- examples: bind auth-middleware server to localhost by default by @TheodorNEngoy in https://github.com/modelcontextprotocol/go-sdk/pull/784
Repository organization
Some effort was put into better organization of the repository, as well as making sure it's up to date and secure. As a highlight, the repository is not integrated with OSSF Scorecard with a positive score of 8.7. Additionally, the full conformance test suite is now run on every PR and push to main.
- chore: update licensing to Apache 2.0 for new contributions by @domdomegg in https://github.com/modelcontextprotocol/go-sdk/pull/750
- chore: update dependencies to newest versions, require Go 1.24 by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/765
- conformance: prepare the conformance test suite by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/764
- chore: use rand.Text and slog.DiscardHandler over intrernal implementation by @IAmSurajBobade in https://github.com/modelcontextprotocol/go-sdk/pull/773
- conformance: mark the new
dns-rebinding-protectionscenario as failing by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/775 - conformance: trigger conformance tests automatically by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/776
- mcp: finalize cleanup of Go 1.23, make Go version support explicit by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/780
- Use omitzero json tag for byte array field in ResourceContents, instead of omitempty by @IAmSurajBobade in https://github.com/modelcontextprotocol/go-sdk/pull/782
- Testing: use synctest for timing-dependent tests by @La002 in https://github.com/modelcontextprotocol/go-sdk/pull/756
- chore: add ROADMAP.md by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/788
- chore: bump node.js version for conformance test runs. by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/796
- Update issue templates by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/797
- chore: add an issue template for enhancements by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/798
- chore: setup dependabot to update github actions. by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/800
- build(deps): bump actions/setup-node from 4.1.0 to 6.2.0 by @dependabot[bot] in https://github.com/modelcontextprotocol/go-sdk/pull/801
- build(deps): bump actions/setup-go from 5.5.0 to 6.2.0 by @dependabot[bot] in https://github.com/modelcontextprotocol/go-sdk/pull/804
- build(deps): bump actions/checkout from 4.3.0 to 6.0.2 by @dependabot[bot] in https://github.com/modelcontextprotocol/go-sdk/pull/803
- Update SECURITY.md to use GitHub Security Advisories by @localden in https://github.com/modelcontextprotocol/go-sdk/pull/809
- chore: Configure OSSF Scorecard action by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/811
- chore: configure a simple AGENTS.md file and a skill for fixing GitHu… by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/810
- chore: update publish-docs permissions to be more targeted. by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/812
- chore: increase timeout for conformance server start. by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/813
- chore: update the version of the conformance suite. by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/814
- chore: Configure advanced CodeQL setup by @maciej-kisiel in https://github.com/modelcontextprotocol/go-sdk/pull/819
New Contributors
- @domdomegg made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/750
- @majiayu000 made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/742
- @awschmeder made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/774
- @alexbumbacea made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/734
- @TheodorNEngoy made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/784
- @pcarleton made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/760
- @nithinputhenveettil made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/789
- @ymmt2005 made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/794
- @localden made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/809
- @roncodingenthusiast made their first contribution in https://github.com/modelcontextprotocol/go-sdk/pull/817
Full Changelog: https://github.com/modelcontextprotocol/go-sdk/compare/v1.3.0...v1.4.0