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
Clientis a logical MCP client, configured with variousClientOptions. - When a client is connected to a server using
Client.Connect, it creates aClientSession. This session is initialized during theConnectmethod, and provides methods to communicate with the server peer. - A
Serveris a logical MCP server, configured with variousServerOptions. - When a server is connected to a client using
Server.Connect, it creates aServerSession. This session is not initialized until the client sends thenotifications/initializedmessage. UseServerOptions.InitializedHandlerto listen for this event, or just use the session through various feature handlers (such as aToolHandler). 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.
func Example_lifecycle() {
ctx := context.Background()
// Create a client and server.
// Wait for the client to initialize the session.
client := mcp.NewClient(&mcp.Implementation{Name: "client", Version: "v0.0.1"}, nil)
server := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.0.1"}, &mcp.ServerOptions{
InitializedHandler: func(context.Context, *mcp.InitializedRequest) {
fmt.Println("initialized!")
},
})
// Connect the server and client using in-memory transports.
//
// Connect the server first so that it's ready to receive initialization
// messages from the client.
t1, t2 := mcp.NewInMemoryTransports()
serverSession, err := server.Connect(ctx, t1, nil)
if err != nil {
log.Fatal(err)
}
clientSession, err := client.Connect(ctx, t2, nil)
if err != nil {
log.Fatal(err)
}
// Now shut down the session by closing the client, and waiting for the
// server session to end.
if err := clientSession.Close(); err != nil {
log.Fatal(err)
}
if err := serverSession.Wait(); err != nil {
log.Fatal(err)
}
// Output: initialized!
}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.
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.
The streamable transport API is implemented across three types:
StreamableHTTPHandler: anhttp.Handlerthat serves streamable MCP sessions.StreamableServerTransport: aTransportthat implements the server side of the streamable transport.StreamableClientTransport: aTransportthat implements the client side of the streamable transport.
To create a streamable MCP server, you create a StreamableHTTPHandler and
pass it an mcp.Server:
// TODO: Until we have a way to clean up abandoned sessions, this test will leak goroutines (see #499)
func ExampleStreamableHTTPHandler() {
// Create a new streamable handler, using the same MCP server for every request.
//
// Here, we configure it to serves application/json responses rather than
// text/event-stream, just so the output below doesn't use random event ids.
server := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.1.0"}, nil)
handler := mcp.NewStreamableHTTPHandler(func(r *http.Request) *mcp.Server {
return server
}, &mcp.StreamableHTTPOptions{JSONResponse: true})
httpServer := httptest.NewServer(handler)
defer httpServer.Close()
// The SDK is currently permissive of some missing keys in "params".
resp := mustPostMessage(`{"jsonrpc": "2.0", "id": 1, "method":"initialize", "params": {}}`, httpServer.URL)
fmt.Println(resp)
// Output:
// {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"logging":{}},"protocolVersion":"2025-06-18","serverInfo":{"name":"server","version":"v0.1.0"}}}
}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.
By default, the streamable server does not support resumability or redelivery of messages, because doing so requires either a persistent storage solution or unbounded memory usage (see also #580).
To enable resumability, set StreamableHTTPOptions.EventStore to a non-nil
value. The SDK provides a MemoryEventStore for testing or simple use cases;
for production use it is generally advisable to use a more sophisticated
implementation.
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#1442 for potential refinements.
See examples/server/distributed for an example using statless mode to implement a server distributed across multiple processes.
For serverless or short-lived processes, configure
StreamableHTTPOptions.SessionStateStore
with an implementation of
ServerSessionStateStore.
The handler will persist ServerSessionState
whenever it changes, and will automatically restore prior state when a request
arrives carrying an existing Mcp-Session-Id. This allows one invocation to
handle initialization while subsequent invocations resume the conversation
without re-running a long-lived server. The SDK provides an in-memory
MemoryServerSessionStateStore
for testing; production deployments should supply a durable store (for example,
backed by a database or object storage).
The SDK supports custom
transports
by implementing the
Transport
interface: a logical bidirectional stream of JSON-RPC messages.
Full example: examples/server/custom-transport.
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/progressornotifications/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.
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-side OAuth is implemented by setting
StreamableClientTransport.HTTPClient to a custom http.Client
Additional support is forthcoming; see #493.
Here we discuss the mitigations described under the MCP spec's Security Best Practices section, and how we handle them.
The mitigation, obtaining user consent for dynamically registered clients, happens on the MCP client. At present we don't provide client-side OAuth support.
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.
The mitigations are as follows:
-
Verify all inbound requests. The
RequireBearerTokenmiddleware 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 usingcrypto/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.
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).
func Example_cancellation() {
// For this example, we're going to be collecting observations from the
// server and client.
var clientResult, serverResult string
var wg sync.WaitGroup
wg.Add(2)
// Create a server with a single slow tool.
// When the client cancels its request, the server should observe
// cancellation.
server := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.0.1"}, nil)
started := make(chan struct{}, 1) // signals that the server started handling the tool call
mcp.AddTool(server, &mcp.Tool{Name: "slow"}, func(ctx context.Context, req *mcp.CallToolRequest, _ any) (*mcp.CallToolResult, any, error) {
started <- struct{}{}
defer wg.Done()
select {
case <-time.After(5 * time.Second):
serverResult = "tool done"
case <-ctx.Done():
serverResult = "tool canceled"
}
return &mcp.CallToolResult{}, nil, nil
})
// Connect a client to the server.
client := mcp.NewClient(&mcp.Implementation{Name: "client", Version: "v0.0.1"}, nil)
ctx := context.Background()
t1, t2 := mcp.NewInMemoryTransports()
if _, err := server.Connect(ctx, t1, nil); err != nil {
log.Fatal(err)
}
session, err := client.Connect(ctx, t2, nil)
if err != nil {
log.Fatal(err)
}
defer session.Close()
// Make a tool call, asynchronously.
ctx, cancel := context.WithCancel(context.Background())
go func() {
defer wg.Done()
_, err = session.CallTool(ctx, &mcp.CallToolParams{Name: "slow"})
clientResult = fmt.Sprintf("%v", err)
}()
// As soon as the server has started handling the call, cancel it from the
// client side.
<-started
cancel()
wg.Wait()
fmt.Println(clientResult)
fmt.Println(serverResult)
// Output:
// context canceled
// tool canceled
}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
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.
func Example_progress() {
server := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.0.1"}, nil)
mcp.AddTool(server, &mcp.Tool{Name: "makeProgress"}, func(ctx context.Context, req *mcp.CallToolRequest, _ any) (*mcp.CallToolResult, any, error) {
if token := req.Params.GetProgressToken(); token != nil {
for i := range 3 {
params := &mcp.ProgressNotificationParams{
Message: "frobbing widgets",
ProgressToken: token,
Progress: float64(i),
Total: 2,
}
req.Session.NotifyProgress(ctx, params) // ignore error
}
}
return &mcp.CallToolResult{}, nil, nil
})
client := mcp.NewClient(&mcp.Implementation{Name: "client", Version: "v0.0.1"}, &mcp.ClientOptions{
ProgressNotificationHandler: func(_ context.Context, req *mcp.ProgressNotificationClientRequest) {
fmt.Printf("%s %.0f/%.0f\n", req.Params.Message, req.Params.Progress, req.Params.Total)
},
})
ctx := context.Background()
t1, t2 := mcp.NewInMemoryTransports()
if _, err := server.Connect(ctx, t1, nil); err != nil {
log.Fatal(err)
}
session, err := client.Connect(ctx, t2, nil)
if err != nil {
log.Fatal(err)
}
defer session.Close()
if _, err := session.CallTool(ctx, &mcp.CallToolParams{
Name: "makeProgress",
Meta: mcp.Meta{"progressToken": "abc123"},
}); err != nil {
log.Fatal(err)
}
// Output:
// frobbing widgets 0/2
// frobbing widgets 1/2
// frobbing widgets 2/2
}