go-sdk/internal/docs/protocol.src.md

Support for the MCP base protocol

%toc

Lifecycle

The SDK provides an API for defining both MCP clients and servers, and connecting them over various transports. When a client and server are connected, it creates a logical session, which follows the MCP spec's lifecycle.

In this SDK, both a Client and Server can handle multiple peers. Every time a new peer is connected, it creates a new session.

• A Client is a logical MCP client, configured with various ClientOptions.
• When a client is connected to a server using Client.Connect, it creates a ClientSession. This session is initialized during the Connect method, and provides methods to communicate with the server peer.
• A Server is a logical MCP server, configured with various ServerOptions.
• When a server is connected to a client using Server.Connect, it creates a ServerSession. This session is not initialized until the client sends the notifications/initialized message. Use ServerOptions.InitializedHandler to listen for this event, or just use the session through various feature handlers (such as a ToolHandler). Requests to the server are rejected until the client has initialized the session.

Both ClientSession and ServerSession have a Close method to terminate the session, and a Wait method to await session termination by the peer. Typically, it is the client's responsibility to end the session.

%include ../../mcp/mcp_example_test.go lifecycle -

Transports

A transport can be used to send JSON-RPC messages from client to server, or vice-versa.

In the SDK, this is achieved by implementing the Transport interface, which creates a (logical) bidirectional stream of JSON-RPC messages. Most transport implementations described below are specific to either the client or server: a "client transport" is something that can be used to connect a client to a server, and a "server transport" is something that can be used to connect a server to a client. However, it's possible for a transport to be both a client and server transport, such as the InMemoryTransport used in the lifecycle example above.

Transports should not be reused for multiple connections: if you need to create multiple connections, use different transports.

Stdio Transport

In the stdio transport clients communicate with an MCP server running in a subprocess using newline-delimited JSON over its stdin/stdout.

Client-side: the client side of the stdio transport is implemented by CommandTransport, which starts the a exec.Cmd as a subprocess and communicates over its stdin/stdout.

Server-side: the server side of the stdio transport is implemented by StdioTransport, which connects over the current processes os.Stdin and os.Stdout.

Streamable Transport

The streamable transport API is implemented across three types:

• StreamableHTTPHandler: anhttp.Handler that serves streamable MCP sessions.
• StreamableServerTransport: a Transport that implements the server side of the streamable transport.
• StreamableClientTransport: a Transport that implements the client side of the streamable transport.

To create a streamable MCP server, you create a StreamableHTTPHandler and pass it an mcp.Server:

%include ../../mcp/streamable_example_test.go streamablehandler -

The StreamableHTTPHandler handles the HTTP requests and creates a new StreamableServerTransport for each new session. The transport is then used to communicate with the client.

On the client side, you create a StreamableClientTransport and use it to connect to the server:

transport := &mcp.StreamableClientTransport{
	Endpoint: "http://localhost:8080/mcp",
}
client, err := mcp.Connect(ctx, transport, &mcp.ClientOptions{...})

The StreamableClientTransport handles the HTTP requests and communicates with the server using the streamable transport protocol.

Stateless Mode

The streamable server supports a stateless mode by setting StreamableHTTPOptions.Stateless, which is where the server does not perform any validation of the session id, and uses a temporary session to handle requests. In this mode, it is impossible for the server to make client requests, as there is no way for the client's response to reach the session.

However, it is still possible for the server to access the ServerSession.ID to see the logical session

Warning

Stateless mode is not directly discussed in the spec, and is still being defined. See modelcontextprotocol/modelcontextprotocol#1364, modelcontextprotocol/modelcontextprotocol#1372, or modelcontextprotocol/modelcontextprotocol#11442 for potential refinements.

See examples/server/distributed for an example using statless mode to implement a server distributed across multiple processes.

Custom transports

The SDK supports custom transports by implementing the Transport interface: a logical bidirectional stream of JSON-RPC messages.

Full example: examples/server/custom-transport.

Concurrency

In general, MCP offers no guarantees about concurrency semantics: if a client or server sends a notification, the spec says nothing about when the peer observes that notification relative to other request. However, the Go SDK implements the following heuristics:

• If a notifying method (such as notifications/progress or notifications/initialized) returns, then it is guaranteed that the peer observes that notification before other notifications or calls from the same client goroutine.
• Calls (such as tools/call) are handled asynchronously with respect to each other.

See modelcontextprotocol/go-sdk#26 for more background.

Authorization

Server

To write an MCP server that performs authorization, use RequireBearerToken. This function is middleware that wraps an HTTP handler, such as the one returned by NewStreamableHTTPHandler, to provide support for verifying bearer tokens. The middleware function checks every request for an Authorization header with a bearer token, and invokes the TokenVerifier passed to RequireBearerToken to parse the token and perform validation. The middleware function checks expiration and scopes (if they are provided in RequireBearerTokenOptions.Scopes), so the TokenVerifer doesn't have to. If RequireBearerTokenOptions.ResourceMetadataURL is set and verification fails, the middleware function sets the WWW-Authenticate header as required by the Protected Resource Metadata spec.

Server handlers, such as tool handlers, can obtain the TokenInfo returned by the TokenVerifier from req.Extra.TokenInfo, where req is the handler's request. (For example, a CallToolRequest.) HTTP handlers wrapped by the RequireBearerToken middleware can obtain the TokenInfo from the context with auth.TokenInfoFromContext.

The auth middleware example shows how to implement authorization for both JWT tokens and API keys.

Client

Client-side OAuth is implemented by setting
StreamableClientTransport.HTTPClient to a custom http.Client Additional support is forthcoming; see #493.

Security

Here we discuss the mitigations described under the MCP spec's Security Best Practices section, and how we handle them.

Confused Deputy

The mitigation, obtaining user consent for dynamically registered clients, happens on the MCP client. At present we don't provide client-side OAuth support.

Token Passthrough

The mitigation, accepting only tokens that were issued for the server, depends on the structure of tokens and is the responsibility of the TokenVerifier provided to RequireBearerToken.

Session Hijacking

The mitigations are as follows:

• Verify all inbound requests. The RequireBearerToken middleware function will verify all HTTP requests that it receives. It is the user's responsibility to wrap that function around all handlers in their server.

• Secure session IDs. This SDK generates cryptographically secure session IDs by default. If you create your own with ServerOptions.GetSessionID, it is your responsibility to ensure they are secure. If you are using Go 1.24 or above, we recommend using crypto/rand.Text

• Binding session IDs to user information. This is an application requirement, out of scope for the SDK. You can create your own session IDs by setting ServerOptions.GetSessionID.

Utilities

Cancellation

Cancellation is implemented with context cancellation. Cancelling a context used in a method on ClientSession or ServerSession will terminate the RPC and send a "notifications/cancelled" message to the peer.

When an RPC exits due to a cancellation error, there's a guarantee that the cancellation notification has been sent, but there's no guarantee that the server has observed it (see concurrency).

%include ../../mcp/mcp_example_test.go cancellation -

Ping

Ping support is symmetrical for client and server.

To initiate a ping, call ClientSession.Ping or ServerSession.Ping.

To have the client or server session automatically ping its peer, and close the session if the ping fails, set ClientOptions.KeepAlive or ServerOptions.KeepAlive.

Progress

Progress reporting is possible by reading the progress token from request metadata and calling either ClientSession.NotifyProgress or ServerSession.NotifyProgress. To listen to progress notifications, set ClientOptions.ProgressNotificationHandler or ServerOptions.ProgressNotificationHandler.

Issue #460 discusses some potential ergonomic improvements to this API.

%include ../../mcp/mcp_example_test.go progress -