modelcontextprotocol/go-sdk: the official Go SDK for MCP servers and clients

What modelcontextprotocol/go-sdk is for

MCP is a protocol for connecting language models to tools and data, and somebody has to implement the wire format in each language. This repository is the official Go implementation. It is aimed at Go engineers building the server side of an MCP integration, and at Go engineers building a client that talks to MCP servers.

The README frames the work plainly: the SDK "endeavors to implement the full MCP spec", and the docs/ directory maps spec features onto the packages. That mapping is the reason to pick this over a hand-rolled implementation. If you are writing a Go service that exposes a tool to a model host, or a Go program that calls tools on someone else's MCP server, this is the library the protocol authors maintain.

It is not a framework for building agents, and it is not a model client. It moves JSON-RPC messages and manages sessions. The intelligence stays outside.

The package split: mcp, jsonrpc, auth and oauthex

The SDK ships as four importable packages, and the split tells you where the boundaries are. The mcp package is the primary API for constructing and using clients and servers. The jsonrpc package is explicitly for users implementing their own transports, which means the default transports are already inside mcp and you only drop down a level if you need something the SDK does not provide. The auth package holds primitives for OAuth support, and oauthex holds protocol extensions such as ProtectedResourceMetadata.

That layering matters when you debug. A failure to reach a server is usually a transport problem in mcp, a malformed frame is a jsonrpc problem, and a rejected connection during authorization is an auth problem. Knowing which package owns the symptom shortens the loop.

The data flow is straightforward. A server is an mcp.Server with registered features, run over an mcp.Transport. A client is an mcp.Client that connects over a transport and receives a session. Calls travel over that session. In the README's client example, the transport is an mcp.CommandTransport wrapping an exec.Command, so the client spawns the server process and speaks over its stdin and stdout. HTTP is covered separately in examples/http/. The repository layout also shows a conformance/ directory and a design/ directory, so protocol conformance is treated as its own concern rather than folded into the main package.

Installing the Go SDK and running a first MCP server

The module path is github.com/modelcontextprotocol/go-sdk, and go.mod declares go 1.25.0. The README does not print an explicit go get line, but the import path is the module path, so a standard module fetch is what pulls it in.

Start by adding the dependency to your module:

go get github.com/modelcontextprotocol/go-sdk/mcp

The README's getting started example defines an input struct and an output struct, each field tagged with json and jsonschema, then registers a tool with mcp.AddTool and runs the server over stdin and stdout:

server := mcp.NewServer(&mcp.Implementation{Name: "greeter", Version: "v1.0.0"}, nil)
mcp.AddTool(server, &mcp.Tool{Name: "greet", Description: "say hi"}, SayHi)
if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
	log.Fatal(err)
}

The tool handler signature is fixed: it takes a context, an *mcp.CallToolRequest and the input struct, and returns an *mcp.CallToolResult, the output struct and an error. Returning a nil result and a populated output struct is the normal path; the README's handler returns nil for the result and an error only on failure.

The client side mirrors it. You build an mcp.Client, connect it with an mcp.CommandTransport, and call the tool by name with a map of arguments:

params := &mcp.CallToolParams{
	Name:      "greet",
	Arguments: map[string]any{"name": "you"},
}
res, err := session.CallTool(ctx, params)

After the call, check res.IsError before reading res.Content, and type-assert each item to *mcp.TextContent to get the text. The README's loop does exactly that. If you see the greeting printed, the session negotiated and the tool round-trip worked.

The version compatibility table is the part to read twice

MCP revisions are dated, and the SDK does not support every revision in every release. The README publishes a table mapping SDK version to spec version. v1.7.0 and later target the 2026-07-28 spec and also support 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. The v1.4.0 to v1.6.1 range tops out at 2025-11-25 with client side OAuth marked experimental. The v1.2.0 to v1.3.1 range has only partial 2025-11-25 support, with client side OAuth and sampling with tools unavailable. The v1.0.0 to v1.1.0 range stops at 2025-06-18.

The practical consequence: if the host you are integrating with negotiates a revision your SDK version does not list, you are not partially covered, you are outside the supported set. Pin deliberately and record which row you are on.

There is a second constraint in the same section. New releases of the SDK target only supported versions of Go, and the README points at the Go release policy rather than promising a wider range. With go.mod at go 1.25.0, a team on an older toolchain has to upgrade before it can build against the current SDK.

Deprecated features and where the SDK is the wrong tool

The README states that roots, sampling and logging are deprecated as of protocol version 2026-07-28 by SEP-2577. The SDK keeps supporting them for compatibility during a deprecation window of at least twelve months, and the feature documentation carries migration guidance.

If your design leans on sampling, that is a warning. You are building on a feature the protocol has moved to deprecate, and the twelve month window is a floor, not a guarantee. The same applies to roots and logging. A new project that can avoid all three should avoid them.

There are other cases where this SDK is the wrong choice. If you only need to call one HTTP endpoint on one MCP server and you control both ends, the protocol machinery is overhead. If you need a feature the SDK has not implemented yet, the README does not claim completeness, only that the project endeavors to implement the spec. And if your team cannot move to Go 1.25.0, the current releases will not build for you regardless of how well the design fits.

mcp-go and the other Go MCP SDKs

The README names the alternatives itself, which is unusual and useful. mcp-go, originally authored by Ed Zynda, is described as having inspired the design of this SDK and as remaining viable. mcp-golang and go-mcp are named alongside it.

The difference is stewardship, not shape. This SDK is the official implementation, maintained in collaboration with Google, and its docs/ directory is a feature-by-feature mapping to the MCP spec. The third party SDKs predate it and built their own API surface. Choosing between them is largely a question of which API you prefer and how closely you want the library's release cadence tied to spec revisions. The compatibility table here is the clearest signal of that tie: each SDK release declares which spec revisions it supports.

One caveat on the search data. People search for "go sdk" and land on AWS, Azure, Temporal, OpenAI, vSphere, Android and iOS SDKs, none of which are this project. If you arrived here looking for one of those, you are in the wrong repository.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-07. Releases are frequent: v1.8.0-pre.2 and v1.8.0-pre.1 both landed on 2026-09-04, and v1.7.0 on 2026-07-28. Pre-release tags are part of the normal cadence here, so a production pin should be to a stable tag rather than to whatever is newest.

Upgrade cost is dominated by the compatibility table. Moving from v1.6.1 to v1.7.0 changes the latest supported spec from 2025-11-25 to 2026-07-28, which is a protocol revision jump, not a patch. Moving within the v1.4.0 to v1.6.1 range keeps the same spec target and is the cheaper hop. Budget the protocol review, not just the dependency bump.

On licensing, the README states that the project is licensed under Apache 2.0 for new contributions, with existing code under MIT, and points at the LICENSE file for details. That is a split licence across the codebase rather than a single uniform one. What that means for your own distribution depends on which files you use and how you comply with each licence's notice requirements, so read LICENSE and treat the question as one for your own counsel rather than for this article.

Editorial conclusion

Adopt modelcontextprotocol/go-sdk if you are writing a Go MCP server or client and want the spec implemented by the group that owns it, with a documented mapping from spec version to SDK version. Do not adopt it if you need the roots, sampling or logging features to be long-lived, or if you cannot move to Go 1.25.0. Before you start, verify which MCP spec revision your counterparties negotiate, check that your module graph accepts the golang.org/x/tools v0.42.0 requirement, and read LICENSE in full because the repository states Apache 2.0 for new contributions with existing code under MIT.

Frequently asked questions

Official sources

1. Issues
2. modelcontextprotocol/go-sdk on GitHub
3. Project website
4. README
5. Releases