Go SDK: Design

[findleyr]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Hi everyone 👋! This is a design discussion for the Go MCP SDK, following up on /discussions/224, where we (the Go team) volunteered to help contribute an official SDK.

In the original discussion, many people expressed support for a Go SDK, which is fantastic. With so much interest, we felt that it was more important than ever to start with a concrete design; otherwise we’d risk a lot of churn as we all worked out the APIs incrementally.

We analyzed a number of SDKs in Go and other languages to arrive at the design below. Wherever possible, we tried to align with the very successful mark3labs/mcp-go. However, as you’ll see, we diverged in a number of ways in order to keep the APIs minimal and to be cautious about future spec evolution. We address the differences between this design and mcp-go throughout the document.

Our goal is to make sure that there is a good official SDK for Go. We want your feedback. If discussion reveals that some of the APIs below aren’t right, we’ll change them.

To achieve this, let’s proceed as follows:

• Start a comment thread here to discuss aspects of the design. As much as possible, try to keep threads focused on one area. Prefer to reuse existing threads rather than creating new ones.
• If compelling arguments emerge that the design needs to be changed, we’ll update it. We’ll also keep a log of any such changes.
• We hope that we can reach consensus within a reasonable amount of time (a couple of weeks, perhaps?). Once that happens, we’ll finalize the design and move to the execution phase, where we create github.com/modelcontextprotocol/go-sdk.

Thanks!
-Rob

Changelog

• 2025-06-02: Added a Meta type for metadata, a section on "Community and Governance", and revised the signature of ToolHandler and CallTool. changes.
• 2025-05-22: Updated middleware per discussion; updated logging to include a general logging handler in addition to a slog.logger. changes

Go SDK Design

This document discusses the design of a Go SDK for the model context protocol. The golang.org/x/tools/internal/mcp package contains a prototype that we built to explore the MCP design space. Many of the ideas there are present in this document. However, we have diverged from and expanded on the APIs of that prototype, and this document should be considered canonical.

Similarities and differences with mark3labs/mcp-go (and others)

The most popular unofficial MCP SDK for Go is mark3labs/mcp-go. As of this writing, it is imported by over 400 packages that span over 200 modules.

We admire mcp-go, and where possible tried to align with its design. However, the APIs here diverge in a number of ways in order to keep the official SDK minimal, allow for future spec evolution, and support additional features. We have noted significant differences from mcp-go in the sections below. Although the API here is not compatible with mcp-go, translating between them should be straightforward in most cases. (Later, we will provide a detailed translation guide.)

Thank you to everyone who contributes to mcp-go and other Go SDKs. We hope that we can collaborate to leverage all that we've learned about MCP and Go in an official SDK.

Requirements

These may be obvious, but it's worthwhile to define goals for an official MCP SDK. An official SDK should aim to be:

• complete: it should be possible to implement every feature of the MCP spec, and these features should conform to all of the semantics described by the spec.
• idiomatic: as much as possible, MCP features should be modeled using features of the Go language and its standard library. Additionally, the SDK should repeat idioms from similar domains.
• robust: the SDK itself should be well tested and reliable, and should enable easy testability for its users.
• future-proof: the SDK should allow for future evolution of the MCP spec, in such a way that we can (as much as possible) avoid incompatible changes to the SDK API.
• extensible: to best serve the previous four concerns, the SDK should be minimal. However, it should admit extensibility using (for example) simple interfaces, middleware, or hooks.

Design

In the sections below, we visit each aspect of the MCP spec, in approximately the order they are presented by the official spec For each, we discuss considerations for the Go implementation, and propose a Go API.

Foundations

Package layout

In the sections that follow, it is assumed that most of the MCP API lives in a single shared package, the mcp package. This is inconsistent with other MCP SDKs, but is consistent with Go packages like net/http, net/rpc, or google.golang.org/grpc. We believe that having a single package aids discoverability in package documentation and in the IDE. Furthermore, it avoids arbitrary decisions about package structure that may be rendered inaccurate by future evolution of the spec.

Functionality that is not directly related to MCP (like jsonschema or jsonrpc2) belongs in a separate package.

Therefore, this is the core package layout, assuming github.com/modelcontextprotocol/go-sdk as the module path.

• github.com/modelcontextprotocol/go-sdk/mcp: the bulk of the user facing API
• github.com/modelcontextprotocol/go-sdk/jsonschema: a jsonschema implementation, with validation
• github.com/modelcontextprotocol/go-sdk/internal/jsonrpc2: a fork of x/tools/internal/jsonrpc2_v2

The JSON-RPC implementation is hidden, to avoid tight coupling. As described in the next section, the only aspects of JSON-RPC that need to be exposed in the SDK are the message types, for the purposes of defining custom transports. We can expose these types by promoting them from the mcp package using aliases or wrappers.

Difference from mcp-go: Our mcp package includes all the functionality of mcp-go's mcp, client, server and transport packages.

JSON-RPC and Transports

The MCP is defined in terms of client-server communication over bidirectional JSON-RPC message streams. Specifically, version 2025-03-26 of the spec defines two transports:

• stdio: communication with a subprocess over stdin/stdout.
• streamable http: communication over a relatively complicated series of text/event-stream GET and HTTP POST requests.

Additionally, version 2024-11-05 of the spec defined a simpler (yet stateful) HTTP transport:

• sse: client issues a hanging GET request and receives messages via text/event-stream, and sends messages via POST to a session endpoint.

Furthermore, the spec states that it must be possible for users to define their own custom transports.

Given the diversity of the transport implementations, they can be challenging to abstract. However, since JSON-RPC requires a bidirectional stream, we can use this to model the MCP transport abstraction:

// A Transport is used to create a bidirectional connection between MCP client
// and server.
type Transport interface {
    Connect(ctx context.Context) (Stream, error)
}

// A Stream is a bidirectional jsonrpc2 Stream.
type Stream interface {
    Read(ctx context.Context) (JSONRPCMessage, error)
    Write(ctx context.Context, JSONRPCMessage) error
    Close() error
}

Methods accept a Go Context and return an error, as is idiomatic for APIs that do I/O.

A Transport is something that connects a logical JSON-RPC stream, and nothing more. Streams must be closeable in order to implement client and server shutdown, and therefore conform to the io.Closer interface.

Other SDKs define higher-level transports, with, for example, methods to send a notification or make a call. Those are jsonrpc2 operations on top of the logical stream, and the lower-level interface is easier to implement in most cases, which means it is easier to implement custom transports.

For our prototype, we've used an internal jsonrpc2 package based on the Go language server gopls, which we propose to fork for the MCP SDK. It already handles concerns like client/server connection, request lifecycle, cancellation, and shutdown.

Differences from mcp-go: The Go team has a battle-tested JSON-RPC implementation that we use for gopls, our Go LSP server. We are using the new version of this library as part of our MCP SDK. It handles all JSON-RPC 2.0 features, including cancellation.

The Transport interface here is lower-level than that of mcp-go, but serves a similar purpose. We believe the lower-level interface is easier to implement.

stdio transports

In the MCP Spec, the stdio transport uses newline-delimited JSON to communicate over stdin/stdout. It's possible to model both client side and server side of this communication with a shared type that communicates over an io.ReadWriteCloser. However, for the purposes of future-proofing, we should use a different types for client and server stdio transport.

The CommandTransport is the client side of the stdio transport, and connects by starting a command and binding its jsonrpc2 stream to its stdin/stdout.

// A CommandTransport is a [Transport] that runs a command and communicates
// with it over stdin/stdout, using newline-delimited JSON.
type CommandTransport struct { /* unexported fields */ }

// NewCommandTransport returns a [CommandTransport] that runs the given command
// and communicates with it over stdin/stdout.
func NewCommandTransport(cmd *exec.Command) *CommandTransport

// Connect starts the command, and connects to it over stdin/stdout.
func (*CommandTransport) Connect(ctx context.Context) (Stream, error) {

The StdIOTransport is the server side of the stdio transport, and connects by binding to os.Stdin and os.Stdout.

// A StdIOTransport is a [Transport] that communicates using newline-delimited
// JSON over stdin/stdout.
type StdIOTransport struct { /* unexported fields */ }

func NewStdIOTransport() *StdIOTransport

func (t *StdIOTransport) Connect(context.Context) (Stream, error)

HTTP transports

The HTTP transport APIs are even more asymmetrical. Since connections are initiated via HTTP requests, the client developer will create a transport, but the server developer will typically install an HTTP handler. Internally, the HTTP handler will create a logical transport for each new client connection.

Importantly, since they serve many connections, the HTTP handlers must accept a callback to get an MCP server for each new session. As described below, MCP servers can optionally connect to multiple clients. This allows customization of per-session servers: if the MCP server is stateless, the user can return the same MCP server for each connection. On the other hand, if any per-session customization is required, it is possible by returning a different Server instance for each connection.

// SSEHTTPHandler is an http.Handler that serves SSE-based MCP sessions as defined by
// the 2024-11-05 version of the MCP protocol.
type SSEHTTPHandler struct { /* unexported fields */ }

// NewSSEHTTPHandler returns a new [SSEHTTPHandler] that is ready to serve HTTP.
//
// The getServer function is used to bind created servers for new sessions. It
// is OK for getServer to return the same server multiple times.
func NewSSEHTTPHandler(getServer func(request *http.Request) *Server) *SSEHTTPHandler

func (*SSEHTTPHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

// Close prevents the SSEHTTPHandler from accepting new sessions, closes active
// sessions, and awaits their graceful termination.
func (*SSEHTTPHandler) Close() error

Notably absent are options to hook into low-level request handling for the purposes of authentication or context injection. These concerns are instead handled using standard HTTP middleware patterns. For middleware at the level of the MCP protocol, see Middleware below.

By default, the SSE handler creates messages endpoints with the ?sessionId=... query parameter. Users that want more control over the management of sessions and session endpoints may write their own handler, and create SSEServerTransport instances themselves for incoming GET requests.

// A SSEServerTransport is a logical SSE session created through a hanging GET
// request.
//
// When connected, it returns the following [Stream] implementation:
//   - Writes are SSE 'message' events to the GET response.
//   - Reads are received from POSTs to the session endpoint, via
//     [SSEServerTransport.ServeHTTP].
//   - Close terminates the hanging GET.
type SSEServerTransport struct { /* ... */ }

// NewSSEServerTransport creates a new SSE transport for the given messages
// endpoint, and hanging GET response.
//
// Use [SSEServerTransport.Connect] to initiate the flow of messages.
//
// The transport is itself an [http.Handler]. It is the caller's responsibility
// to ensure that the resulting transport serves HTTP requests on the given
// session endpoint.
//
// Most callers should instead use an [SSEHandler], which transparently handles
// the delegation to SSEServerTransports.
func NewSSEServerTransport(endpoint string, w http.ResponseWriter) *SSEServerTransport

// ServeHTTP handles POST requests to the transport endpoint.
func (*SSEServerTransport) ServeHTTP(w http.ResponseWriter, req *http.Request)

// Connect sends the 'endpoint' event to the client.
// See [SSEServerTransport] for more details on the [Stream] implementation.
func (*SSEServerTransport) Connect(context.Context) (Stream, error)

The SSE client transport is simpler, and hopefully self-explanatory.

type SSEClientTransport struct { /* ... */ }

// NewSSEClientTransport returns a new client transport that connects to the
// SSE server at the provided URL.
func NewSSEClientTransport(url string) (*SSEClientTransport, error) {

// Connect connects through the client endpoint.
func (*SSEClientTransport) Connect(ctx context.Context) (Stream, error)

The Streamable HTTP transports are similar to the SSE transport, albeit with a
more complicated implementation. For brevity, we summarize only the differences
from the equivalent SSE types:

// The StreamableHTTPHandler interface is symmetrical to the SSEHTTPHandler.
type StreamableHTTPHandler struct { /* unexported fields */ }
func NewStreamableHTTPHandler(getServer func(request *http.Request) *Server) *StreamableHTTPHandler
func (*StreamableHTTPHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
func (*StreamableHTTPHandler) Close() error

// Unlike the SSE transport, the streamable transport constructor accepts a
// session ID, not an endpoint, along with the HTTP response for the request
// that created the session. It is the caller's responsibility to delegate
// requests to this session.
type StreamableServerTransport struct { /* ... */ }
func NewStreamableServerTransport(sessionID string, w http.ResponseWriter) *StreamableServerTransport
func (*StreamableServerTransport) ServeHTTP(w http.ResponseWriter, req *http.Request)
func (*StreamableServerTransport) Connect(context.Context) (Stream, error)

// The streamable client handles reconnection transparently to the user.
type StreamableClientTransport struct { /* ... */ }
func NewStreamableClientTransport(url string) *StreamableClientTransport {
func (*StreamableClientTransport) Connect(context.Context) (Stream, error)

Differences from mcp-go: In mcp-go, server authors create an MCPServer, populate it with tools, resources and so on, and then wrap it in an SSEServer or StdioServer. Users can manage their own sessions with RegisterSession and UnregisterSession. Rather than use a server constructor to get a distinct server for each connection, there is a concept of a "session tool" that overlays tools for a specific session.

Here, we tried to differentiate the concept of a Server, HTTPHandler, and Transport, and provide per-session customization through either the getServer constructor or middleware. Additionally, individual handlers and transports here have a minimal API, and do not expose internal details. (Open question: are we oversimplifying?)

Other transports

We also provide a couple of transport implementations for special scenarios. An InMemoryTransport can be used when the client and server reside in the same process. A LoggingTransport is a middleware layer that logs RPC logs to a desired location, specified as an io.Writer.

// An InMemoryTransport is a [Transport] that communicates over an in-memory
// network connection, using newline-delimited JSON.
type InMemoryTransport struct { /* ... */ }

// NewInMemoryTransports returns two InMemoryTransports that connect to each
// other.
func NewInMemoryTransports() (*InMemoryTransport, *InMemoryTransport)

// A LoggingTransport is a [Transport] that delegates to another transport,
// writing RPC logs to an io.Writer.
type LoggingTransport struct { /* ... */ }
func NewLoggingTransport(delegate Transport, w io.Writer) *LoggingTransport

Protocol types

Types needed for the protocol are generated from the JSON schema of the MCP spec.

These types will be included in the mcp package, but will be unexported unless they are needed for the user-facing API. Notably, JSON-RPC request types are elided, since they are handled by the jsonrpc2 package and should not be observed by the user.

For user-provided data, we use json.RawMessage or map[string]any, depending on the use case.

For union types, which can't be represented in Go (specifically Content and ResourceContents), we prefer distinguished unions: struct types with fields corresponding to the union of all properties for union elements.

For brevity, only a few examples are shown here:

type ReadResourceParams struct {
	URI string `json:"uri"`
}

type CallToolResult struct {
	Meta    Meta      `json:"_meta,omitempty"`
	Content []Content `json:"content"`
	IsError bool      `json:"isError,omitempty"`
}

// Content is the wire format for content.
//
// The Type field distinguishes the type of the content.
// At most one of Text, MIMEType, Data, and Resource is non-zero.
type Content struct {
	Type     string            `json:"type"`
	Text     string            `json:"text,omitempty"`
	MIMEType string            `json:"mimeType,omitempty"`
	Data     []byte            `json:"data,omitempty"`
	Resource *ResourceContents `json:"resource,omitempty"`
}

// NewTextContent creates a [Content] with text.
func NewTextContent(text string) *Content
// etc.

The Meta type includes a map[string]any for arbitrary data, and a ProgressToken field.

Differences from mcp-go: these types are largely similar, but our type generator flattens types rather than using struct embedding.

Clients and Servers

Generally speaking, the SDK is used by creating a Client or Server instance, adding features to it, and connecting it to a peer.

However, the SDK must make a non-obvious choice in these APIs: are clients 1:1 with their logical connections? What about servers? Both clients and servers are stateful: users may add or remove roots from clients, and tools, prompts, and resources from servers. Additionally, handlers for these features may themselves be stateful, for example if a tool handler caches state from earlier requests in the session.

We believe that in the common case, any change to a client or server, such as adding a tool, is intended for all its peers. It is therefore more useful to allow multiple connections from a client, and to a server. This is similar to the net/http packages, in which an http.Client and http.Server each may handle multiple unrelated connections. When users add features to a client or server, all connected peers are notified of the change.

Supporting multiple connections to servers (and from clients) still allows for stateful components, as it is up to the user to decide whether or not to create distinct servers/clients for each connection. For example, if the user wants to create a distinct server for each new connection, they can do so in the getServer factory passed to transport handlers.

Following the terminology of the spec, we call the logical connection between a client and server a "session." There must necessarily be a ClientSession and a ServerSession, corresponding to the APIs available from the client and server perspective, respectively.

Client                                                   Server
  ⇅                          (jsonrpc2)                     ⇅
ClientSession ⇄ Client Transport ⇄ Server Transport ⇄ ServerSession

Sessions are created from either Client or Server using the Connect method.

type Client struct { /* ... */ }
func NewClient(name, version string, opts *ClientOptions) *Client
func (*Client) Connect(context.Context, Transport) (*ClientSession, error)
func (*Client) Sessions() iter.Seq[*ClientSession]
// Methods for adding/removing client features are described below.

type ClientOptions struct { /* ... */ } // described below

type ClientSession struct { /* ... */ }
func (*ClientSession) Client() *Client
func (*ClientSession) Close() error
func (*ClientSession) Wait() error
// Methods for calling through the ClientSession are described below.
// For example: ClientSession.ListTools.

type Server struct { /* ... */ }
func NewServer(name, version string, opts *ServerOptions) *Server
func (*Server) Connect(context.Context, Transport) (*ServerSession, error)
func (*Server) Sessions() iter.Seq[*ServerSession]
// Methods for adding/removing server features are described below.

type ServerOptions struct { /* ... */ } // described below

type ServerSession struct { /* ... */ }
func (*ServerSession) Server() *Server
func (*ServerSession) Close() error
func (*ServerSession) Wait() error
// Methods for calling through the ServerSession are described below.
// For example: ServerSession.ListRoots.

Here's an example of these APIs from the client side:

client := mcp.NewClient("mcp-client", "v1.0.0", nil)
// Connect to a server over stdin/stdout
transport := mcp.NewCommandTransport(exec.Command("myserver"))
session, err := client.Connect(ctx, transport)
if err != nil { ... }
// Call a tool on the server.
content, err := session.CallTool(ctx, "greet", map[string]any{"name": "you"}, nil)
...
return session.Close()

A server that can handle that client call would look like this:

// Create a server with a single tool.
server := mcp.NewServer("greeter", "v1.0.0", nil)
server.AddTools(mcp.NewTool("greet", "say hi", SayHi))
// Run the server over stdin/stdout, until the client disconnects.
transport := mcp.NewStdIOTransport()
session, err := server.Connect(ctx, transport)
...
return session.Wait()

For convenience, we provide Server.Run to handle the common case of running a session until the client disconnects:

func (*Server) Run(context.Context, Transport)

Differences from mcp-go: the Server APIs are similar to mcp-go, though the association between servers and transports is different. In mcp-go, a single server is bound to what we would call an SSEHTTPHandler, and reused for all sessions. Per-session behavior is implemented though a 'session tool' overlay. As discussed above, the transport abstraction here is differentiated from HTTP serving, and the Server.Connect method provides a consistent API for binding to an arbitrary transport. Servers here do not have methods for sending notifications or calls, because they are logically distinct from the ServerSession. In mcp-go, servers are n:1, but there is no abstraction of a server session: sessions are addressed in Server APIs through their sessionID: SendNotificationToAllClients, SendNotificationToClient, SendNotificationToSpecificClient.

The client API here is different, since clients and client sessions are conceptually distinct. The ClientSession is closer to mcp-go's notion of Client.

For both clients and servers, mcp-go uses variadic options to customize behavior, whereas an options struct is used here. We felt that in this case, an options struct would be more readable, and result in simpler package documentation.

Spec Methods

In our SDK, RPC methods that are defined in the specification take a context and a params pointer as arguments, and return a result pointer and error:

func (*ClientSession) ListTools(context.Context, *ListToolsParams) (*ListToolsResult, error)

Our SDK has a method for every RPC in the spec, their signatures all share this form. We do this, rather than providing more convenient shortcut signatures, to maintain backward compatibility if the spec makes backward-compatible changes such as adding a new property to the request parameters (as in this commit, for example). To avoid boilerplate, we don't repeat this signature for RPCs defined in the spec; readers may assume it when we mention a "spec method."

CallTool is the only exception: for convenience when binding to Go argument types, *CallToolParams[TArgs] is generic, with a type parameter providing the Go type of the tool arguments. The spec method accepts a *CallToolParams[json.RawMessage], but we provide a generic helper function. See the section on Tools below for details.

Why do we use params instead of the full JSON-RPC request? As much as possible, we endeavor to hide JSON-RPC details when they are not relevant to the business logic of your client or server. In this case, the additional information in the JSON-RPC request is just the request ID and method name; the request ID is irrelevant, and the method name is implied by the name of the Go method providing the API.

We believe that any change to the spec that would require callers to pass a new a parameter is not backward compatible. Therefore, it will always work to pass nil for any XXXParams argument that isn't currently necessary. For example, it is okay to call Ping like so:

err := session.Ping(ctx, nil)

Iterator Methods

For convenience, iterator methods handle pagination for the List spec methods automatically, traversing all pages. If Params are supplied, iteration begins from the provided cursor (if present).

func (*ClientSession) Tools(context.Context, *ListToolsParams) iter.Seq2[Tool, error]

func (*ClientSession) Prompts(context.Context, *ListPromptsParams) iter.Seq2[Prompt, error]

func (*ClientSession) Resources(context.Context, *ListResourceParams) iter.Seq2[Resource, error]

func (*ClientSession) ResourceTemplates(context.Context, *ListResourceTemplatesParams) iter.Seq2[ResourceTemplate, error]

Middleware

We provide a mechanism to add MCP-level middleware on the both the client and server side, which runs after the request has been parsed but before any normal handling.

// A MethodHandler handles MCP messages.
// The params argument is an XXXParams struct pointer, such as *GetPromptParams.
// For methods, a MethodHandler must return either an XXResult struct pointer and a nil error, or
// nil with a non-nil error.
// For notifications, a MethodHandler must return nil, nil.
type MethodHandler[S ClientSession | ServerSession] func(
	ctx context.Context, _ *S, method string, params any) (result any, err error)

// Middleware is a function from MethodHandlers to MethodHandlers.
type Middleware[S ClientSession | ServerSession] func(MethodHandler[S]) MethodHandler[S]

// AddMiddleware wraps the client/server's current method handler using the provided
// middleware. Middleware is applied from right to left, so that the first one
// is executed first.
//
// For example, AddMiddleware(m1, m2, m3) augments the server method handler as
// m1(m2(m3(handler))).
func (c *Client) AddMiddleware(middleware ...Middleware[ClientSession])
func (s *Server) AddMiddleware(middleware ...Middleware[ServerSession])

As an example, this code adds server-side logging:

func withLogging(h mcp.MethodHandler[ServerSession]) mcp.MethodHandler[ServerSession]{
    return func(ctx context.Context, s *mcp.ServerSession, method string, params any) (res any, err error) {
        log.Printf("request: %s %v", method, params)
        defer func() { log.Printf("response: %v, %v", res, err) }()
        return h(ctx, s , method, params)
    }
}

server.AddMiddleware(withLogging)

Differences from mcp-go: Version 0.26.0 of mcp-go defines 24 server hooks. Each hook consists of a field in the Hooks struct, a Hooks.Add method, and a type for the hook function. These are rarely used. The most common is OnError, which occurs fewer than ten times in open-source code.

Errors

With the exception of tool handler errors, protocol errors are handled transparently as Go errors: errors in server-side feature handlers are propagated as errors from calls from the ClientSession, and vice-versa.

Protocol errors wrap a JSONRPCError type which exposes its underlying error code.

type JSONRPCError struct {
	Code    int64           `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

As described by the spec, tool execution errors are reported in tool results.

Differences from mcp-go: the JSONRPCError type here does not include ID and Method, which can be inferred from the caller. Otherwise, this behavior is similar.

Cancellation

Cancellation is implemented transparently using context cancellation. The user can cancel an operation by cancelling the associated context:

ctx, cancel := context.WithCancel(ctx)
go session.CallTool(ctx, "slow", map[string]any{}, nil)
cancel()

When this client call is cancelled, a "notifications/cancelled" notification is sent to the server. However, the client call returns immediately with ctx.Err(): it does not wait for the result from the server.

The server observes a client cancellation as a cancelled context.

Progress handling

A caller can request progress notifications by setting the Meta.ProgressToken field on any request.

type XXXParams struct { // where XXX is each type of call
  Meta Meta
  ...
}

type Meta struct {
  Data          map[string]any
  ProgressToken any // string or int
}

Handlers can notify their peer about progress by calling the NotifyProgress method. The notification is only sent if the peer requested it by providing a progress token.

func (*ClientSession) NotifyProgress(context.Context, *ProgressNotification)
func (*ServerSession) NotifyProgress(context.Context, *ProgressNotification)

Ping / KeepAlive

Both ClientSession and ServerSession expose a Ping method to call "ping" on their peer.

func (c *ClientSession) Ping(ctx context.Context, *PingParams) error
func (c *ServerSession) Ping(ctx context.Context, *PingParams) error

Additionally, client and server sessions can be configured with automatic keepalive behavior. If the KeepAlive option is set to a non-zero duration, it defines an interval for regular "ping" requests. If the peer fails to respond to pings originating from the keepalive check, the session is automatically closed.

type ClientOptions struct {
  ...
  KeepAlive time.Duration
}

type ServerOptions struct {
  ...
  KeepAlive time.Duration
}

Differences from mcp-go: in mcp-go the Ping method is only provided for client, not server, and the keepalive option is only provided for SSE servers (as a variadic option).

Client Features

Roots

Clients support the MCP Roots feature, including roots-changed notifications. Roots can be added and removed from a Client with AddRoots and RemoveRoots:

// AddRoots adds the given roots to the client,
// replacing any with the same URIs,
// and notifies any connected servers.
func (*Client) AddRoots(roots ...*Root)

// RemoveRoots removes the roots with the given URIs.
// and notifies any connected servers if the list has changed.
// It is not an error to remove a nonexistent root.
func (*Client) RemoveRoots(uris ...string)

Server sessions can call the spec method ListRoots to get the roots. If a server installs a RootsChangedHandler, it will be called when the client sends a roots-changed notification, which happens whenever the list of roots changes after a connection has been established.

type ServerOptions {
  ...
  // If non-nil, called when a client sends a roots-changed notification.
  RootsChangedHandler func(context.Context, *ServerSession, *RootsChangedParams)
}

The Roots method provides a cached iterator of the root set, invalidated when roots change.

func (*ServerSession) Roots(context.Context) (iter.Seq[*Root, error])

Sampling

Clients that support sampling are created with a CreateMessageHandler option for handling server calls. To perform sampling, a server session calls the spec method CreateMessage.

type ClientOptions struct {
  ...
  CreateMessageHandler func(context.Context, *ClientSession, *CreateMessageParams) (*CreateMessageResult, error)
}

Server Features

Tools

A Tool is a logical MCP tool, generated from the MCP spec, and a ServerTool is a tool bound to a tool handler.

A tool handler accepts CallToolParams and returns a CallToolResult. However, since we want to bind tools to Go input types, it is convenient in associated APIs to make CallToolParams generic, with a type parameter TArgs for the tool argument type. This allows tool APIs to manage the marshalling and unmarshalling of tool inputs for their caller. The bound ServerTool type expects a json.RawMessage for its tool arguments, but the NewTool constructor described below provides a mechanism to bind a typed handler.

type CallToolParams[TArgs any] struct {
	Meta      Meta   `json:"_meta,omitempty"`
	Arguments TArgs  `json:"arguments,omitempty"`
	Name      string `json:"name"`
}

type Tool struct {
	Annotations *ToolAnnotations   `json:"annotations,omitempty"`
	Description string             `json:"description,omitempty"`
	InputSchema *jsonschema.Schema `json:"inputSchema"`
	Name string                    `json:"name"`
}

type ToolHandler[TArgs] func(context.Context, *ServerSession, *CallToolParams[TArgs]) (*CallToolResult, error)

type ServerTool struct {
	Tool    Tool
	Handler ToolHandler[json.RawMessage]
}

Add tools to a server with AddTools:

server.AddTools(
  mcp.NewTool("add", "add numbers", addHandler),
  mcp.NewTool("subtract, subtract numbers", subHandler))

Remove them by name with RemoveTools:

server.RemoveTools("add", "subtract")

A tool's input schema, expressed as a JSON Schema, provides a way to validate the tool's input. One of the challenges in defining tools is the need to associate them with a Go function, yet support the arbitrary complexity of JSON Schema. To achieve this, we have seen two primary approaches:

1. Use reflection to generate the tool's input schema from a Go type (à la metoro-io/mcp-golang)
2. Explicitly build the input schema (à la mark3labs/mcp-go).

Both of these have their advantages and disadvantages. Reflection is nice, because it allows you to bind directly to a Go API, and means that the JSON schema of your API is compatible with your Go types by construction. It also means that concerns like parsing and validation can be handled automatically. However, it can become cumbersome to express the full breadth of JSON schema using Go types or struct tags, and sometimes you want to express things that aren’t naturally modeled by Go types, like unions. Explicit schemas are simple and readable, and give the caller full control over their tool definition, but involve significant boilerplate.

We have found that a hybrid model works well, where the initial schema is derived using reflection, but any customization on top of that schema is applied using variadic options. We achieve this using a NewTool helper, which generates the schema from the input type, and wraps the handler to provide parsing and validation. The schema (and potentially other features) can be customized using ToolOptions.

// NewTool creates a Tool using reflection on the given handler.
func NewTool[TArgs any](name, description string, handler ToolHandler[TArgs], opts …ToolOption) *ServerTool

type ToolOption interface { /* ... */ }

NewTool determines the input schema for a Tool from the TArgs type. Each struct field that would be marshaled by encoding/json.Marshal becomes a property of the schema. The property is required unless the field's json tag specifies "omitempty" or "omitzero" (new in Go 1.24). For example, given this struct:

struct {
  Name     string `json:"name"`
  Count    int    `json:"count,omitempty"`
  Choices  []string
  Password []byte `json:"-"`
}

"name" and "Choices" are required, while "count" is optional.

As of this writing, the only ToolOption is Input, which allows customizing the input schema of the tool using schema options. These schema options are recursive, in the sense that they may also be applied to properties.

func Input(...SchemaOption) ToolOption

type Property(name string, opts ...SchemaOption) SchemaOption
type Description(desc string) SchemaOption
// etc.

For example:

NewTool(name, description, handler,
    Input(Property("count", Description("size of the inventory"))))

The most recent JSON Schema spec defines over 40 keywords. Providing them all as options would bloat the API despite the fact that most would be very rarely used. For less common keywords, use the Schema option to set the schema explicitly:

NewTool(name, description, handler,
    Input(Property("Choices", Schema(&jsonschema.Schema{UniqueItems: true}))))

Schemas are validated on the server before the tool handler is called.

Since all the fields of the Tool struct are exported, a Tool can also be created directly with assignment or a struct literal.

Client sessions can call the spec method ListTools or an iterator method Tools to list the available tools, and use spec method CallTool to call tools. Similar to ServerTool.Handler, CallTool expects *CallToolParams[json.RawMessage], but we provide a generic CallTool helper to operate on typed arguments.

func (cs *ClientSession) CallTool(context.Context, *CallToolParams[json.RawMessage]) (*CallToolResult, error)

func CallTool[TArgs any](context.Context, *ClientSession, *CallToolParams[TArgs]) (*CallToolResult, error)

Differences from mcp-go: using variadic options to configure tools was significantly inspired by mcp-go. However, the distinction between ToolOption and SchemaOption allows for recursive application of schema options. For example, that limitation is visible in this code, which must resort to untyped maps to express a nested schema.

Additionally, the NewTool helper provides a means for building a tool from a Go function using reflection, that automatically handles parsing and validation of inputs.

We provide a full JSON Schema implementation for validating tool input schemas against incoming arguments. The jsonschema.Schema type provides exported features for all keywords in the JSON Schema draft2020-12 spec. Tool definers can use it to construct any schema they want, so there is no need to provide options for all of them. When combined with schema inference from input structs, we found that we needed only three options to cover the common cases, instead of mcp-go's 23. For example, we will provide Enum, which occurs 125 times in open source code, but not MinItems, MinLength or MinProperties, which each occur only once (and in an SDK that wraps mcp-go).

For registering tools, we provide only AddTools; mcp-go's SetTools, AddTool, AddSessionTool, and AddSessionTools are deemed unnecessary. (Similarly for Delete/Remove).

Prompts

Use NewPrompt to create a prompt. As with tools, prompt argument schemas can be inferred from a struct, or obtained from options.

func NewPrompt[TReq any](name, description string,
  handler func(context.Context, *ServerSession, TReq) (*GetPromptResult, error),
  opts ...PromptOption) *ServerPrompt

Use AddPrompts to add prompts to the server, and RemovePrompts
to remove them by name.

type codeReviewArgs struct {
  Code string `json:"code"`
}

func codeReviewHandler(context.Context, *ServerSession, codeReviewArgs) {...}

server.AddPrompts(
  NewPrompt("code_review", "review code", codeReviewHandler,
    Argument("code", Description("the code to review"))))

server.RemovePrompts("code_review")

Client sessions can call the spec method ListPrompts or the iterator method Prompts to list the available prompts, and the spec method GetPrompt to get one.

Differences from mcp-go: We provide a NewPrompt helper to bind a prompt handler to a Go function using reflection to derive its arguments. We provide RemovePrompts to remove prompts from the server.

Resources and resource templates

In our design, each resource and resource template is associated with a function that reads it, with this signature:

type ResourceHandler func(context.Context, *ServerSession, *ReadResourceParams) (*ReadResourceResult, error)

The arguments include the ServerSession so the handler can observe the client's roots. The handler should return the resource contents in a ReadResourceResult, calling either NewTextResourceContents or NewBlobResourceContents. If the handler omits the URI or MIME type, the server will populate them from the resource.

The ServerResource and ServerResourceTemplate types hold the association between the resource and its handler:

type ServerResource struct {
  Resource Resource
  Handler  ResourceHandler
}

type ServerResourceTemplate struct {
  Template ResourceTemplate
  Handler  ResourceHandler
}

To add a resource or resource template to a server, users call the AddResources and AddResourceTemplates methods with one or more ServerResources or ServerResourceTemplates. We also provide methods to remove them.

func (*Server) AddResources(...*ServerResource)
func (*Server) AddResourceTemplates(...*ServerResourceTemplate)

func (s *Server) RemoveResources(uris ...string)
func (s *Server) RemoveResourceTemplates(uriTemplates ...string)

The ReadResource method finds a resource or resource template matching the argument URI and calls its associated handler.

To read files from the local filesystem, we recommend using FileResourceHandler to construct a handler:

// FileResourceHandler returns a ResourceHandler that reads paths using dir as a root directory.
// It protects against path traversal attacks.
// It will not read any file that is not in the root set of the client requesting the resource.
func (*Server) FileResourceHandler(dir string) ResourceHandler

Here is an example:

// Safely read "/public/puppies.txt".
s.AddResources(&mcp.ServerResource{
  Resource: mcp.Resource{URI: "file:///puppies.txt"},
  Handler: s.FileReadResourceHandler("/public")})

Server sessions also support the spec methods ListResources and ListResourceTemplates, and the corresponding iterator methods Resources and ResourceTemplates.

Differences from mcp-go: for symmetry with tools and prompts, we use AddResources rather than AddResource. Additionally, the ResourceHandler returns a ReadResourceResult, rather than just its content, for compatibility with future evolution of the spec.

Subscriptions

ClientSessions can manage change notifications on particular resources:

func (*ClientSession) Subscribe(context.Context, *SubscribeParams) error
func (*ClientSession) Unsubscribe(context.Context, *UnsubscribeParams) error

The server does not implement resource subscriptions. It passes along subscription requests to the user, and supplies a method to notify clients of changes. It tracks which sessions have subscribed to which resources so the user doesn't have to.

If a server author wants to support resource subscriptions, they must provide handlers to be called when clients subscribe and unsubscribe. It is an error to provide only one of these handlers.

type ServerOptions struct {
  ...
  // Function called when a client session subscribes to a resource.
  SubscribeHandler func(context.Context, *SubscribeParams) error
  // Function called when a client session unsubscribes from a resource.
  UnsubscribeHandler func(context.Context, *UnsubscribeParams) error
}

User code should call ResourceUpdated when a subscribed resource changes.

func (*Server) ResourceUpdated(context.Context, *ResourceUpdatedNotification) error

The server routes these notifications to the server sessions that subscribed to the resource.

ListChanged notifications

When a list of tools, prompts or resources changes as the result of an AddXXX or RemoveXXX call, the server informs all its connected clients by sending the corresponding type of notification. A client will receive these notifications if it was created with the corresponding option:

type ClientOptions struct {
  ...
  ToolListChangedHandler func(context.Context, *ClientSession, *ToolListChangedParams)
  PromptListChangedHandler func(context.Context, *ClientSession, *PromptListChangedParams)
  // For both resources and resource templates.
  ResourceListChangedHandler func(context.Context, *ClientSession, *ResourceListChangedParams)
}

Differences from mcp-go: mcp-go instead provides a general OnNotification handler. For type-safety, and to hide JSON RPC details, we provide feature-specific handlers here.

Completion

Clients call the spec method Complete to request completions. Servers automatically handle these requests based on their collections of prompts and resources.

Differences from mcp-go: the client API is similar. mcp-go has not yet defined its server-side behavior.

Logging

MCP specifies a notification for servers to log to clients. Server sessions implement this with the LoggingMessage method. It honors the minimum log level established by the client session's SetLevel call.

As a convenience, we also provide a slog.Handler that allows server authors to write logs with the log/slog package::

// A LoggingHandler is a [slog.Handler] for MCP.
type LoggingHandler struct {...}

// LoggingHandlerOptions are options for a LoggingHandler.
type LoggingHandlerOptions struct {
	// The value for the "logger" field of logging notifications.
	LoggerName string
	// Limits the rate at which log messages are sent.
	// If zero, there is no rate limiting.
	MinInterval time.Duration
}

// NewLoggingHandler creates a [LoggingHandler] that logs to the given [ServerSession] using a
// [slog.JSONHandler].
func NewLoggingHandler(ss *ServerSession, opts *LoggingHandlerOptions) *LoggingHandler

Server-to-client logging is configured with ServerOptions:

type ServerOptions {
  ...
  // The value for the "logger" field of the notification.
  LoggerName string
  // Log notifications to a single ClientSession will not be
  // sent more frequently than this duration.
  LoggingInterval time.Duration
}

A call to a log method like Info is translated to a LoggingMessageNotification as follows:

• The attributes and the message populate the "data" property with the output of a slog.JSONHandler: The result is always a JSON object, with the key "msg" for the message.

• If the LoggerName server option is set, it populates the "logger" property.

• The standard slog levels Info, Debug, Warn and Error map to the corresponding levels in the MCP spec. The other spec levels map to integers between the slog levels. For example, "notice" is level 2 because it is between "warning" (slog value 4) and "info" (slog value 0). The mcp package defines consts for these levels. To log at the "notice" level, a handler would call Log(ctx, mcp.LevelNotice, "message").

A client that wishes to receive log messages must provide a handler:

type ClientOptions struct {
  ...
  LoggingMessageHandler func(context.Context, *ClientSession, *LoggingMessageParams)
}

Pagination

Servers initiate pagination for ListTools, ListPrompts, ListResources, and ListResourceTemplates, dictating the page size and providing a NextCursor field in the Result if more pages exist. The SDK implements keyset pagination, using the unique ID of the feature as the key for a stable sort order and encoding the cursor as an opaque string.

For server implementations, the page size for the list operation may be configured via the ServerOptions.PageSize field. PageSize must be a non-negative integer. If zero, a sensible default is used.

type ServerOptions {
  ...
  PageSize int
}

Client requests for List methods include an optional Cursor field for pagination. Server responses for List methods include a NextCursor field if more pages exist.

In addition to the List methods, the SDK provides an iterator method for each list operation. This simplifies pagination for clients by automatically handling the underlying pagination logic. See Iterator Methods above.

Differences with mcp-go: the PageSize configuration is set with a configuration field rather than a variadic option. Additionally, this design proposes pagination by default, as this is likely desirable for most servers

Governance and Community

While the sections above propose an initial implementation of the Go SDK, MCP is evolving rapidly. SDKs need to keep pace, by implementing changes to the spec, fixing bugs, and accomodating new and emerging use-cases. This section proposes how the SDK project can be managed so that it can change safely and transparently.

Initially, the Go SDK repository will be administered by the Go team and Anthropic, and they will be the Approvers (the set of people able to merge PRs to the SDK). The policies here are also intended to satisfy necessary constraints of the Go team's participation in the project.

The content in this section will also be included in a CONTRIBUTING.md file in the repo root.

Hosting, copyright, and license

The SDK will be hosted under github.com/modelcontextprotocol/go-sdk, MIT license, copyright "Go SDK Authors". Each Go file in the repository will have a standard copyright header. For example:

// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
// Use of this source code is governed by an MIT-style
// license that can be found in the LICENSE file.

Issues and Contributing

The SDK will use its GitHub issue tracker for bug tracking, and pull requests for contributions.

Contributions to the SDK will be welcomed, and will be accepted provided they are high quality and consistent with the direction and philosophy of the SDK outlined above. An official SDK must be conservative in the changes it accepts, to defend against compatibility problems, security vulnerabilities, and churn. To avoid being declined, PRs should be associated with open issues, and those issues should either be labeled 'Help Wanted', or the PR author should ask on the issue before contributing.

Proposals

A proposal is an issue that proposes a new API for the SDK, or a change to the signature or behavior of an existing API. Proposals will be labeled with the 'Proposal' label, and require an explicit approval before being accepted (applied through the 'Proposal-Accepted' label). Proposals will remain open for at least a week to allow discussion before being accepted or declined by an Approver.

Proposals that are straightforward and uncontroversial may be approved based on GitHub discussion. However, proposals that are deemed to be sufficiently unclear or complicated will be deferred to a regular steering meeting (see below).

This process is similar to the Go proposal process, but is necessarily lighter weight to accomodate the greater rate of change expected for the SDK.

Steering meetings

On a regular basis, we will host a virtual steering meeting to discuss outstanding proposals and other changes to the SDK. These 1hr meetings and their agenda will be announced in advance, and open to all to join. The meetings will be recorded, and recordings and meeting notes will be made available afterward.

This process is similar to the Go Tools call, though it is expected that meetings will at least initially occur on a more frequent basis (likely biweekly).

Discord

Discord (either the public or private Anthropic discord servers) should only be used for logistical coordination or answering questions. Design discussion and decisions should occur in GitHub issues or public steering meetings.

Antitrust considerations

It is important that the SDK avoids bias toward specific integration paths or providers. Therefore, the CONTRIBUTING.md file will include an antitrust policy that outlines terms and practices intended to avoid such bias, or the appearance thereof. (The details of this policy will be determined by Google and Anthropic lawyers).

Releases and Versioning

The SDK will consist of a single Go module, and will be released through versioned Git tags. Accordingly, it will follow semantic versioning.

Up until the v1.0.0 release, the SDK may be unstable and may change in breaking ways. An initial v1.0.0 release will occur when the SDK is deemed by Approvers to be stable, production ready, and sufficiently complete (though some unimplemented features may remain). Subsequent to that release, new APIs will be added in minor versions, and breaking changes will require a v2 release of the module (and therefore should be avoided). All releases will have corresponding release notes in GitHub.

It is desirable that releases occur frequently, and that a v1.0.0 release is achieved as quickly as possible.

If feasible, the SDK will support all versions of the MCP spec. However, if breaking changes to the spec make this infeasible, preference will be given to the most recent version of the MCP spec.

Ongoing evaluation

On an ongoing basis, the administrators of the SDK will evaluate whether it is keeping pace with changes to the MCP spec and meeting its goals of openness and transparency. If it is not meeting these goals, either because it exceeds the bandwidth of its current Approvers, or because the processes here are inadequate, these processes will be re-evaluated. At this time, the Approvers set may be expanded to include additional community members, based on their history of strong contribution.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[SamMorrowDrums]

Thank you so much for hard work on this!

Excited to try this out at GitHub. 🔥

[williammartin]

This looks great, thank you for your work. As I read the function signatures, I had a similar question as: mark3labs/mcp-go#294, which perhaps you also have a good answer for.

You say:

As described by the spec, tool execution errors are reported in tool results.

And the ToolHandler has signature:

type ToolHandler func(context.Context, *ServerSession, *CallToolParams) (*CallToolResult, error)

Under what circumstances would you expect a Tool to return a non-nil error as the second return value? Thanks!

[findleyr]

@williammartin here's the relevant implementation in our prototype:
https://go.googlesource.com/tools/+/refs/heads/master/internal/mcp/tool.go#37

If you use the NewTool helper (which binds a tool to a Go function), errors in that function are lifted into the CallToolResult, as prescribed by the spec. If you write your own ToolHandler, you'd have to implement the equivalent logic yourself. Let me know if you think that's not correct.

[MegaGrindStone]

Some concrete example of returned error would be, in the filesystem mcp server, if your handler unable to read or write the file requested by the client, you would returns the error and explained what's happen to the client.

But, I want to clarify something to @findleyr. Based on the implementation you share above, if the handler implementation is returning error, the client that calling it would NOT receive a Go error, but instead a CallToolResult with an IsError field set to true, right?

[findleyr]

@MegaGrindStone yes, that's right. That was my reading of the spec: a missing tool or parse error results in a JSON-RPC error, but a failure of the business logic of the tool (the Go function) is lifted into a normal result with "isError": true.

[williammartin]

Thanks @findleyr for sharing that code! That's pretty much exactly what I imagined earlier in a conversation when I wrote to @SamMorrowDrums about separating our tool handling from the specific server module:

So for example, we might have our own handler func(context.Context, args map[string]any) ToolCallResult (glossing over some unknowns about what handlers actually need from the request, maybe we just have our own request type) where ToolCallResult is a sealed interface. Then we can swap out the MCP implementation very easily by just adjusting the mapping layer

Except in this implementation you've chosen to union fields rather than types (totally fine, I'm just a sum typer at heart!). Also, a big fan of giving access to the raw json for input, thats what I would have used in the signature above if it wouldn't have meant marshaling the mcp-go args again.

[williammartin]

@findleyr, as valuable as this document is for noodling on, I'm very eager to get my hands on the implementation to give feedback based on empirical use. At the top of the discussion you said:

We hope that we can reach consensus within a reasonable amount of time (a couple of weeks, perhaps?). Once that happens, we’ll finalize the design and move to the execution phase, where we create github.com/modelcontextprotocol/go-sdk.

Please let me know if you start executing in such a way that I can start trying it out.

[lexlapax]

I vote for creating github.com/modelcontextprotocol/go-sdk with at least a README on it including pointers to this thread and the dev repo at google to point the search-gods to the right direction.

[RazaGR]

Really excited to see this moving forward — the design looks thoughtful and well aligned with Go idioms. I’d be happy to help with early testing, especially around session handling, transport abstractions, and tool integration. Please feel free to loop me in where hands-on feedback would be most useful. Looking forward to contributing!

[anuraaga]

Thanks for the doc @findleyr. As you know I am mostly looking at the observability aspect of the SDK, especially propagating distributed context. Some initial thoughts

• As discussed in https://github.com/orgs/modelcontextprotocol/discussions/224#discussioncomment-13095826, we will need a way to handle _meta generically. You mentioned needing to customize generation logic and I was wondering if it's possible to add some details about it to the doc. Also some notable questions are

  • How would it be accessed, i.e. in middleware? Would we need a huge type switch? Or perhaps it makes sense to make params a generic type, e.g. Params[CallToolParams], func (p *Params) Meta(), etc
  • Or maybe meta can be recognized for what it is and passed within Context and retrieved something like mcp.MetaFromContext(ctx). This seems particularly important if the proposal to move meta to the top level goes through Document request.params._meta convention modelcontextprotocol#414 (comment) as it seems we wouldn't want to have to add meta to every single function that accepts params

• A bit related to the above, there seems to be a notion that all types in MCP are actually open meaning they should provide access to additional fields. Does it make sense to make every type define custom marshaling to store unknown fields into a map? Of course I wish Go had a json: struct tag to store them more easily

  • I raised feat(protocol): allow additional fields in meta mark3labs/mcp-go#293 to mcp-go specifically for _meta since it is the one that has current use as an open container and I didn't want to do too intrusive of a change. But if you follow the links to the other SDKs from there, you'll see that they allow extension on almost all types, not just _meta

• Middleware seems to only be defined for server. However, MCP supports making requests from the server to the client. An example here. So to make sure the client handling such a request can receive context from the server, I think middleware needs to be addable in a symmetric way between client/server. In my instrumentation of SDKs I have tried to instrument Transport for this reason - it worked well in Python and Typescript because the way async iterators work, they actually handle the messages they receive and can setup context. It didn't work for Java, though I made a suggestion to refactor in a way that potentially could. If wanting to make Transport a symmetric entrypoint for wrapping with context, I think in Go it may look like a Write() and ReadLoop(), the latter not actually returning a message but looping on received messages to pass to a JSON-RPC handler that could be instrumented with middleware. If Transport isn't the place to think about this though, hopefully there is a different way to do middleware symmetric to server and client.

  • BTW, to clarify, if we ignore server -> client requests for now, I guess the intention of the design is to use server middleware to read context, and wrap Transport to wrap Stream on the client to write it?

[anuraaga]

Thanks - I read through the latest code and see the symmetric middleware and the request handling side looks pretty good. I am still curious what it'll look like to inject data into messages before going over the wire, I think it's wrap Transport to wrap Stream, but some concerns are that it is a bit tedious to wrap two types - but that's fine really. More worryingly is if these interfaces may be extended using optional interfaces in the future like http.ResponseWriter. Anyone that has written net/http middleware will know how incredibly difficult it is to wrap that type, while being very common to do - if the Transport interface seems pretty stable and we optimistically expect no optional interfaces, even when it happens it could be ok but want to call that out as a concern.

Also, for requests from server to client, or arbitrary request from client/server, I think it can be simply added with AddRequestHandler and Session.SendRequest or similar. I don't know if such functionality would be needed for an initial release but checking on whether this sort of design is on the table for future work to support it.

[anuraaga]

I went ahead and prototyped what it would look like to inject metadata by wrapping Transport. I realized one issue was that the params are already serialized into json.RawMessage by the time they hit the transport, so injecting means unmarshalling, injecting, and remarshalling. It's doable but I guess it's nice if this could happen before the original marshalling somehow.

That being said, since it is doable, once meta is available on the server side things look ready for context propagation to work so nice to see that.

type contextTransport struct {
	delegate mcp.Transport
}

func (c contextTransport) Connect(ctx context.Context) (mcp.Stream, error) {
	stream, err := c.delegate.Connect(ctx)
	if err != nil {
		return nil, err
	}
	return contextStream{delegate: stream}, nil
}

type contextStream struct {
	delegate mcp.Stream
}

// Read implements mcp.Stream.
func (c contextStream) Read(ctx context.Context) (jsonrpc2.Message, int64, error) {
	return c.delegate.Read(ctx)
}

// Write implements mcp.Stream.
func (c contextStream) Write(ctx context.Context, msg jsonrpc2.Message) (int64, error) {
	if req, ok := msg.(*jsonrpc2.Request); ok {
		var params map[string]any
		if err := json.Unmarshal(req.Params, &params); err == nil {
			meta := params["_meta"]
			if meta == nil {
				meta = make(map[string]any)
				params["_meta"] = meta
			}
			otel.GetTextMapPropagator().Inject(ctx, stringAnyMapCarrier{meta.(map[string]any)})
			if newParams, err := json.Marshal(params); err == nil {
				req.Params = newParams
			}
		}
	}
	return c.delegate.Write(ctx, msg)
}

// Close implements mcp.Stream.
func (c contextStream) Close() error {
	return c.delegate.Close()
}

[jba]

Ah, I see: our middleware intercepts on the receiving side (like all HTTP middleware). You need to intercept on the sending side. There are other use cases for that too, like adding a progress token to every outgoing request.
I think we need another kind of middleware, before each call, with unmarshalled params.
I'll think about that.

[jba]

@anuraaga please take a look at https://go.googlesource.com/tools/+/refs/heads/master/internal/mcp/client.go#197.
I think "sending middleware" should do what you want.
Let me know if there's anything we can improve.

[anuraaga]

Thanks @jba! Can confirm it works great for propagation, and definitely the easiest of any MCP SDK I've tried so far. I've tried with a basic example and will try some more advanced use cases such as calling back from server to client, but I don't see any reason this wouldn't work.

The only notes are less about this SDK and Go generics themselves, and probably well known, but I'll write them down just in case - definitely not blockers since even if improved, it would be in a possibly distant future Go version.

• Wish the type parameter could be inferred for e.g. server.AddSendingMiddleware(OTelSendingMiddleware[*mcp.ServerSession]())
• Not really about middleware but when updating my code to the latest SDK, I found the mcp.CallTool function to accept a generic type, and ClientSession.CallTool which duplicates its functionality without generics. Wish we could have generic methods so we don't need such duplication 😅

func OTelReceivingMiddleware[S mcp.Session]() mcp.Middleware[S] {
	return func(mh mcp.MethodHandler[S]) mcp.MethodHandler[S] {
		return func(ctx context.Context, sess S, method string, params mcp.Params) (result mcp.Result, err error) {
			ctx = otel.GetTextMapPropagator().Extract(ctx, stringAnyMapCarrier{params.GetMeta().Data})
			return mh(ctx, sess, method, params)
		}
	}
}

func OTelSendingMiddleware[S mcp.Session]() mcp.Middleware[S] {
	return func(mh mcp.MethodHandler[S]) mcp.MethodHandler[S] {
		return func(ctx context.Context, sess S, method string, params mcp.Params) (result mcp.Result, err error) {
			meta := params.GetMeta()
			if meta.Data == nil {
				meta.Data = make(map[string]any)
			}
			otel.GetTextMapPropagator().Inject(ctx, stringAnyMapCarrier{meta.Data})
			return mh(ctx, sess, method, params)
		}
	}
}

server.AddSendingMiddleware(OTelSendingMiddleware[*mcp.ServerSession]())
server.AddReceivingMiddleware(OTelReceivingMiddleware[*mcp.ServerSession]())

client.AddReceivingMiddleware(OTelReceivingMiddleware[*mcp.ClientSession]())
client.AddSendingMiddleware(OTelSendingMiddleware[*mcp.ClientSession]())

[tarunanand-dev]

Hello @findleyr and fellow contributors,

Thanks for the very thoughtful design proposal and discussion.

I have an alternate proposal and discussion that I kickstarted with the rust sdk authors here
https://github.com/orgs/modelcontextprotocol/discussions/354

Reproducing the gist of that discussion here:

Folks, as MCP’s language ecosystem expands, we’re spending more time re‑implementing the same deterministic‑state logic than shipping new ideas. I’d like us to flip that ratio by standardizing on a single, Rust core (rust‑sdk) that owns the workflow engine— sessions, peering, transport, serialization—while each language surface (Python, JS/TS, Go, etc.) stays 100 % idiomatic and lightweight. 

Rust gives us memory‑safe, no‑GC performance overhead, a stable FFI, and a proven path. The payoff is immediate: one quality, security and performance audit instead of five, feature parity across languages on day 1, and p99 latencies that drop from milliseconds to microseconds—without asking Python or JavaScript developers to learn Rust. 

In short, one deterministic engine, many friendly faces. We have built a V 0.1 Python and Typescript SDK based on this architecture so that we write less boilerplate and innovate faster on the parts that matter.

I know that as Golang stewards and enthusiasts you may want to write the SDK from scratch but would love to hear your views and counterpoints to this.

The Python Bindings PR is here
modelcontextprotocol/rust-sdk#172

The Typescript Bindings PR is here
modelcontextprotocol/rust-sdk#183

[findleyr]

Thanks @tarunanand-dev for the idea. I think a good rule of thumb is that cgo (or other FFI) should be avoided unless it's infeasible to implement in pure Go, especially for something like an SDK which will be included in many builds. One of the reasons we think Go is a great fit for MCP is that it's a lightweight, portable, fast-compiling glue language, and any FFI would significantly reduce that value proposition.

Additionally, as of writing I don't think the implementation of the SDK is particularly difficult. That may change in the future, but right now I think the benefits of a shared implementation would not offset the downsides.

[codefromthecrypt]

I also agree that Go should be Go unless a very good reason, and I think MCP spec is simple enough and there will be enough contributors to ward off most reasons. While folks have discussed performance (and some security hints), there are many other reasons to stay in Go.

cross-compilation, coherent stack traces, easy debugging, ability to run on any platform including one without libc... all the joys folks are used in go. let's keep MCP as joyful as other key libraries in the Go ecosystem!

[jpmcb]

Thanks for the idea but, as others have said, I see no need for external bindings to Rust or C or another systems language / compiled objects.

Go's rock solid static binary, cross-compilation support makes for a good reason to not have external dependencies on system libraries or other bindings. I'd expect that if I go build an MCP server for a certain architecture or container target, it should "just work" for that architecture without having to fuss about with other targets for the bindings.

[lexlapax]

I tend to agree. While there may be learnings from the rust community on their progression on libraries, this is a go-lang discussion for as pure a golang support for mcp as possible, with as few external interactions or dependencies as possible, but sticking to the go way if there's such a thing. If as a developer I want some things from one language and some from another, that's upto my choosing, there's plenty of interop available.

[tarunanand-dev]

Interop and cross pollination of ideas are two different things. Unless you believe that all servers will be written in golang for e.g. interop will be in play whether you consider ideas from other languages or not. So yes, its a good idea to have pure go but keep the integration tax in mind. We can take this away to https://github.com/orgs/modelcontextprotocol/discussions/354 if you are interested and leave this thread for the go sdk.

[jakemac53]

Clients support the MCP Roots feature, including roots-changed notifications. Roots can be added and removed from a Client with AddRoots and RemoveRoots:

I think this might be consistent with other MCP SDKs, but I did want to mention that having the client by default always claim to have roots support is sometimes not ideal, because while the protocol may be "supported", that doesn't mean the client actually ever will set any roots.

This makes it difficult for a server to handle clients which don't actually ever set roots, for instance they may want to conditionally add a tool to manage roots.

I ran into this developing the MCP server for Dart/Flutter tooling, cursor claims to support roots but does not actually support them, so I had to add a flag to force enable a fallback mode instead of relying on detection of the supported features.

[MegaGrindStone]

I agree with this. But, from the current implementation, it looks like the client always declare to NOT support the Roots feature. Because, in that code, the Roots field from ClientCapabilities have a zero value, or do I miss something? Maybe in that code, we could check the length of the Client's roots to decide whether this client support Roots feature or not.

[jakemac53]

Yeah my comment is based only on the design proposed, it looks to me as well like the current implementation doesn't ever declare roots support at all, but I assume that is just a work in progress, or I am missing something as well.

For dart_mcp I chose to take a more object oriented approach, where you use mixins for each feature you support. It is a bit more tricky to fit that cleanly into a functional style though - because you want some actual nice apis for adding/removing roots. The mixins can both operate sort of as middleware for handling requests and altering the capabilities, as well as adding members (add/removeRoots).

[findleyr]

@jakemac53 thanks for the feedback. We should include a way to suppress client and server capabilities.

I think it's just a bug of our type wasn't extracting root capabilities to a named type like it does for server capabilities, and therefore root capabilities were generated as an embedded struct rather than a nillable (and therefore optional) field. So @MegaGrindStone while you are right that there's something wrong with the zero value in the implementation, it's not quite what you conclude: we were indeed always advertising root support.

@jakemac53 Just checking my understanding of what you're saying: if a hypothetical client used this SDK, and yet didn't have a UI element for users to add roots, it would be buggy for servers to assume that the user has chosen not to add roots. I agree that makes sense.

On the other hand, it seems less important to be able to suppress server capabilities, but we should allow it anyway.
mcp-go adds the capability on the first call to AddXXX, which seems like a good solution.

Is there any reason to support tools (or roots) and not advertise support of listChanged? I can't imagine a scenario where that would be desirable.

[jakemac53]

Just checking my understanding of what you're saying: if a hypothetical client used this SDK, and yet didn't have a UI element for users to add roots, it would be buggy for servers to assume that the user has chosen not to add roots.

Yes, exactly

mcp-go adds the capability on the first call to AddXXX, which seems like a good solution.

This assumes at least one root will be set prior to any servers being connected - the capabilities can only be given during initialization. So, I don't think that is really a good solution.

Is there any reason to support tools (or roots) and not advertise support of listChanged? I can't imagine a scenario where that would be desirable.

I don't think there is, for dart_mcp I chose to just always support the change notifications with no opt-out.

[findleyr]

This assumes at least one root will be set prior to any servers being connected - the capabilities can only be given during initialization. So, I don't think that is really a good solution.

Yeah, I think it's necessary but perhaps not sufficient. AddTools is variadic, so AddTools() could enable the capability without actually adding any tools, but it's too clever.

[anuraaga]

Had a random thought, I was wondering what the future of the design is in terms of ownership. I found the section on package layout

Therefore, this is the core package layout, assuming github.com/modelcontextprotocol/go-sdk as the module path.

github.com/modelcontextprotocol/go-sdk/mcp: the bulk of the user facing API
github.com/modelcontextprotocol/go-sdk/jsonschema: a jsonschema implementation, with validation
github.com/modelcontextprotocol/go-sdk/internal/jsonrpc2: a fork of x/tools/internal/jsonrpc2_v2

which seems to indicate the future is in the modelcontextprotocol org. If so, why not do it as soon as possible? If that is the intention, the only reason I can think of is to want to use gerrit for code reviews, but I would suggest it's better to get used to GitHub sooner than later.

If the intention is to be golang.org/x/mcp then there doesn't seem to be a reason to change from prototyping within the tools repo, but the question then that I think should be documented is what's the intention in terms of versioning. I know many /x/ modules never release a v1, with some that do, but I guess MCP users are expecting a v1 sooner than later.

I think it would be quite helpful to clarify what the goals are in terms of ownership and community engagement in this design, probably more so than even the technical details which will all somehow be resolved before a v1 release by the community. My advice would be to add a # Community section to the doc with these or any related details that come to mind.

[findleyr]

The intention is to contribute this to github.com/modelcontextprotocol/go-sdk. I like the idea of a Community section, thanks.

[findleyr]

There's a lot of overlap between the functionality in this (generated?) comment and the existing extensibility mechanisms of the getServer factory method, SSE transport, and middleware. I certainly wouldn't want an initial version of the SDK to have two constructors for the SSEHTTPHandler: if there are missing hooks in current constructor, we should fix them.

Please provide concrete arguments for the three bullets in the 'Why this is important' section. For example, the whole point of the existing getServer factory is to provide per-session customization.

Though I do think we should consider passing options to NewSSEHandler, for future-proofing.

[jpmcb]

🔥 Design looks impeccable, as I'd expect from the Go team!!!!!! Great work Robert! Can't wait to get my hands on it

re: Governance and ownership

One area I see as missing from this discussion is how the SDK will be governed and managed - Go code is one thing, governing the Go community around the SDK is another.

From what I've inferred:

• The SDK will land in github.com/modelcontextprotocol/go-sdk
• The Go team at Google will be the majority supporters

Open questions from this structure:

• What is the onramp for new maintainers?
• Will there be a Google group or something setup for the broader community to participate in and get notifications for? (much like the [email protected] for new version announcements or [email protected] for responsible security disclosures)
• Who owns the direction of this SDK? The Go team?

---

I don't think this is blocking, just would be good to iron out now. And maybe some of these questions are things that are better left for the core modelcontextprotocol org

[findleyr]

Thanks very much for your review and suggestions. You're right, there's a lot to address here, and we should include it in the design doc. (After all, it's almost more important to define how the SDK will evolve over time, since there are many spec changes on the horizon). I've started writing this up in https://go.dev/cl/677540. If you're able, please feel free to review that CL.

[sammcj]

Very much looking forward to an official Golang SDK, for anyone hanging out for this in the mean time I've found https://github.com/mark3labs/mcp-go/ to be the best alternative.

[dugenkui03]

why should we need Server()/func (*ServerSession) Server() *Server?

It seems dangerous, because anyone can get Server in ToolHandler/type ToolHandler func(context.Context, *ServerSession, *CallToolParams) (*CallToolResult, error) and do any thing they want, such as RemovePrompts.

[findleyr]

Thank you, that's an interesting point. I think if you are executing malicious code on the server, there are bigger problems.
However, I agree that we should not need the Server() method, and it does seem to violate a boundary. Let's remove it.

[richardwooding]

I'm looking forward to switching from github.com/mark3labs/mcp-go to this when it's ready.

[weylan]

me too!!!!

[mhpenta]

Thanks for the thoughtful design! I'm concerned about the tight coupling between tools and the MCP implementation via the *ServerSession parameter (among other things).

type ToolHandler[TArgs] func(context.Context, *ServerSession, *CallToolParams[TArgs]) (*CallToolResult, error)

The core issue: The *ServerSession parameter tightly couples every tool to this specific MCP implementation. This means tools can't be reused across different contexts - you can't take a search tool from your MCP server and drop it into a custom chatbot or headless agent flow without rewriting it. This is also a problem in mcp-go.

An alternative approach would be to use a standard interface so that tools can be reused outside of this specific implementation. At its simplest:

type Tool interface {
    Name() string
    Description() string  
    Parameters() *jsonschema.Schema
    Execute(ctx context.Context, params json.RawMessage) (*ToolResult, error)
}

For more flexibility, we could use execution options to handle session features like progress notification or logging:

type ExecuteOptions struct {
	ProgressReporter ProgressReporter
	Logger Logger
	// ... future extensions 
}

type Tool interface {
	Name() string
	Description() string
	Parameters() *jsonschema.Schema
	Execute(ctx context.Context, params json.RawMessage, opts ExecuteOptions) (*ToolResult, error)
}

// Usage would be clean and explicit:
// tool.Execute(ctx, params, EmptyOptions())  // no progress/logging 
// tool.Execute(ctx, params, ExecuteOptions{ProgressReporter: session})  // with MCP features

In this way, MCP-specific features become optional capabilities rather than required dependencies. This enables a richer ecosystem of reusable tools while maintaining full MCP functionality when needed. There are multiple ways to do this but execution options are my preferred approach, perhaps allowing for empty options like we see in the context package (context.Background() or context.TODO())

This is just an example - I am not certain these are the exact right contracts and abstractions. But, in general, with really strong foundational structs and abstractions, a project like this can have influence in the overall structure of tool using LLMs in Go. I understand this adds a layer of abstraction, but I believe the ecosystem benefits outweigh the complexity cost.

Thoughts on this direction? Happy to contribute a more detailed proposal if there's interest although seeing the implementation details will help a lot in thinking through what would be required.

[findleyr]

Thanks for clarifying. CC @jba has been revisiting the tool API as he adds jsonschema validation.

Right now, Tool is the type generated from the spec, and ServerTool is the combination of a Tool and a tool handler. Because ServerTool is a struct, we can safely add to it in the future. If it were an interface, we wouldn't be able to do that (unless we made it a closed interface by adding unexported methods, but then there's little point to the interface).

The requirement to have a ServerTool type is motivated by the desire to use generics in NewTool¹, since Go doesn't support generic methods.

However, I do think it's worth exploring the idea of passing an interface to the tool, rather than the ServerSession itself. This would also solve a related problem I've been looking at for implementing the Streamable HTTP server. Let me explore that idea a bit further.

From your perspective, would it be sufficient to simply modify the current API to pass an interface like CallableResources (albeit with a different name, probably), rather than the ServerSession?

¹ aside: we're planning to rename NewTool to NewServerTool, to be idiomatic.

[mhpenta]

Yes, that would go a long way to allaying my concerns.

Those design decisions around structs versus interfaces makes sense to me. I understand the aim to use generics here - it makes the tool creation elegant:

type WebSearchTool struct {
	client brave.Brave
}

type WebSearchToolQuery struct {
	Query string `json:"query" description:"The search query to send to Brave Search"`
}

func (t *WebSearchToolMCP) ToMCPTool() *mcp.ServerTool {
	return mcp.NewServerTool(
		"brave_web_search",
		"Search the web using Brave Search API for current information",
		t.HandleSearch,
	)
}

func (t *WebSearchTool) HandleSearch(
	ctx context.Context,
	resources mcp.CallableResources,
	params *mcp.CallToolParams[WebSearchToolQuery]) (*mcp.CallToolResult, error) {

	// Log search using resources.LoggingMessage (or whatever)
	// Notify client of progress with resources.NotifyProgress
	
	// Or don't do anything with CallableResources

	results, _ := t.client.WebSearch(ctx, params.Arguments.Query)
	resultJSON, _ := json.Marshal(results)
	return &mcp.CallToolResult{
		Content: []*mcp.Content{
			mcp.NewTextContent(string(resultJSON)),
		},
	}, nil
}

Thanks again, looking forward to seeing the final version. Please feel free to reach out if you want any further comment or feedback.

[jba]

I have to think more about this, but one point jumps out at me.

Go has no security model for code in the same process. It doesn't matter whether you use interfaces, structs, unexported fields, or what have you. The unsafe package, and other techniques like exploiting race conditions, allow any piece of code in the same process to access any piece of memory in that process.

To support true sandboxing of tools, we would have to run them in a separate process, and presumably over some sort of virtual machine like gvisor. I don't think anything like that is in scope for this SDK.

[jba]

I have to think more about this, but one point jumps out at me.

Go has no security model for code in the same process. It doesn't matter whether you use interfaces, structs, unexported fields, or what have you. The unsafe package, and other techniques like exploiting race conditions, allow any piece of code in the same process to access any piece of memory in that process.

To support true sandboxing of tools, we would have to run them in a separate process, and presumably over some sort of virtual machine like gvisor. I don't think anything like that is in scope for this SDK.

[jba]

You do have a point about ServerSession. It exports Close and Wait, which tools shouldn't be calling. I'm not sure if this matters much—in Go we often over-expose types rather than increase complexity with elaborate designs—but perhaps it's worth it here. However, since it wouldn't help with security for the reason I mentioned, I'm not sure what purpose it would serve. if "programmers will include tools into MCP servers they might not fully understand or trust," we have bigger problems than a couple of exposed methods.

[findleyr]

Quick update: at this point, I think the discussion here has run its course (thanks!), though I expect we'll get a lot more feedback once we move code to the official repo. We will do this as soon as possible--we're just blocked on finalizing the antitrust policy mentioned in the governance section.

In the meantime:

1. We're updating the Tool API slightly so that all tools have their schemas validated: https://go.dev/cl/679595. tl;dr: the default CallToolParams.Arguments type is becoming any rather than json.RawMessage, so that we can always run jsonschema validation.
2. We're preparing for the next update to the MCP spec, including output schemas for tools.
3. The streamable transport has implications for handler APIs, since we need to scope server->client messages to the client->server RPC. One way to do this is to expose client capabilities to server handlers as an interface, which coincidentally is what was being requested in https://github.com/orgs/modelcontextprotocol/discussions/364#discussioncomment-13394963.

[SamMorrowDrums]

@findleyr amazing, very excited to try. Do you expect Completions with the updated context spec to be supported soon?

I (roughly) implemented it in a fork of MCP-go, and for template resources in particular the completions spec is virtually useless without, as it's pretty much always the case that subsequent completions are dependent on the prior values. Especially when there are many millions of values, as is the case for GitHub repository content.

I built it before @connor4312 and I submitted the spec suggestion, so naming is old but happy to link.

I was planning to upstream, just got sidetracked.

Code is here: https://github.com/SamMorrowDrums/mcp-go

Ignore the rename, I was rushing to get a demo working.

[LinPr]

Super cool！

[cbrgm]

I'm looking forward to it! Thanks everyone involved for making it possible!

[findleyr]

@SamMorrowDrums yes, completions are one of the major outstanding features, and we plan to implement it soon.

[findleyr]

github.com/modelcontextprotocol/go-sdk now exists (we spent the first couple days of the week setting it up).

It's should still be considered unreleased, but we should continue design discussions there. I'll close out this discussion later today or tomorrow.

[tarunanand-dev]

Hello @findleyr and community,

Following up on my previous post - I have released a Milestone 0 of the MCP Bench at https://github.com/unimcp/mcpbench

MCPBench is the open standard for compatibility testing of various Model Context Protocol (MCP https://github.com/modelcontextprotocol) client and server SDK implementations. As the MCP ecosystem grows, not every server or client will be written in the same language, creating an N×N compatibility matrix where N represents the number of language SDKs available.

Our goal is to ensure seamless interoperability between different MCP implementations, regardless of the programming language used.

Initial SDK Support:

Python SDK (Official)
TypeScript SDK (Official)
Rust SDK (Official)

Future Expansion: Additional language SDKs will be added as the MCP ecosystem grows.

The rest of the details are in the README.

I would love to add support for Go SDK as it becomes available this week or later I would appreciate any insights from the Golang community into what should go into the benchmark in general or specific to golang.

[findleyr]

Thanks, this could be really useful for the community. We've already discovered some bugs testing conformance against different SDKs, and have been meaning to write some automated conformance tests.

If you don't already, you'll probably want to pin a version, as I expect there will be breaking API changes in the next few weeks.

[rwjblue-glean]

Apologies if this has already been discussed, but I don't see how to implement a server that does not manage a long running connection under the proposed implementation. Based on my reading of the spec:

5. If the input is a JSON-RPC request, the server MUST either return Content-Type: text/event-stream, to initiate an SSE stream, or Content-Type: application/json, to return one JSON object. The client MUST support both these cases.

The server is allowed to specifically decide if it wants to start a long running connection (text/event-stream) or simply return the response to the specific request (application/json). In the latter case, there are no "sessions" and each call is effectively stateless.

In mcp-go, this is controlled by server.WithStateLess, which effectively toggles whether or not to initiate a text/event-stream or just a plain application/json response. In a number of simple tool call cases, the persistent connection can just increase the complexity on the hosting side of things.

Perhaps adding an explicit option to StreamableHTTPOptions for that would work? Thoughts?

[findleyr]

@rwjblue-glean we can certainly add this option -- the Streamable HTTP implementation needs several options related to session management.

I didn't implement this initially, because with batching removed I didn't understand how a client is supposed to make stateless requests. The spec requires that the client initialize the session. If the client then wants to make a request, it must send another POST request. How can it do that without a session id?

It seems like other SDKs just allow uninitialized requests in stateless mode, but this doesn't seem compliant with the spec, unless I'm misunderstanding.

[findleyr]

BTW, this concern is effectively modelcontextprotocol/modelcontextprotocol#282.

[rwjblue-glean]

@findleyr - Makes sense! It's a bit unfortunate (the hosting side of things is definitely more complicated having to manage the long running connection and dealing with coordination across servers, redeployments, &c &c), but I totally agree with your take on the spec (upon re-reading the lifecycle section).

Thank you for sharing the link, I'll read through that issue in more detail.

[findleyr]

Looking into this more at your suggestion, it seems that especially in the context of modelcontextprotocol/modelcontextprotocol#478, there is an implicit 'stateless' mode, not mentioned in the spec, where there is no capability negotiation and where protocol version negotiation occurs via HTTP headers.

We'll need to implement this, of course, but I'd like to get some clarification on the spec first to ensure we don't misinterpret the undocumented specification. Thanks for bringing this up.

[rwjblue-glean]

Perfect! I'm also happy to help on the implementation side of things once we figure out what the best way forward on the spec side.

[SamMorrowDrums]

@findleyr I wanted to discuss your code comment on the error interface and make a proposal.

		// TODO(rfindley): investigate why server errors are embedded in this strange way,
		// rather than returned as jsonrpc2 server errors.
		if err != nil {
			return &CallToolResult{
				Content: []*Content{NewTextContent(err.Error())},
				IsError: true,
			}, nil
		}
		return res, nil

Building a remote server, I have wanted middleware to have access to errors that I also want to return to the end user as an error string. I still also want to make coding errors go via the err value. In order to do this I think it would be great if we could use an interface like so:

type CallToolResult interface {
	ToResult() *CallToolResult
}

And enable us to do things like:

• provide an actual error (with types preserved for errors.Is etc.), while being able to serialize into a CallToolResult with a user string message, and IsError: true at the outermost point as the server is actually returning the response. This way middleware can upcast the results and handle accordingly, and the server still only returns mcp content as expected.

Almost all errors in a tool are user-facing, and not coding errors and so should be returning as an error response, with a deliberate message so I get why MCP Go returns them as content, I just want to delay the serialization so I can use real types that preserve the information until serialization is actually necessary.

I thought about just using the error return for this, but held back because:

• coding/implemation errors should return as errors and allow for bubbling up as such
• you cannot easily retain all error information while also specifying the message to return to a user.

With this interface you could then provide some obvious helpers like NewToolResponseFromErr(err) that would return the message err.Error() but would also have a .Err filed in the struct that could be inspected by middleware, and would only be serialized on calling ToResult()

What do you think?

---

edit: I also think that this would be useful for implementing custom typed returns from tool calls, where they just need to fulfil the interface and the SDK is not involved beyond that.

[findleyr]

We were planning to support custom return types via NewServerTool[In, Out], which will put the return types in structured output, but that would be more limiting than what you describe.

We could theoretically have both (NewServerTool could be renamed to allow for multiple ServerTool constructors).

Do you want to move this discussion to a new issue on github.com/modelcontextprotocol/go-sdk?

[jba]

Let's move discussion to modelcontextprotocol/go-sdk#64, where I propose a different solution.

[findleyr]

Hi all, thanks again for the feedback. As noted, since discussion quieted down, we've moved on with the implementation at https://github.com/modelcontextprotocol/go-sdk.

But that doesn't mean the design period is closed. In fact, I encourage you to raise design issues in that repo as either concrete poposals or GitHub discussions (see CONTRIBUTING.md). For example, we're currently having a discussion revisiting the tool binding API in modelcontextprotocol/go-sdk#37.