or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

auth.mdindex.mdjsonrpc.mdmcp-client.mdmcp-protocol.mdmcp-server.mdmcp-transports.mdmcp-types.mdoauthex.md
tile.json

mcp-server.mddocs/

MCP Server

The MCP server implementation enables exposing tools, prompts, and resources to MCP clients, with support for multiple concurrent sessions.

Server Construction

NewServer

Creates a new MCP server.

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

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

Parameters:

  • impl: Implementation information (must not be nil)
  • options: Optional server configuration

Example:

server := mcp.NewServer(&mcp.Implementation{
    Name:    "my-server",
    Version: "1.0.0",
}, &mcp.ServerOptions{
    Instructions: "This server provides data analysis tools",
})

ServerOptions

Configures server behavior and capabilities.

type ServerOptions struct {
    Instructions                string
    Logger                      *slog.Logger
    InitializedHandler          func(context.Context, *InitializedRequest)
    PageSize                    int
    RootsListChangedHandler     func(context.Context, *RootsListChangedRequest)
    ProgressNotificationHandler func(context.Context, *ProgressNotificationServerRequest)
    CompletionHandler           func(context.Context, *CompleteRequest) (*CompleteResult, error)
    KeepAlive                   time.Duration
    SubscribeHandler            func(context.Context, *SubscribeRequest) error
    UnsubscribeHandler          func(context.Context, *UnsubscribeRequest) error
    HasPrompts                  bool
    HasResources                bool
    HasTools                    bool
    GetSessionID                func() string
}

Fields:

  • Instructions: Optional instructions for connected clients
  • Logger: If non-nil, log server activity
  • InitializedHandler: Called when "notifications/initialized" is received
  • PageSize: Maximum items per page in list methods (default: 1000)
  • RootsListChangedHandler: Called when client roots list changes
  • ProgressNotificationHandler: Called when client sends progress notifications
  • CompletionHandler: Called for completion/complete requests
  • KeepAlive: Interval for automatic ping requests (0 disables)
  • SubscribeHandler: Called when a client subscribes to a resource
  • UnsubscribeHandler: Called when a client unsubscribes from a resource
  • HasPrompts: Advertise prompts capability even if no prompts registered
  • HasResources: Advertise resources capability even if no resources registered
  • HasTools: Advertise tools capability even if no tools registered
  • GetSessionID: Provides session ID for incoming requests (default: random)

DefaultPageSize

Default maximum items per page for list operations.

const DefaultPageSize = 1000

Server Methods

Run

Runs the server on a given transport (blocking).

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

Parameters:

  • ctx: Context for the server operation
  • t: Transport to use for communication

Example:

if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
    log.Fatal(err)
}

Connect

Connects the server over a transport and returns a session.

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

Parameters:

  • ctx: Context for the connection operation
  • t: Transport to use for communication
  • opts: Optional session configuration

Returns: A new ServerSession for interacting with the client

Sessions

Returns an iterator over all current server sessions.

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

Example:

for session := range server.Sessions() {
    fmt.Printf("Session ID: %s\n", session.ID())
}

AddSendingMiddleware

Wraps the sending method handler with middleware.

func (s *Server) AddSendingMiddleware(middleware ...Middleware)

AddReceivingMiddleware

Wraps the receiving method handler with middleware.

func (s *Server) AddReceivingMiddleware(middleware ...Middleware)

Tool Management

AddTool (Generic)

Adds a tool with typed input and output to the server.

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

Type Parameters:

  • In: Input type for tool arguments (must be JSON-marshalable)
  • Out: Output type for tool results (use any for no output schema)

Parameters:

  • s: Server to add the tool to
  • t: Tool definition
  • h: Typed tool handler function

Behavior:

  • Automatically generates input schema from In type if not set
  • Automatically generates output schema from Out type if not set and Out is not any
  • Validates inputs according to schema
  • Populates structured output automatically

Example:

type CalculateInput struct {
    X float64 `json:"x" jsonschema:"first number"`
    Y float64 `json:"y" jsonschema:"second number"`
}

type CalculateOutput struct {
    Result float64 `json:"result"`
}

mcp.AddTool(server, &mcp.Tool{
    Name:        "add",
    Description: "Adds two numbers",
}, func(ctx context.Context, req *mcp.CallToolRequest, in CalculateInput) (*mcp.CallToolResult, CalculateOutput, error) {
    return nil, CalculateOutput{Result: in.X + in.Y}, nil
})

AddTool (Method)

Adds a tool with a low-level handler to the server.

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

Parameters:

  • t: Tool definition
  • h: Tool handler function

Example:

server.AddTool(&mcp.Tool{
    Name:        "echo",
    Description: "Echoes input",
    InputSchema: map[string]any{
        "type": "object",
        "properties": map[string]any{
            "message": map[string]any{"type": "string"},
        },
    },
}, func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    var args struct {
        Message string `json:"message"`
    }
    if err := json.Unmarshal(req.Params.Arguments, &args); err != nil {
        return nil, err
    }
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: args.Message},
        },
    }, nil
})

RemoveTools

Removes tools by name and notifies connected clients.

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

Parameters:

  • names: Names of tools to remove

ToolHandler

Low-level tool handler function type.

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

ToolHandlerFor

Typed tool handler function type (used with generic AddTool).

type ToolHandlerFor[In, Out any] func(
    _ context.Context,
    request *CallToolRequest,
    input In,
) (result *CallToolResult, output Out, _ error)

Parameters:

  • ctx: Request context
  • request: Tool call request with metadata
  • input: Validated and unmarshaled input

Returns:

  • result: Call result (can be nil to use defaults)
  • output: Structured output (automatically populated in result)
  • error: Error if tool execution failed

Prompt Management

AddPrompt

Adds a prompt template to the server.

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

Parameters:

  • p: Prompt definition
  • h: Prompt handler function

Example:

server.AddPrompt(&mcp.Prompt{
    Name:        "greeting",
    Description: "Generate a greeting",
    Arguments: []*mcp.PromptArgument{
        {Name: "name", Description: "Person to greet", Required: true},
        {Name: "language", Description: "Language code", Required: false},
    },
}, func(ctx context.Context, req *mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
    name := req.Params.Arguments["name"]
    language := req.Params.Arguments["language"]

    greeting := "Hello"
    if language == "es" {
        greeting = "Hola"
    }

    return &mcp.GetPromptResult{
        Messages: []*mcp.PromptMessage{
            {
                Role: "user",
                Content: &mcp.TextContent{
                    Text: fmt.Sprintf("%s, %s!", greeting, name),
                },
            },
        },
    }, nil
})

RemovePrompts

Removes prompts by name and notifies connected clients.

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

PromptHandler

Prompt handler function type.

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

Resource Management

AddResource

Adds a resource to the server.

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

Parameters:

  • r: Resource definition
  • h: Resource handler function

Example:

server.AddResource(&mcp.Resource{
    URI:         "file:///data/users.json",
    Name:        "users",
    Description: "User database",
    MIMEType:    "application/json",
}, func(ctx context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    data, err := os.ReadFile("/data/users.json")
    if err != nil {
        return nil, err
    }
    return &mcp.ReadResourceResult{
        Contents: []*mcp.ResourceContents{
            {
                URI:      req.Params.URI,
                MIMEType: "application/json",
                Text:     string(data),
            },
        },
    }, nil
})

AddResourceTemplate

Adds a resource template to the server.

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

Parameters:

  • t: Resource template definition
  • h: Resource handler function

Example:

server.AddResourceTemplate(&mcp.ResourceTemplate{
    URITemplate: "file:///data/{filename}",
    Name:        "data-files",
    Description: "Access data files",
    MIMEType:    "text/plain",
}, func(ctx context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
    // Extract filename from URI
    u, _ := url.Parse(req.Params.URI)
    filename := filepath.Base(u.Path)

    data, err := os.ReadFile(filepath.Join("/data", filename))
    if err != nil {
        return nil, mcp.ResourceNotFoundError(req.Params.URI)
    }

    return &mcp.ReadResourceResult{
        Contents: []*mcp.ResourceContents{
            {URI: req.Params.URI, Text: string(data)},
        },
    }, nil
})

RemoveResources

Removes resources by URI and notifies connected clients.

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

RemoveResourceTemplates

Removes resource templates by URI template and notifies connected clients.

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

ResourceUpdated

Notifies subscribed clients that a resource has been updated.

func (s *Server) ResourceUpdated(
    ctx context.Context,
    params *ResourceUpdatedNotificationParams,
) error

Parameters:

  • ctx: Context for the operation
  • params: Notification parameters with resource URI

Example:

err := server.ResourceUpdated(ctx, &mcp.ResourceUpdatedNotificationParams{
    URI: "file:///data/users.json",
})

ResourceHandler

Resource handler function type.

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

ResourceNotFoundError

Creates an error for resource not found scenarios.

func ResourceNotFoundError(uri string) error

ServerSession

A ServerSession represents a logical connection from a single MCP client. Its methods send requests or notifications to the client.

Sampling Operations

CreateMessage

Sends a sampling request to the client (asks client to call an LLM).

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

Example:

result, err := session.CreateMessage(ctx, &mcp.CreateMessageParams{
    Messages: []*mcp.SamplingMessage{
        {
            Role: "user",
            Content: &mcp.TextContent{Text: "What is 2+2?"},
        },
    },
    MaxTokens: 100,
})

Elicitation Operations

Elicit

Sends an elicitation request to the client (asks user for information).

func (ss *ServerSession) Elicit(
    ctx context.Context,
    params *ElicitParams,
) (*ElicitResult, error)

Example:

result, err := session.Elicit(ctx, &mcp.ElicitParams{
    Message: "Please enter your API key",
    RequestedSchema: map[string]any{
        "type": "object",
        "properties": map[string]any{
            "apiKey": map[string]any{"type": "string"},
        },
    },
})

Root Operations

ListRoots

Lists the client's roots.

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

Logging Operations

Log

Sends a log message to the client.

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

Example:

err := session.Log(ctx, &mcp.LoggingMessageParams{
    Level:  mcp.LevelInfo,
    Logger: "my-server",
    Data:   "Processing request",
})

Progress Notifications

NotifyProgress

Sends a progress notification to the client.

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

Connection Management

Close

Performs a graceful shutdown of the connection.

func (ss *ServerSession) Close() error

Wait

Waits for the connection to be closed by the client.

func (ss *ServerSession) Wait() error

Ping

Pings the client.

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

Session Information

ID

Returns the session ID.

func (ss *ServerSession) ID() string

InitializeParams

Returns the InitializeParams provided during client's connection.

func (ss *ServerSession) InitializeParams() *InitializeParams

Server Capabilities

ServerCapabilities

Describes capabilities that a server may support.

type ServerCapabilities struct {
    Completions  *CompletionCapabilities `json:"completions,omitempty"`
    Experimental map[string]any          `json:"experimental,omitempty"`
    Logging      *LoggingCapabilities    `json:"logging,omitempty"`
    Prompts      *PromptCapabilities     `json:"prompts,omitempty"`
    Resources    *ResourceCapabilities   `json:"resources,omitempty"`
    Tools        *ToolCapabilities       `json:"tools,omitempty"`
}

Fields:

  • Completions: Present if server supports argument autocompletion
  • Experimental: Non-standard capabilities
  • Logging: Present if server supports sending log messages
  • Prompts: Present if server offers prompt templates
  • Resources: Present if server offers resources to read
  • Tools: Present if server offers tools to call

ToolCapabilities

type ToolCapabilities struct {
    ListChanged bool `json:"listChanged,omitempty"`
}

PromptCapabilities

type PromptCapabilities struct {
    ListChanged bool `json:"listChanged,omitempty"`
}

ResourceCapabilities

type ResourceCapabilities struct {
    ListChanged bool `json:"listChanged,omitempty"`
    Subscribe   bool `json:"subscribe,omitempty"`
}

CompletionCapabilities

type CompletionCapabilities struct{}

LoggingCapabilities

type LoggingCapabilities struct{}

Logging Integration

LoggingHandler

An slog.Handler implementation that sends logs to MCP clients.

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

Example:

handler := mcp.NewLoggingHandler(session, &mcp.LoggingHandlerOptions{
    LoggerName:  "my-server",
    MinInterval: 100 * time.Millisecond,
})
logger := slog.New(handler)
logger.Info("Server started")

LoggingHandlerOptions

type LoggingHandlerOptions struct {
    LoggerName  string
    MinInterval time.Duration
}

Fields:

  • LoggerName: Value for the "logger" field of logging notifications
  • MinInterval: Limits the rate at which log messages are sent

Logging Levels

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
)

Session State

ServerSessionOptions

Configures the server session.

type ServerSessionOptions struct {
    State *ServerSessionState
}

ServerSessionState

Represents the state of a session.

type ServerSessionState struct {
    InitializeParams  *InitializeParams `json:"initializeParams"`
    InitializedParams *InitializedParams `json:"initializedParams"`
    LogLevel          LoggingLevel       `json:"logLevel"`
}

Fields:

  • InitializeParams: Parameters from 'initialize' request
  • InitializedParams: Parameters from 'notifications/initialized'
  • LogLevel: Current logging level for the session