mcp

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 11, 2025 License: MIT Imports: 35 Imported by: 45

Documentation

Overview

The mcp package provides an SDK for writing model context protocol clients and servers.

To get started, create either a Client or Server, and connect it to a peer using a Transport. The diagram below illustrates how this works: 

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

A Client is an MCP client, which can be configured with various client capabilities. Clients may be connected to a Server instance using the Client.Connect method.

Similarly, a Server is an MCP server, which can be configured with various server capabilities. Servers may be connected to one or more Client instances using the Server.Connect method, which creates a ServerSession.

A Transport connects a bidirectional Connection of jsonrpc2 messages. In practice, transports in the MCP spec are are either client transports or server transports. For example, the StdioTransport is a server transport that communicates over stdin/stdout, and its counterpart is a CommandTransport that communicates with a subprocess over its stdin/stdout.

Some transports may hide more complicated details, such as an SSEClientTransport, which reads messages via server-sent events on a hanging GET request, and writes them to a POST endpoint. Users of this SDK may define their own custom Transports by implementing the Transport interface.

Example (ProgressMiddleware)

This middleware function adds a progress token to every outgoing request from the client. 

package main

import (
	"context"
	"sync/atomic"

	"github.com/modelcontextprotocol/go-sdk/mcp"
)

var nextProgressToken atomic.Int64

// This middleware function adds a progress token to every outgoing request
// from the client.
func main() {
	c := mcp.NewClient(testImpl, nil)
	c.AddSendingMiddleware(addProgressToken[*mcp.ClientSession])
	_ = c
}

func addProgressToken[S mcp.Session](h mcp.MethodHandler[S]) mcp.MethodHandler[S] {
	return func(ctx context.Context, s S, method string, params mcp.Params) (result mcp.Result, err error) {
		if rp, ok := params.(mcp.RequestParams); ok {
			rp.SetProgressToken(nextProgressToken.Add(1))
		}
		return h(ctx, s, method, params)
	}
}

Index

Examples

Constants

View Source 
const (
	LevelDebug     = slog.LevelDebug
	LevelInfo      = slog.LevelInfo
	LevelNotice    = (slog.LevelInfo + slog.LevelWarn) / 2
	LevelWarning   = slog.LevelWarn
	LevelError     = slog.LevelError
	LevelCritical  = slog.LevelError + 4
	LevelAlert     = slog.LevelError + 8
	LevelEmergency = slog.LevelError + 12
)

Logging levels.

View Source 
const (
	CodeResourceNotFound = -32002
	// The error code if the method exists and was called properly, but the peer does not support it.
	CodeUnsupportedMethod = -31001
)

Error codes

View Source 
const DefaultPageSize = 1000

Variables

View Source 
var ErrConnectionClosed = errors.New("connection closed")

ErrConnectionClosed is returned when sending a message to a connection that is closed or in the process of closing.

Functions

func AddTool added in v0.2.0 

func AddTool[In, Out any](s *Server, t *Tool, h ToolHandlerFor[In, Out])

AddTool adds a Tool to the server, or replaces one with the same name. If the tool's input schema is nil, it is set to the schema inferred from the In type parameter, using jsonschema.For. If the tool's output schema is nil and the Out type parameter is not the empty interface, then the output schema is set to the schema inferred from Out. The Tool argument must not be modified after this call.

func NewInMemoryTransports 

func NewInMemoryTransports() (*InMemoryTransport, *InMemoryTransport)

NewInMemoryTransports returns two InMemoryTransports that connect to each other.

func ResourceNotFoundError 

func ResourceNotFoundError(uri string) error

ResourceNotFoundError returns an error indicating that a resource being read could not be found.

Types

type Annotations 

type Annotations struct {
	// Describes who the intended customer of this object or data is.
	//
	// It can include multiple entries to indicate content useful for multiple
	// audiences (e.g., []Role{"user", "assistant"}).
	Audience []Role `json:"audience,omitempty"`
	// The moment the resource was last modified, as an ISO 8601 formatted string.
	//
	// Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z").
	//
	// Examples: last activity timestamp in an open file, timestamp when the
	// resource was attached, etc.
	LastModified string `json:"lastModified,omitempty"`
	// Describes how important this data is for operating the server.
	//
	// A value of 1 means "most important," and indicates that the data is
	// effectively required, while 0 means "least important," and indicates that the
	// data is entirely optional.
	Priority float64 `json:"priority,omitempty"`
}

Optional annotations for the client. The client can use annotations to inform how objects are used or displayed

type AudioContent 

type AudioContent struct {
	Data        []byte
	MIMEType    string
	Meta        Meta
	Annotations *Annotations
}

AudioContent contains base64-encoded audio data.

func (AudioContent) MarshalJSON 

func (c AudioContent) MarshalJSON() ([]byte, error)

type CallToolParams 

type CallToolParams = CallToolParamsFor[any]

type CallToolParamsFor 

type CallToolParamsFor[In any] struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta      `json:"_meta,omitempty"`
	Name      string `json:"name"`
	Arguments In     `json:"arguments,omitempty"`
}

func (*CallToolParamsFor[Out]) GetProgressToken 

func (x *CallToolParamsFor[Out]) GetProgressToken() any

func (*CallToolParamsFor[Out]) SetProgressToken 

func (x *CallToolParamsFor[Out]) SetProgressToken(t any)

type CallToolResult 

type CallToolResult = CallToolResultFor[any]

The server's response to a tool call.

type CallToolResultFor 

type CallToolResultFor[Out any] struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// A list of content objects that represent the unstructured result of the tool
	// call.
	Content []Content `json:"content"`
	// An optional JSON object that represents the structured result of the tool
	// call.
	StructuredContent Out `json:"structuredContent,omitempty"`
	// Whether the tool call ended in an error.
	//
	// If not set, this is assumed to be false (the call was successful).
	//
	// Any errors that originate from the tool should be reported inside the result
	// object, with isError set to true, not as an MCP protocol-level error
	// response. Otherwise, the LLM would not be able to see that an error occurred
	// and self-correct.
	//
	// However, any errors in finding the tool, an error indicating that the
	// server does not support tool calls, or any other exceptional conditions,
	// should be reported as an MCP error response.
	IsError bool `json:"isError,omitempty"`
}

func (*CallToolResultFor[Out]) UnmarshalJSON 

func (x *CallToolResultFor[Out]) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the unmarshalling of content into the Content interface.

type CancelledParams 

type CancelledParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An optional string describing the reason for the cancellation. This may be
	// logged or presented to the user.
	Reason string `json:"reason,omitempty"`
	// The ID of the request to cancel.
	//
	// This must correspond to the ID of a request previously issued in the same
	// direction.
	RequestID any `json:"requestId"`
}

func (*CancelledParams) GetProgressToken 

func (x *CancelledParams) GetProgressToken() any

func (*CancelledParams) SetProgressToken 

func (x *CancelledParams) SetProgressToken(t any)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

A Client is an MCP client, which may be connected to an MCP server using the Client.Connect method.

func NewClient 

func NewClient(impl *Implementation, opts *ClientOptions) *Client

NewClient creates a new Client.

Use Client.Connect to connect it to an MCP server.

The first argument must not be nil.

If non-nil, the provided options configure the Client.

func (*Client) AddReceivingMiddleware 

func (c *Client) AddReceivingMiddleware(middleware ...Middleware[*ClientSession])

AddReceivingMiddleware wraps the current receiving method handler using the provided middleware. Middleware is applied from right to left, so that the first one is executed first.

For example, AddReceivingMiddleware(m1, m2, m3) augments the method handler as m1(m2(m3(handler))).

Receiving middleware is called when a request is received. It is useful for tasks such as authentication, request logging and metrics.

func (*Client) AddRoots 

func (c *Client) AddRoots(roots ...*Root)

AddRoots adds the given roots to the client, replacing any with the same URIs, and notifies any connected servers.

func (*Client) AddSendingMiddleware 

func (c *Client) AddSendingMiddleware(middleware ...Middleware[*ClientSession])

AddSendingMiddleware wraps the current sending method handler using the provided middleware. Middleware is applied from right to left, so that the first one is executed first.

For example, AddSendingMiddleware(m1, m2, m3) augments the method handler as m1(m2(m3(handler))).

Sending middleware is called when a request is sent. It is useful for tasks such as tracing, metrics, and adding progress tokens.

func (*Client) Connect 

func (c *Client) Connect(ctx context.Context, t Transport) (cs *ClientSession, err error)

Connect begins an MCP session by connecting to a server over the given transport, and initializing the session.

Typically, it is the responsibility of the client to close the connection when it is no longer needed. However, if the connection is closed by the server, calls or notifications will return an error wrapping ErrConnectionClosed.

func (*Client) RemoveRoots 

func (c *Client) RemoveRoots(uris ...string)

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. TODO: notification

type ClientCapabilities 

type ClientCapabilities struct {
	// Experimental, non-standard capabilities that the client supports.
	Experimental map[string]struct{} `json:"experimental,omitempty"`
	// Present if the client supports listing roots.
	Roots struct {
		// Whether the client supports notifications for changes to the roots list.
		ListChanged bool `json:"listChanged,omitempty"`
	} `json:"roots,omitempty"`
	// Present if the client supports sampling from an LLM.
	Sampling *SamplingCapabilities `json:"sampling,omitempty"`
	// Present if the client supports elicitation from the server.
	Elicitation *ElicitationCapabilities `json:"elicitation,omitempty"`
}

Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.

type ClientOptions 

type ClientOptions struct {
	// Handler for sampling.
	// Called when a server calls CreateMessage.
	CreateMessageHandler func(context.Context, *ClientSession, *CreateMessageParams) (*CreateMessageResult, error)
	// Handlers for notifications from the server.
	ToolListChangedHandler      func(context.Context, *ClientSession, *ToolListChangedParams)
	PromptListChangedHandler    func(context.Context, *ClientSession, *PromptListChangedParams)
	ResourceListChangedHandler  func(context.Context, *ClientSession, *ResourceListChangedParams)
	LoggingMessageHandler       func(context.Context, *ClientSession, *LoggingMessageParams)
	ProgressNotificationHandler func(context.Context, *ClientSession, *ProgressNotificationParams)
	// If non-zero, 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.
	KeepAlive time.Duration
}

ClientOptions configures the behavior of the client.

type ClientSession 

type ClientSession struct {
	// contains filtered or unexported fields
}

A ClientSession is a logical connection with an MCP server. Its methods can be used to send requests or notifications to the server. Create a session by calling Client.Connect.

Call ClientSession.Close to close the connection, or await client termination with ServerSession.Wait.

func (*ClientSession) CallTool 

func (cs *ClientSession) CallTool(ctx context.Context, params *CallToolParams) (*CallToolResult, error)

CallTool calls the tool with the given name and arguments. The arguments can be any value that marshals into a JSON object.

func (*ClientSession) Close 

func (cs *ClientSession) Close() error

Close performs a graceful close of the connection, preventing new requests from being handled, and waiting for ongoing requests to return. Close then terminates the connection.

func (*ClientSession) Complete 

func (cs *ClientSession) Complete(ctx context.Context, params *CompleteParams) (*CompleteResult, error)

func (*ClientSession) GetPrompt 

func (cs *ClientSession) GetPrompt(ctx context.Context, params *GetPromptParams) (*GetPromptResult, error)

GetPrompt gets a prompt from the server.

func (*ClientSession) ID 

func (cs *ClientSession) ID() string

func (*ClientSession) ListPrompts 

func (cs *ClientSession) ListPrompts(ctx context.Context, params *ListPromptsParams) (*ListPromptsResult, error)

ListPrompts lists prompts that are currently available on the server.

func (*ClientSession) ListResourceTemplates 

func (cs *ClientSession) ListResourceTemplates(ctx context.Context, params *ListResourceTemplatesParams) (*ListResourceTemplatesResult, error)

ListResourceTemplates lists the resource templates that are currently available on the server.

func (*ClientSession) ListResources 

func (cs *ClientSession) ListResources(ctx context.Context, params *ListResourcesParams) (*ListResourcesResult, error)

ListResources lists the resources that are currently available on the server.

func (*ClientSession) ListTools 

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

ListTools lists tools that are currently available on the server.

func (*ClientSession) NotifyProgress 

func (cs *ClientSession) NotifyProgress(ctx context.Context, params *ProgressNotificationParams) error

NotifyProgress sends a progress notification from the client to the server associated with this session. This can be used if the client is performing a long-running task that was initiated by the server

func (*ClientSession) Ping 

func (cs *ClientSession) Ping(ctx context.Context, params *PingParams) error

Ping makes an MCP "ping" request to the server.

func (*ClientSession) Prompts 

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

Prompts provides an iterator for all prompts available on the server, automatically fetching pages and managing cursors. The params argument can set the initial cursor. Iteration stops at the first encountered error, which will be yielded.

func (*ClientSession) ReadResource 

func (cs *ClientSession) ReadResource(ctx context.Context, params *ReadResourceParams) (*ReadResourceResult, error)

ReadResource asks the server to read a resource and return its contents.

func (*ClientSession) ResourceTemplates 

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

ResourceTemplates provides an iterator for all resource templates available on the server, automatically fetching pages and managing cursors. The `params` argument can set the initial cursor. Iteration stops at the first encountered error, which will be yielded.

func (*ClientSession) Resources 

func (cs *ClientSession) Resources(ctx context.Context, params *ListResourcesParams) iter.Seq2[*Resource, error]

Resources provides an iterator for all resources available on the server, automatically fetching pages and managing cursors. The params argument can set the initial cursor. Iteration stops at the first encountered error, which will be yielded.

func (*ClientSession) SetLevel 

func (cs *ClientSession) SetLevel(ctx context.Context, params *SetLevelParams) error

func (*ClientSession) Tools 

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

Tools provides an iterator for all tools available on the server, automatically fetching pages and managing cursors. The params argument can set the initial cursor. Iteration stops at the first encountered error, which will be yielded.

func (*ClientSession) Wait 

func (cs *ClientSession) Wait() error

Wait waits for the connection to be closed by the server. Generally, clients should be responsible for closing the connection.

type CommandTransport 

type CommandTransport struct {
	// contains filtered or unexported fields
}

A CommandTransport is a Transport that runs a command and communicates with it over stdin/stdout, using newline-delimited JSON.

func NewCommandTransport 

func NewCommandTransport(cmd *exec.Cmd) *CommandTransport

NewCommandTransport returns a CommandTransport that runs the given command and communicates with it over stdin/stdout.

The resulting transport takes ownership of the command, starting it during CommandTransport.Connect, and stopping it when the connection is closed.

func (*CommandTransport) Connect 

func (t *CommandTransport) Connect(ctx context.Context) (Connection, error)

Connect starts the command, and connects to it over stdin/stdout.

type CompleteContext 

type CompleteContext struct {
	// Previously-resolved variables in a URI template or prompt.
	Arguments map[string]string `json:"arguments,omitempty"`
}

CompleteContext represents additional, optional context for completions.

type CompleteParams 

type CompleteParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// The argument's information
	Argument CompleteParamsArgument `json:"argument"`
	Context  *CompleteContext       `json:"context,omitempty"`
	Ref      *CompleteReference     `json:"ref"`
}

type CompleteParamsArgument 

type CompleteParamsArgument struct {
	// The name of the argument
	Name string `json:"name"`
	// The value of the argument to use for completion matching.
	Value string `json:"value"`
}

type CompleteReference 

type CompleteReference struct {
	Type string `json:"type"`
	// Name is relevant when Type is "ref/prompt".
	Name string `json:"name,omitempty"`
	// URI is relevant when Type is "ref/resource".
	URI string `json:"uri,omitempty"`
}

CompleteReference represents a completion reference type (ref/prompt ref/resource). The Type field determines which other fields are relevant.

func (*CompleteReference) MarshalJSON 

func (r *CompleteReference) MarshalJSON() ([]byte, error)

func (*CompleteReference) UnmarshalJSON 

func (r *CompleteReference) UnmarshalJSON(data []byte) error

type CompleteResult 

type CompleteResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta       `json:"_meta,omitempty"`
	Completion CompletionResultDetails `json:"completion"`
}

The server's response to a completion/complete request

type CompletionResultDetails 

type CompletionResultDetails struct {
	HasMore bool     `json:"hasMore,omitempty"`
	Total   int      `json:"total,omitempty"`
	Values  []string `json:"values"`
}

type Connection 

type Connection interface {
	Read(context.Context) (jsonrpc.Message, error)
	Write(context.Context, jsonrpc.Message) error
	Close() error // may be called concurrently by both peers
	SessionID() string
}

A Connection is a logical bidirectional JSON-RPC connection.

type Content 

type Content interface {
	MarshalJSON() ([]byte, error)
	// contains filtered or unexported methods
}

A Content is a TextContent, ImageContent, AudioContent, ResourceLink, or EmbeddedResource.

type CreateMessageParams 

type CreateMessageParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// A request to include context from one or more MCP servers (including the
	// caller), to be attached to the prompt. The client may ignore this request.
	IncludeContext string `json:"includeContext,omitempty"`
	// The maximum number of tokens to sample, as requested by the server. The
	// client may choose to sample fewer tokens than requested.
	MaxTokens int64              `json:"maxTokens"`
	Messages  []*SamplingMessage `json:"messages"`
	// Optional metadata to pass through to the LLM provider. The format of this
	// metadata is provider-specific.
	Metadata struct{} `json:"metadata,omitempty"`
	// The server's preferences for which model to select. The client may ignore
	// these preferences.
	ModelPreferences *ModelPreferences `json:"modelPreferences,omitempty"`
	StopSequences    []string          `json:"stopSequences,omitempty"`
	// An optional system prompt the server wants to use for sampling. The client
	// may modify or omit this prompt.
	SystemPrompt string  `json:"systemPrompt,omitempty"`
	Temperature  float64 `json:"temperature,omitempty"`
}

func (*CreateMessageParams) GetProgressToken 

func (x *CreateMessageParams) GetProgressToken() any

func (*CreateMessageParams) SetProgressToken 

func (x *CreateMessageParams) SetProgressToken(t any)

type CreateMessageResult 

type CreateMessageResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta    `json:"_meta,omitempty"`
	Content Content `json:"content"`
	// The name of the model that generated the message.
	Model string `json:"model"`
	Role  Role   `json:"role"`
	// The reason why sampling stopped, if known.
	StopReason string `json:"stopReason,omitempty"`
}

The client's response to a sampling/create_message request from the server. The client should inform the user before returning the sampled message, to allow them to inspect the response (human in the loop) and decide whether to allow the server to see it.

type ElicitationCapabilities 

type ElicitationCapabilities struct{}

ElicitationCapabilities describes the capabilities for elicitation.

type EmbeddedResource 

type EmbeddedResource struct {
	Resource    *ResourceContents
	Meta        Meta
	Annotations *Annotations
}

EmbeddedResource contains embedded resources.

func (*EmbeddedResource) MarshalJSON 

func (c *EmbeddedResource) MarshalJSON() ([]byte, error)

type GetPromptParams 

type GetPromptParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// Arguments to use for templating the prompt.
	Arguments map[string]string `json:"arguments,omitempty"`
	// The name of the prompt or prompt template.
	Name string `json:"name"`
}

func (*GetPromptParams) GetProgressToken 

func (x *GetPromptParams) GetProgressToken() any

func (*GetPromptParams) SetProgressToken 

func (x *GetPromptParams) SetProgressToken(t any)

type GetPromptResult 

type GetPromptResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An optional description for the prompt.
	Description string           `json:"description,omitempty"`
	Messages    []*PromptMessage `json:"messages"`
}

The server's response to a prompts/get request from the client.

type ImageContent 

type ImageContent struct {
	Meta        Meta
	Annotations *Annotations
	Data        []byte // base64-encoded
	MIMEType    string
}

ImageContent contains base64-encoded image data.

func (*ImageContent) MarshalJSON 

func (c *ImageContent) MarshalJSON() ([]byte, error)

type Implementation added in v0.2.0 

type Implementation struct {
	// Intended for programmatic or logical use, but used as a display name in past
	// specs or fallback (if title isn't present).
	Name string `json:"name"`
	// Intended for UI and end-user contexts — optimized to be human-readable and
	// easily understood, even by those unfamiliar with domain-specific terminology.
	Title   string `json:"title,omitempty"`
	Version string `json:"version"`
}

An Implementation describes the name and version of an MCP implementation, with an optional title for UI representation.

type InMemoryTransport 

type InMemoryTransport struct {
	// contains filtered or unexported fields
}

An InMemoryTransport is a Transport that communicates over an in-memory network connection, using newline-delimited JSON.

func (*InMemoryTransport) Connect 

func (t *InMemoryTransport) Connect(context.Context) (Connection, error)

type InitializeParams 

type InitializeParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta         `json:"_meta,omitempty"`
	Capabilities *ClientCapabilities `json:"capabilities"`
	ClientInfo   *Implementation     `json:"clientInfo"`
	// The latest version of the Model Context Protocol that the client supports.
	// The client may decide to support older versions as well.
	ProtocolVersion string `json:"protocolVersion"`
}

func (*InitializeParams) GetProgressToken 

func (x *InitializeParams) GetProgressToken() any

func (*InitializeParams) SetProgressToken 

func (x *InitializeParams) SetProgressToken(t any)

type InitializeResult 

type InitializeResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta         `json:"_meta,omitempty"`
	Capabilities *serverCapabilities `json:"capabilities"`
	// Instructions describing how to use the server and its features.
	//
	// This can be used by clients to improve the LLM's understanding of available
	// tools, resources, etc. It can be thought of like a "hint" to the model. For
	// example, this information may be added to the system prompt.
	Instructions string `json:"instructions,omitempty"`
	// The version of the Model Context Protocol that the server wants to use. This
	// may not match the version that the client requested. If the client cannot
	// support this version, it must disconnect.
	ProtocolVersion string          `json:"protocolVersion"`
	ServerInfo      *Implementation `json:"serverInfo"`
}

After receiving an initialize request from the client, the server sends this response.

type InitializedParams 

type InitializedParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
}

func (*InitializedParams) GetProgressToken 

func (x *InitializedParams) GetProgressToken() any

func (*InitializedParams) SetProgressToken 

func (x *InitializedParams) SetProgressToken(t any)

type ListPromptsParams 

type ListPromptsParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An opaque token representing the current pagination position. If provided,
	// the server should return results starting after this cursor.
	Cursor string `json:"cursor,omitempty"`
}

func (*ListPromptsParams) GetProgressToken 

func (x *ListPromptsParams) GetProgressToken() any

func (*ListPromptsParams) SetProgressToken 

func (x *ListPromptsParams) SetProgressToken(t any)

type ListPromptsResult 

type ListPromptsResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An opaque token representing the pagination position after the last returned
	// result. If present, there may be more results available.
	NextCursor string    `json:"nextCursor,omitempty"`
	Prompts    []*Prompt `json:"prompts"`
}

The server's response to a prompts/list request from the client.

type ListResourceTemplatesParams 

type ListResourceTemplatesParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An opaque token representing the current pagination position. If provided,
	// the server should return results starting after this cursor.
	Cursor string `json:"cursor,omitempty"`
}

func (*ListResourceTemplatesParams) GetProgressToken 

func (x *ListResourceTemplatesParams) GetProgressToken() any

func (*ListResourceTemplatesParams) SetProgressToken 

func (x *ListResourceTemplatesParams) SetProgressToken(t any)

type ListResourceTemplatesResult 

type ListResourceTemplatesResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An opaque token representing the pagination position after the last returned
	// result. If present, there may be more results available.
	NextCursor        string              `json:"nextCursor,omitempty"`
	ResourceTemplates []*ResourceTemplate `json:"resourceTemplates"`
}

The server's response to a resources/templates/list request from the client.

type ListResourcesParams 

type ListResourcesParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An opaque token representing the current pagination position. If provided,
	// the server should return results starting after this cursor.
	Cursor string `json:"cursor,omitempty"`
}

func (*ListResourcesParams) GetProgressToken 

func (x *ListResourcesParams) GetProgressToken() any

func (*ListResourcesParams) SetProgressToken 

func (x *ListResourcesParams) SetProgressToken(t any)

type ListResourcesResult 

type ListResourcesResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An opaque token representing the pagination position after the last returned
	// result. If present, there may be more results available.
	NextCursor string      `json:"nextCursor,omitempty"`
	Resources  []*Resource `json:"resources"`
}

The server's response to a resources/list request from the client.

type ListRootsParams 

type ListRootsParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
}

func (*ListRootsParams) GetProgressToken 

func (x *ListRootsParams) GetProgressToken() any

func (*ListRootsParams) SetProgressToken 

func (x *ListRootsParams) SetProgressToken(t any)

type ListRootsResult 

type ListRootsResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta  `json:"_meta,omitempty"`
	Roots []*Root `json:"roots"`
}

The client's response to a roots/list request from the server. This result contains an array of Root objects, each representing a root directory or file that the server can operate on.

type ListToolsParams 

type ListToolsParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An opaque token representing the current pagination position. If provided,
	// the server should return results starting after this cursor.
	Cursor string `json:"cursor,omitempty"`
}

func (*ListToolsParams) GetProgressToken 

func (x *ListToolsParams) GetProgressToken() any

func (*ListToolsParams) SetProgressToken 

func (x *ListToolsParams) SetProgressToken(t any)

type ListToolsResult 

type ListToolsResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An opaque token representing the pagination position after the last returned
	// result. If present, there may be more results available.
	NextCursor string  `json:"nextCursor,omitempty"`
	Tools      []*Tool `json:"tools"`
}

The server's response to a tools/list request from the client.

type LoggingHandler 

type LoggingHandler struct {
	// contains filtered or unexported fields
}

A LoggingHandler is a slog.Handler for MCP.

func NewLoggingHandler 

func NewLoggingHandler(ss *ServerSession, opts *LoggingHandlerOptions) *LoggingHandler

NewLoggingHandler creates a LoggingHandler that logs to the given ServerSession using a slog.JSONHandler.

func (*LoggingHandler) Enabled 

func (h *LoggingHandler) Enabled(ctx context.Context, level slog.Level) bool

Enabled implements slog.Handler.Enabled by comparing level to the ServerSession's level.

func (*LoggingHandler) Handle 

func (h *LoggingHandler) Handle(ctx context.Context, r slog.Record) error

Handle implements slog.Handler.Handle by writing the Record to a JSONHandler, then calling [ServerSession.LoggingMessage] with the result.

func (*LoggingHandler) WithAttrs 

func (h *LoggingHandler) WithAttrs(as []slog.Attr) slog.Handler

WithAttrs implements slog.Handler.WithAttrs.

func (*LoggingHandler) WithGroup 

func (h *LoggingHandler) WithGroup(name string) slog.Handler

WithGroup implements slog.Handler.WithGroup.

type LoggingHandlerOptions 

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
}

LoggingHandlerOptions are options for a LoggingHandler.

type LoggingLevel 

type LoggingLevel string

The severity of a log message.

These map to syslog message severities, as specified in RFC-5424: https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1

type LoggingMessageParams 

type LoggingMessageParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// The data to be logged, such as a string message or an object. Any JSON
	// serializable type is allowed here.
	Data any `json:"data"`
	// The severity of this log message.
	Level LoggingLevel `json:"level"`
	// An optional name of the logger issuing this message.
	Logger string `json:"logger,omitempty"`
}

func (*LoggingMessageParams) GetProgressToken 

func (x *LoggingMessageParams) GetProgressToken() any

func (*LoggingMessageParams) SetProgressToken 

func (x *LoggingMessageParams) SetProgressToken(t any)

type LoggingTransport 

type LoggingTransport struct {
	// contains filtered or unexported fields
}

A LoggingTransport is a Transport that delegates to another transport, writing RPC logs to an io.Writer.

func NewLoggingTransport 

func NewLoggingTransport(delegate Transport, w io.Writer) *LoggingTransport

NewLoggingTransport creates a new LoggingTransport that delegates to the provided transport, writing RPC logs to the provided io.Writer.

func (*LoggingTransport) Connect 

func (t *LoggingTransport) Connect(ctx context.Context) (Connection, error)

Connect connects the underlying transport, returning a Connection that writes logs to the configured destination.

type Meta 

type Meta map[string]any

Meta is additional metadata for requests, responses and other types.

func (Meta) GetMeta 

func (m Meta) GetMeta() map[string]any

GetMeta returns metadata from a value.

func (*Meta) SetMeta 

func (m *Meta) SetMeta(x map[string]any)

SetMeta sets the metadata on a value.

type MethodHandler 

type MethodHandler[S Session] func(ctx context.Context, _ S, method string, params Params) (result Result, err error)

A MethodHandler handles MCP messages. For methods, exactly one of the return values must be nil. For notifications, both must be nil.

type Middleware 

type Middleware[S Session] func(MethodHandler[S]) MethodHandler[S]

Middleware is a function from MethodHandlers to MethodHandlers.

type ModelHint 

type ModelHint struct {
	// A hint for a model name.
	//
	// The client should treat this as a substring of a model name; for example: -
	// `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022` - `sonnet`
	// should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc. -
	// `claude` should match any Claude model
	//
	// The client may also map the string to a different provider's model name or a
	// different model family, as long as it fills a similar niche; for example: -
	// `gemini-1.5-flash` could match `claude-3-haiku-20240307`
	Name string `json:"name,omitempty"`
}

Hints to use for model selection.

Keys not declared here are currently left unspecified by the spec and are up to the client to interpret.

type ModelPreferences 

type ModelPreferences struct {
	// How much to prioritize cost when selecting a model. A value of 0 means cost
	// is not important, while a value of 1 means cost is the most important factor.
	CostPriority float64 `json:"costPriority,omitempty"`
	// Optional hints to use for model selection.
	//
	// If multiple hints are specified, the client must evaluate them in order (such
	// that the first match is taken).
	//
	// The client should prioritize these hints over the numeric priorities, but may
	// still use the priorities to select from ambiguous matches.
	Hints []*ModelHint `json:"hints,omitempty"`
	// How much to prioritize intelligence and capabilities when selecting a model.
	// A value of 0 means intelligence is not important, while a value of 1 means
	// intelligence is the most important factor.
	IntelligencePriority float64 `json:"intelligencePriority,omitempty"`
	// How much to prioritize sampling speed (latency) when selecting a model. A
	// value of 0 means speed is not important, while a value of 1 means speed is
	// the most important factor.
	SpeedPriority float64 `json:"speedPriority,omitempty"`
}

The server's preferences for model selection, requested of the client during sampling.

Because LLMs can vary along multiple dimensions, choosing the "best" model is rarely straightforward. Different models excel in different areas—some are faster but less capable, others are more capable but more expensive, and so on. This interface allows servers to express their priorities across multiple dimensions to help clients make an appropriate selection for their use case.

These preferences are always advisory. The client may ignore them. It is also up to the client to decide how to interpret these preferences and how to balance them against other considerations.

type Params 

type Params interface {
	// GetMeta returns metadata from a value.
	GetMeta() map[string]any
	// SetMeta sets the metadata on a value.
	SetMeta(map[string]any)
}

Params is a parameter (input) type for an MCP call or notification.

type PingParams 

type PingParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
}

func (*PingParams) GetProgressToken 

func (x *PingParams) GetProgressToken() any

func (*PingParams) SetProgressToken 

func (x *PingParams) SetProgressToken(t any)

type ProgressNotificationParams 

type ProgressNotificationParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// An optional message describing the current progress.
	Message string `json:"message,omitempty"`
	// The progress thus far. This should increase every time progress is made, even
	// if the total is unknown.
	Progress float64 `json:"progress"`
	// The progress token which was given in the initial request, used to associate
	// this notification with the request that is proceeding.
	ProgressToken any `json:"progressToken"`
	// Total number of items to process (or total progress required), if known.
	Total float64 `json:"total,omitempty"`
}

type Prompt 

type Prompt struct {
	// See [specification/2025-06-18/basic/index#general-fields] for notes on _meta
	// usage.
	Meta `json:"_meta,omitempty"`
	// A list of arguments to use for templating the prompt.
	Arguments []*PromptArgument `json:"arguments,omitempty"`
	// An optional description of what this prompt provides
	Description string `json:"description,omitempty"`
	// Intended for programmatic or logical use, but used as a display name in past
	// specs or fallback (if title isn't present).
	Name string `json:"name"`
	// Intended for UI and end-user contexts — optimized to be human-readable and
	// easily understood, even by those unfamiliar with domain-specific terminology.
	Title string `json:"title,omitempty"`
}

A prompt or prompt template that the server offers.

type PromptArgument 

type PromptArgument struct {
	// Intended for programmatic or logical use, but used as a display name in past
	// specs or fallback (if title isn't present).
	Name string `json:"name"`
	// Intended for UI and end-user contexts — optimized to be human-readable and
	// easily understood, even by those unfamiliar with domain-specific terminology.
	Title string `json:"title,omitempty"`
	// A human-readable description of the argument.
	Description string `json:"description,omitempty"`
	// Whether this argument must be provided.
	Required bool `json:"required,omitempty"`
}

Describes an argument that a prompt can accept.

type PromptHandler 

type PromptHandler func(context.Context, *ServerSession, *GetPromptParams) (*GetPromptResult, error)

A PromptHandler handles a call to prompts/get.

type PromptListChangedParams 

type PromptListChangedParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
}

func (*PromptListChangedParams) GetProgressToken 

func (x *PromptListChangedParams) GetProgressToken() any

func (*PromptListChangedParams) SetProgressToken 

func (x *PromptListChangedParams) SetProgressToken(t any)

type PromptMessage 

type PromptMessage struct {
	Content Content `json:"content"`
	Role    Role    `json:"role"`
}

Describes a message returned as part of a prompt.

This is similar to SamplingMessage, but also supports the embedding of resources from the MCP server.

func (*PromptMessage) UnmarshalJSON 

func (m *PromptMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the unmarshalling of content into the Content interface.

type ReadResourceParams 

type ReadResourceParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// The URI of the resource to read. The URI can use any protocol; it is up to
	// the server how to interpret it.
	URI string `json:"uri"`
}

func (*ReadResourceParams) GetProgressToken 

func (x *ReadResourceParams) GetProgressToken() any

func (*ReadResourceParams) SetProgressToken 

func (x *ReadResourceParams) SetProgressToken(t any)

type ReadResourceResult 

type ReadResourceResult struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta     `json:"_meta,omitempty"`
	Contents []*ResourceContents `json:"contents"`
}

The server's response to a resources/read request from the client.

type RequestParams 

type RequestParams interface {
	Params

	// GetProgressToken returns the progress token from the params' Meta field, or nil
	// if there is none.
	GetProgressToken() any

	// SetProgressToken sets the given progress token into the params' Meta field.
	// It panics if its argument is not an int or a string.
	SetProgressToken(any)
}

RequestParams is a parameter (input) type for an MCP request.

type Resource 

type Resource struct {
	// See [specification/2025-06-18/basic/index#general-fields] for notes on _meta
	// usage.
	Meta `json:"_meta,omitempty"`
	// Optional annotations for the client.
	Annotations *Annotations `json:"annotations,omitempty"`
	// A description of what this resource represents.
	//
	// This can be used by clients to improve the LLM's understanding of available
	// resources. It can be thought of like a "hint" to the model.
	Description string `json:"description,omitempty"`
	// The MIME type of this resource, if known.
	MIMEType string `json:"mimeType,omitempty"`
	// Intended for programmatic or logical use, but used as a display name in past
	// specs or fallback (if title isn't present).
	Name string `json:"name"`
	// The size of the raw resource content, in bytes (i.e., before base64 encoding
	// or any tokenization), if known.
	//
	// This can be used by Hosts to display file sizes and estimate context window
	// usage.
	Size int64 `json:"size,omitempty"`
	// Intended for UI and end-user contexts — optimized to be human-readable and
	// easily understood, even by those unfamiliar with domain-specific terminology.
	//
	// If not provided, the name should be used for display (except for Tool, where
	// Annotations.Title should be given precedence over using name, if
	// present).
	Title string `json:"title,omitempty"`
	// The URI of this resource.
	URI string `json:"uri"`
}

A known resource that the server is capable of reading.

type ResourceContents 

type ResourceContents struct {
	URI      string `json:"uri"`
	MIMEType string `json:"mimeType,omitempty"`
	Text     string `json:"text,omitempty"`
	Blob     []byte `json:"blob,omitempty"`
	Meta     Meta   `json:"_meta,omitempty"`
}

ResourceContents contains the contents of a specific resource or sub-resource.

func (ResourceContents) MarshalJSON 

func (r ResourceContents) MarshalJSON() ([]byte, error)

type ResourceHandler 

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

A ResourceHandler is a function that reads a resource. It will be called when the client calls ClientSession.ReadResource. If it cannot find the resource, it should return the result of calling ResourceNotFoundError. 

type ResourceLink struct {
	URI         string
	Name        string
	Title       string
	Description string
	MIMEType    string
	Size        *int64
	Meta        Meta
	Annotations *Annotations
}

ResourceLink is a link to a resource

func (*ResourceLink) MarshalJSON 

func (c *ResourceLink) MarshalJSON() ([]byte, error)

type ResourceListChangedParams 

type ResourceListChangedParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
}

func (*ResourceListChangedParams) GetProgressToken 

func (x *ResourceListChangedParams) GetProgressToken() any

func (*ResourceListChangedParams) SetProgressToken 

func (x *ResourceListChangedParams) SetProgressToken(t any)

type ResourceTemplate 

type ResourceTemplate struct {
	// See [specification/2025-06-18/basic/index#general-fields] for notes on _meta
	// usage.
	Meta `json:"_meta,omitempty"`
	// Optional annotations for the client.
	Annotations *Annotations `json:"annotations,omitempty"`
	// A description of what this template is for.
	//
	// This can be used by clients to improve the LLM's understanding of available
	// resources. It can be thought of like a "hint" to the model.
	Description string `json:"description,omitempty"`
	// The MIME type for all resources that match this template. This should only be
	// included if all resources matching this template have the same type.
	MIMEType string `json:"mimeType,omitempty"`
	// Intended for programmatic or logical use, but used as a display name in past
	// specs or fallback (if title isn't present).
	Name string `json:"name"`
	// Intended for UI and end-user contexts — optimized to be human-readable and
	// easily understood, even by those unfamiliar with domain-specific terminology.
	//
	// If not provided, the name should be used for display (except for Tool, where
	// Annotations.Title should be given precedence over using name, if
	// present).
	Title string `json:"title,omitempty"`
	// A URI template (according to RFC 6570) that can be used to construct resource
	// URIs.
	URITemplate string `json:"uriTemplate"`
}

A template description for resources available on the server.

type Result 

type Result interface {
	// GetMeta returns metadata from a value.
	GetMeta() map[string]any
	// SetMeta sets the metadata on a value.
	SetMeta(map[string]any)
}

Result is a result of an MCP call.

type Role 

type Role string

The sender or recipient of messages and data in a conversation.

type Root 

type Root struct {
	// See [specification/2025-06-18/basic/index#general-fields] for notes on _meta
	// usage.
	Meta `json:"_meta,omitempty"`
	// An optional name for the root. This can be used to provide a human-readable
	// identifier for the root, which may be useful for display purposes or for
	// referencing the root in other parts of the application.
	Name string `json:"name,omitempty"`
	// The URI identifying the root. This *must* start with file:// for now. This
	// restriction may be relaxed in future versions of the protocol to allow other
	// URI schemes.
	URI string `json:"uri"`
}

Represents a root directory or file that the server can operate on.

type RootsListChangedParams 

type RootsListChangedParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
}

func (*RootsListChangedParams) GetProgressToken 

func (x *RootsListChangedParams) GetProgressToken() any

func (*RootsListChangedParams) SetProgressToken 

func (x *RootsListChangedParams) SetProgressToken(t any)

type SSEClientTransport 

type SSEClientTransport struct {
	// contains filtered or unexported fields
}

An SSEClientTransport is a Transport that can communicate with an MCP endpoint serving the SSE transport defined by the 2024-11-05 version of the spec.

https://modelcontextprotocol.io/specification/2024-11-05/basic/transports

func NewSSEClientTransport 

func NewSSEClientTransport(baseURL string, opts *SSEClientTransportOptions) *SSEClientTransport

NewSSEClientTransport returns a new client transport that connects to the SSE server at the provided URL.

NewSSEClientTransport panics if the given URL is invalid.

func (*SSEClientTransport) Connect 

func (c *SSEClientTransport) Connect(ctx context.Context) (Connection, error)

Connect connects through the client endpoint.

type SSEClientTransportOptions 

type SSEClientTransportOptions struct {
	// HTTPClient is the client to use for making HTTP requests. If nil,
	// http.DefaultClient is used.
	HTTPClient *http.Client
}

SSEClientTransportOptions provides options for the NewSSEClientTransport constructor.

type SSEHandler 

type SSEHandler struct {
	// contains filtered or unexported fields
}

SSEHandler is an http.Handler that serves SSE-based MCP sessions as defined by the 2024-11-05 version of the MCP spec.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"net/http/httptest"

	"github.com/modelcontextprotocol/go-sdk/mcp"
)

type AddParams struct {
	X, Y int
}

func Add(ctx context.Context, cc *mcp.ServerSession, params *mcp.CallToolParamsFor[AddParams]) (*mcp.CallToolResultFor[any], error) {
	return &mcp.CallToolResultFor[any]{
		Content: []mcp.Content{
			&mcp.TextContent{Text: fmt.Sprintf("%d", params.Arguments.X+params.Arguments.Y)},
		},
	}, nil
}

func main() {
	server := mcp.NewServer(&mcp.Implementation{Name: "adder", Version: "v0.0.1"}, nil)
	mcp.AddTool(server, &mcp.Tool{Name: "add", Description: "add two numbers"}, Add)

	handler := mcp.NewSSEHandler(func(*http.Request) *mcp.Server { return server })
	httpServer := httptest.NewServer(handler)
	defer httpServer.Close()

	ctx := context.Background()
	transport := mcp.NewSSEClientTransport(httpServer.URL, nil)
	client := mcp.NewClient(&mcp.Implementation{Name: "test", Version: "v1.0.0"}, nil)
	cs, err := client.Connect(ctx, transport)
	if err != nil {
		log.Fatal(err)
	}
	defer cs.Close()

	res, err := cs.CallTool(ctx, &mcp.CallToolParams{
		Name:      "add",
		Arguments: map[string]any{"x": 1, "y": 2},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(res.Content[0].(*mcp.TextContent).Text)

}

Output:

3

func NewSSEHandler 

func NewSSEHandler(getServer func(request *http.Request) *Server) *SSEHandler

NewSSEHandler returns a new SSEHandler that creates and manages MCP sessions created via incoming HTTP requests.

Sessions are created when the client issues a GET request to the server, which must accept text/event-stream responses (server-sent events). For each such request, a new SSEServerTransport is created with a distinct messages endpoint, and connected to the server returned by getServer. It is up to the user whether getServer returns a distinct Server for each new request, or reuses an existing server.

The SSEHandler also handles requests to the message endpoints, by delegating them to the relevant server transport.

TODO(rfindley): add options.

func (*SSEHandler) ServeHTTP 

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

type SSEServerTransport 

type SSEServerTransport struct {
	// contains filtered or unexported fields
}

A SSEServerTransport is a logical SSE session created through a hanging GET request.

When connected, it returns the following Connection 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.

func NewSSEServerTransport 

func NewSSEServerTransport(endpoint string, w http.ResponseWriter) *SSEServerTransport

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 (*SSEServerTransport) Connect 

func (t *SSEServerTransport) Connect(context.Context) (Connection, error)

Connect sends the 'endpoint' event to the client. See SSEServerTransport for more details on the Connection implementation.

func (*SSEServerTransport) ServeHTTP 

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

ServeHTTP handles POST requests to the transport endpoint.

type SamplingCapabilities 

type SamplingCapabilities struct{}

SamplingCapabilities describes the capabilities for sampling.

type SamplingMessage 

type SamplingMessage struct {
	Content Content `json:"content"`
	Role    Role    `json:"role"`
}

Describes a message issued to or received from an LLM API.

func (*SamplingMessage) UnmarshalJSON 

func (m *SamplingMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the unmarshalling of content into the Content interface.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

A Server is an instance of an MCP server.

Servers expose server-side MCP features, which can serve one or more MCP sessions by using [Server.Start] or Server.Run.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/modelcontextprotocol/go-sdk/mcp"
)

type SayHiParams struct {
	Name string `json:"name"`
}

func SayHi(ctx context.Context, cc *mcp.ServerSession, params *mcp.CallToolParamsFor[SayHiParams]) (*mcp.CallToolResultFor[any], error) {
	return &mcp.CallToolResultFor[any]{
		Content: []mcp.Content{
			&mcp.TextContent{Text: "Hi " + params.Arguments.Name},
		},
	}, nil
}

func main() {
	ctx := context.Background()
	clientTransport, serverTransport := mcp.NewInMemoryTransports()

	server := mcp.NewServer(&mcp.Implementation{Name: "greeter", Version: "v0.0.1"}, nil)
	mcp.AddTool(server, &mcp.Tool{Name: "greet", Description: "say hi"}, SayHi)

	serverSession, err := server.Connect(ctx, serverTransport)
	if err != nil {
		log.Fatal(err)
	}

	client := mcp.NewClient(&mcp.Implementation{Name: "client"}, nil)
	clientSession, err := client.Connect(ctx, clientTransport)
	if err != nil {
		log.Fatal(err)
	}

	res, err := clientSession.CallTool(ctx, &mcp.CallToolParams{
		Name:      "greet",
		Arguments: map[string]any{"name": "user"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(res.Content[0].(*mcp.TextContent).Text)

	clientSession.Close()
	serverSession.Wait()

}

// createSessions creates and connects an in-memory client and server session for testing purposes.
func createSessions(ctx context.Context) (*mcp.ClientSession, *mcp.ServerSession, *mcp.Server) {
	server := mcp.NewServer(testImpl, nil)
	client := mcp.NewClient(testImpl, nil)
	serverTransport, clientTransport := mcp.NewInMemoryTransports()
	serverSession, err := server.Connect(ctx, serverTransport)
	if err != nil {
		log.Fatal(err)
	}
	clientSession, err := client.Connect(ctx, clientTransport)
	if err != nil {
		log.Fatal(err)
	}
	return clientSession, serverSession, server
}

Output:

Hi user

func NewServer 

func NewServer(impl *Implementation, opts *ServerOptions) *Server

NewServer creates a new MCP server. The resulting server has no features: add features using the various Server.AddXXX methods, and the AddTool function.

The server can be connected to one or more MCP clients using [Server.Start] or Server.Run.

The first argument must not be nil.

If non-nil, the provided options are used to configure the server.

func (*Server) AddPrompt added in v0.2.0 

func (s *Server) AddPrompt(p *Prompt, h PromptHandler)

AddPrompt adds a Prompt to the server, or replaces one with the same name.

func (*Server) AddReceivingMiddleware 

func (s *Server) AddReceivingMiddleware(middleware ...Middleware[*ServerSession])

AddReceivingMiddleware wraps the current receiving method handler using the provided middleware. Middleware is applied from right to left, so that the first one is executed first.

For example, AddReceivingMiddleware(m1, m2, m3) augments the method handler as m1(m2(m3(handler))).

Receiving middleware is called when a request is received. It is useful for tasks such as authentication, request logging and metrics.

func (*Server) AddResource added in v0.2.0 

func (s *Server) AddResource(r *Resource, h ResourceHandler)

AddResource adds a Resource to the server, or replaces one with the same URI. AddResource panics if the resource URI is invalid or not absolute (has an empty scheme).

func (*Server) AddResourceTemplate added in v0.2.0 

func (s *Server) AddResourceTemplate(t *ResourceTemplate, h ResourceHandler)

AddResourceTemplate adds a ResourceTemplate to the server, or replaces on with the same URI. AddResourceTemplate panics if a URI template is invalid or not absolute (has an empty scheme).

func (*Server) AddSendingMiddleware 

func (s *Server) AddSendingMiddleware(middleware ...Middleware[*ServerSession])

AddSendingMiddleware wraps the current sending method handler using the provided middleware. Middleware is applied from right to left, so that the first one is executed first.

For example, AddSendingMiddleware(m1, m2, m3) augments the method handler as m1(m2(m3(handler))).

Sending middleware is called when a request is sent. It is useful for tasks such as tracing, metrics, and adding progress tokens.

func (*Server) AddTool added in v0.2.0 

func (s *Server) AddTool(t *Tool, h ToolHandler)

AddTool adds a Tool to the server, or replaces one with the same name. The tool's input schema must be non-nil. The Tool argument must not be modified after this call.

func (*Server) Connect 

func (s *Server) Connect(ctx context.Context, t Transport) (*ServerSession, error)

Connect connects the MCP server over the given transport and starts handling messages.

It returns a connection object that may be used to terminate the connection (with [Connection.Close]), or await client termination (with [Connection.Wait]).

func (*Server) RemovePrompts 

func (s *Server) RemovePrompts(names ...string)

RemovePrompts removes the prompts with the given names. It is not an error to remove a nonexistent prompt.

func (*Server) RemoveResourceTemplates 

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

RemoveResourceTemplates removes the resource templates with the given URI templates. It is not an error to remove a nonexistent resource.

func (*Server) RemoveResources 

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

RemoveResources removes the resources with the given URIs. It is not an error to remove a nonexistent resource.

func (*Server) RemoveTools 

func (s *Server) RemoveTools(names ...string)

RemoveTools removes the tools with the given names. It is not an error to remove a nonexistent tool.

func (*Server) Run 

func (s *Server) Run(ctx context.Context, t Transport) error

Run runs the server over the given transport, which must be persistent.

Run blocks until the client terminates the connection or the provided context is cancelled. If the context is cancelled, Run closes the connection.

If tools have been added to the server before this call, then the server will advertise the capability for tools, including the ability to send list-changed notifications. If no tools have been added, the server will not have the tool capability. The same goes for other features like prompts and resources.

func (*Server) Sessions 

func (s *Server) Sessions() iter.Seq[*ServerSession]

Sessions returns an iterator that yields the current set of server sessions.

type ServerOptions 

type ServerOptions struct {
	// Optional instructions for connected clients.
	Instructions string
	// If non-nil, called when "notifications/initialized" is received.
	InitializedHandler func(context.Context, *ServerSession, *InitializedParams)
	// PageSize is the maximum number of items to return in a single page for
	// list methods (e.g. ListTools).
	PageSize int
	// If non-nil, called when "notifications/roots/list_changed" is received.
	RootsListChangedHandler func(context.Context, *ServerSession, *RootsListChangedParams)
	// If non-nil, called when "notifications/progress" is received.
	ProgressNotificationHandler func(context.Context, *ServerSession, *ProgressNotificationParams)
	// If non-nil, called when "completion/complete" is received.
	CompletionHandler func(context.Context, *ServerSession, *CompleteParams) (*CompleteResult, error)
	// If non-zero, 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.
	KeepAlive time.Duration
}

ServerOptions is used to configure behavior of the server.

type ServerSession 

type ServerSession struct {
	// contains filtered or unexported fields
}

A ServerSession is a logical connection from a single MCP client. Its methods can be used to send requests or notifications to the client. Create a session by calling Server.Connect.

Call ServerSession.Close to close the connection, or await client termination with ServerSession.Wait.

func (*ServerSession) Close 

func (ss *ServerSession) Close() error

Close performs a graceful shutdown of the connection, preventing new requests from being handled, and waiting for ongoing requests to return. Close then terminates the connection.

func (*ServerSession) CreateMessage 

func (ss *ServerSession) CreateMessage(ctx context.Context, params *CreateMessageParams) (*CreateMessageResult, error)

CreateMessage sends a sampling request to the client.

func (*ServerSession) ID 

func (ss *ServerSession) ID() string

func (*ServerSession) ListRoots 

func (ss *ServerSession) ListRoots(ctx context.Context, params *ListRootsParams) (*ListRootsResult, error)

ListRoots lists the client roots.

func (*ServerSession) Log 

func (ss *ServerSession) Log(ctx context.Context, params *LoggingMessageParams) error

Log sends a log message to the client. The message is not sent if the client has not called SetLevel, or if its level is below that of the last SetLevel.

func (*ServerSession) NotifyProgress 

func (ss *ServerSession) NotifyProgress(ctx context.Context, params *ProgressNotificationParams) error

NotifyProgress sends a progress notification from the server to the client associated with this session. This is typically used to report on the status of a long-running request that was initiated by the client.

func (*ServerSession) Ping 

func (ss *ServerSession) Ping(ctx context.Context, params *PingParams) error

Ping pings the client.

func (*ServerSession) Wait 

func (ss *ServerSession) Wait() error

Wait waits for the connection to be closed by the client.

type Session 

type Session interface {
	*ClientSession | *ServerSession
	// ID returns the session ID, or the empty string if there is none.
	ID() string
	// contains filtered or unexported methods
}

A Session is either a ClientSession or a ServerSession.

type SetLevelParams 

type SetLevelParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
	// The level of logging that the client wants to receive from the server. The
	// server should send all logs at this level and higher (i.e., more severe) to
	// the client as notifications/message.
	Level LoggingLevel `json:"level"`
}

func (*SetLevelParams) GetProgressToken 

func (x *SetLevelParams) GetProgressToken() any

func (*SetLevelParams) SetProgressToken 

func (x *SetLevelParams) SetProgressToken(t any)

type StdioTransport 

type StdioTransport struct {
	// contains filtered or unexported fields
}

A StdioTransport is a Transport that communicates over stdin/stdout using newline-delimited JSON.

func NewStdioTransport 

func NewStdioTransport() *StdioTransport

NewStdioTransport constructs a transport that communicates over stdin/stdout.

func (*StdioTransport) Connect 

func (t *StdioTransport) Connect(context.Context) (Connection, error)

type StreamableClientTransport 

type StreamableClientTransport struct {
	// contains filtered or unexported fields
}

A StreamableClientTransport is a Transport that can communicate with an MCP endpoint serving the streamable HTTP transport defined by the 2025-03-26 version of the spec.

TODO(rfindley): support retries and resumption tokens.

func NewStreamableClientTransport 

func NewStreamableClientTransport(url string, opts *StreamableClientTransportOptions) *StreamableClientTransport

NewStreamableClientTransport returns a new client transport that connects to the streamable HTTP server at the provided URL.

func (*StreamableClientTransport) Connect 

func (t *StreamableClientTransport) Connect(ctx context.Context) (Connection, error)

Connect implements the Transport interface.

The resulting Connection writes messages via POST requests to the transport URL with the Mcp-Session-Id header set, and reads messages from hanging requests.

When closed, the connection issues a DELETE request to terminate the logical session.

type StreamableClientTransportOptions 

type StreamableClientTransportOptions struct {
	// HTTPClient is the client to use for making HTTP requests. If nil,
	// http.DefaultClient is used.
	HTTPClient *http.Client
}

StreamableClientTransportOptions provides options for the NewStreamableClientTransport constructor.

type StreamableHTTPHandler 

type StreamableHTTPHandler struct {
	// contains filtered or unexported fields
}

A StreamableHTTPHandler is an http.Handler that serves streamable MCP sessions, as defined by the MCP spec.

func NewStreamableHTTPHandler 

func NewStreamableHTTPHandler(getServer func(*http.Request) *Server, opts *StreamableHTTPOptions) *StreamableHTTPHandler

NewStreamableHTTPHandler returns a new StreamableHTTPHandler.

The getServer function is used to create or look up servers for new sessions. It is OK for getServer to return the same server multiple times.

func (*StreamableHTTPHandler) ServeHTTP 

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

type StreamableHTTPOptions 

type StreamableHTTPOptions struct {
}

StreamableHTTPOptions is a placeholder options struct for future configuration of the StreamableHTTP handler.

type StreamableServerTransport 

type StreamableServerTransport struct {
	// contains filtered or unexported fields
}

A StreamableServerTransport implements the Transport interface for a single session.

func NewStreamableServerTransport 

func NewStreamableServerTransport(sessionID string) *StreamableServerTransport

NewStreamableServerTransport returns a new StreamableServerTransport with the given session ID.

A StreamableServerTransport implements the server-side of the streamable transport.

TODO(rfindley): consider adding options here, to configure event storage policy.

func (*StreamableServerTransport) Close 

func (t *StreamableServerTransport) Close() error

Close implements the Connection interface.

func (*StreamableServerTransport) Connect 

func (s *StreamableServerTransport) Connect(context.Context) (Connection, error)

Connect implements the Transport interface.

TODO(rfindley): Connect should return a new object.

func (*StreamableServerTransport) Read 

func (t *StreamableServerTransport) Read(ctx context.Context) (jsonrpc.Message, error)

Read implements the Connection interface.

func (*StreamableServerTransport) ServeHTTP 

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

ServeHTTP handles a single HTTP request for the session.

func (*StreamableServerTransport) SessionID 

func (t *StreamableServerTransport) SessionID() string

func (*StreamableServerTransport) Write 

func (t *StreamableServerTransport) Write(ctx context.Context, msg jsonrpc.Message) error

Write implements the Connection interface.

type TextContent 

type TextContent struct {
	Text        string
	Meta        Meta
	Annotations *Annotations
}

TextContent is a textual content.

func (*TextContent) MarshalJSON 

func (c *TextContent) MarshalJSON() ([]byte, error)

type Tool 

type Tool struct {
	// See [specification/2025-06-18/basic/index#general-fields] for notes on _meta
	// usage.
	Meta `json:"_meta,omitempty"`
	// Optional additional tool information.
	//
	// Display name precedence order is: title, annotations.title, then name.
	Annotations *ToolAnnotations `json:"annotations,omitempty"`
	// A human-readable description of the tool.
	//
	// This can be used by clients to improve the LLM's understanding of available
	// tools. It can be thought of like a "hint" to the model.
	Description string `json:"description,omitempty"`
	// A JSON Schema object defining the expected parameters for the tool.
	InputSchema *jsonschema.Schema `json:"inputSchema"`
	// Intended for programmatic or logical use, but used as a display name in past
	// specs or fallback (if title isn't present).
	Name string `json:"name"`
	// An optional JSON Schema object defining the structure of the tool's output
	// returned in the structuredContent field of a CallToolResult.
	OutputSchema *jsonschema.Schema `json:"outputSchema,omitempty"`
	// Intended for UI and end-user contexts — optimized to be human-readable and
	// easily understood, even by those unfamiliar with domain-specific terminology.
	// If not provided, Annotations.Title should be used for display if present,
	// otherwise Name.
	Title string `json:"title,omitempty"`
}

Definition for a tool the client can call.

type ToolAnnotations 

type ToolAnnotations struct {
	// If true, the tool may perform destructive updates to its environment. If
	// false, the tool performs only additive updates.
	//
	// (This property is meaningful only when ReadOnlyHint == false.)
	//
	// Default: true
	DestructiveHint *bool `json:"destructiveHint,omitempty"`
	// If true, calling the tool repeatedly with the same arguments will have no
	// additional effect on the its environment.
	//
	// (This property is meaningful only when ReadOnlyHint == false.)
	//
	// Default: false
	IdempotentHint bool `json:"idempotentHint,omitempty"`
	// If true, this tool may interact with an "open world" of external entities. If
	// false, the tool's domain of interaction is closed. For example, the world of
	// a web search tool is open, whereas that of a memory tool is not.
	//
	// Default: true
	OpenWorldHint *bool `json:"openWorldHint,omitempty"`
	// If true, the tool does not modify its environment.
	//
	// Default: false
	ReadOnlyHint bool `json:"readOnlyHint,omitempty"`
	// A human-readable title for the tool.
	Title string `json:"title,omitempty"`
}

Additional properties describing a Tool to clients.

NOTE: all properties in ToolAnnotations are hints. They are not guaranteed to provide a faithful description of tool behavior (including descriptive properties like title).

Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers.

type ToolHandler 

type ToolHandler = ToolHandlerFor[map[string]any, any]

A ToolHandler handles a call to tools/call. [CallToolParams.Arguments] will contain a map[string]any that has been validated against the input schema.

type ToolHandlerFor 

type ToolHandlerFor[In, Out any] func(context.Context, *ServerSession, *CallToolParamsFor[In]) (*CallToolResultFor[Out], error)

A ToolHandlerFor handles a call to tools/call with typed arguments and results.

type ToolListChangedParams 

type ToolListChangedParams struct {
	// This property is reserved by the protocol to allow clients and servers to
	// attach additional metadata to their responses.
	Meta `json:"_meta,omitempty"`
}

func (*ToolListChangedParams) GetProgressToken 

func (x *ToolListChangedParams) GetProgressToken() any

func (*ToolListChangedParams) SetProgressToken 

func (x *ToolListChangedParams) SetProgressToken(t any)

type Transport 

type Transport interface {
	// Connect returns the logical JSON-RPC connection..
	//
	// It is called exactly once by [Server.Connect] or [Client.Connect].
	Connect(ctx context.Context) (Connection, error)
}

A Transport is used to create a bidirectional connection between MCP client and server.

Transports should be used for at most one call to Server.Connect or Client.Connect.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.