Help us shape the future of Go! Take the 2026 Go Developer Survey

server

package
v0.24.1 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: Apache-2.0 Imports: 31 Imported by: 10

Documentation

Overview

Package handler provides a configurable MCP handler implementation.

It wires protocol handlers from the github.com/viant/mcp-protocol/handler package with optional middleware such as:

  • Transport (HTTP, HTTP-SSE, Streaming, STDIO)
  • OAuth2 / OIDC authorization
  • CORS handling
  • Structured logging

Callers typically construct a handler via `server.New` and then expose it over HTTP or stdio: 

s, _ := handler.New(handler.WithNewHandler(myImpl))
log.Fatal(s.HTTP(ctx, ":4981").ListenAndServe())

Index

Constants

View Source 
const (
	AllowOriginHeader       = "Access-Control-Allow-Origin"
	AllowHeadersHeader      = "Access-Control-Allow-Headers"
	AllowMethodsHeader      = "Access-Control-Allow-Methods"
	AllControlRequestHeader = "Access-Control-Request-Method"
	AllowCredentialsHeader  = "Access-Control-Allow-Credentials"
	ExposeHeadersHeader     = "Access-Control-Expose-Headers"
	MaxAgeHeader            = "Access-Control-Max-Age"
	Separator               = ", "
)

Variables

This section is empty.

Functions

func ChainMiddlewareHandlers added in v0.2.5 

func ChainMiddlewareHandlers(h http.Handler, mws ...Middleware) http.Handler

ChainMiddlewareHandlers chains multiple middleware handlers together

Types

type Adapter added in v0.2.5 

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

Adapter adapts a handler Handler to implement the client.Interface

func NewAdapter added in v0.2.5 

func NewAdapter(handler *Handler) *Adapter

NewAdapter creates a new adapter for the given handler

func (*Adapter) CallTool added in v0.2.5 

func (a *Adapter) CallTool(ctx context.Context, params *schema.CallToolRequestParams, options ...client.RequestOption) (*schema.CallToolResult, error)

CallTool calls a tool

func (*Adapter) Complete added in v0.2.5 

func (a *Adapter) Complete(ctx context.Context, params *schema.CompleteRequestParams, options ...client.RequestOption) (*schema.CompleteResult, error)

Complete completes a request

func (*Adapter) CreateMessage added in v0.2.10 

func (a *Adapter) CreateMessage(ctx context.Context, params *schema.CreateMessageRequestParams, options ...client.RequestOption) (*schema.CreateMessageResult, error)

CreateMessage proxies "sampling/createMessage" to the underlying handler.

func (*Adapter) Discover added in v0.18.0 

func (a *Adapter) Discover(ctx context.Context, options ...client.RequestOption) (*schema.DiscoverResult, error)

Discover exposes the July stateless discovery operation for in-process clients.

func (*Adapter) Elicit added in v0.2.10 

func (a *Adapter) Elicit(ctx context.Context, params *schema.ElicitRequestParams, options ...client.RequestOption) (*schema.ElicitResult, error)

Elicit proxies "elicitation/create" to the underlying handler.

func (*Adapter) GetPrompt added in v0.2.5 

func (a *Adapter) GetPrompt(ctx context.Context, params *schema.GetPromptRequestParams, options ...client.RequestOption) (*schema.GetPromptResult, error)

GetPrompt gets a prompt

func (*Adapter) GetSkill added in v0.24.1 

func (a *Adapter) GetSkill(ctx context.Context, uri string, options ...client.RequestOption) (*schema.GetSkillResult, error)

func (*Adapter) Initialize added in v0.2.5 

func (a *Adapter) Initialize(ctx context.Context, options ...client.RequestOption) (*schema.InitializeResult, error)

Initialize initializes the client

func (*Adapter) ListPrompts added in v0.2.5 

func (a *Adapter) ListPrompts(ctx context.Context, cursor *string, options ...client.RequestOption) (*schema.ListPromptsResult, error)

ListPrompts lists prompts

func (*Adapter) ListResourceTemplates added in v0.2.5 

func (a *Adapter) ListResourceTemplates(ctx context.Context, cursor *string, options ...client.RequestOption) (*schema.ListResourceTemplatesResult, error)

ListResourceTemplates lists resource templates

func (*Adapter) ListResources added in v0.2.5 

func (a *Adapter) ListResources(ctx context.Context, cursor *string, options ...client.RequestOption) (*schema.ListResourcesResult, error)

ListResources lists resources

func (*Adapter) ListRoots added in v0.2.10 

func (a *Adapter) ListRoots(ctx context.Context, params *schema.ListRootsRequestParams, options ...client.RequestOption) (*schema.ListRootsResult, error)

ListRoots proxies "roots/list" to the underlying handler.

func (*Adapter) ListSkills added in v0.24.1 

func (a *Adapter) ListSkills(ctx context.Context, cursor *string, options ...client.RequestOption) (*schema.ListSkillsResult, error)

Native skills use the same request sequencing and handler dispatch as other in-process standard methods. Authentication remains in the request context.

func (*Adapter) ListTools added in v0.2.5 

func (a *Adapter) ListTools(ctx context.Context, cursor *string, options ...client.RequestOption) (*schema.ListToolsResult, error)

ListTools lists tools

func (*Adapter) Ping added in v0.2.5 

func (a *Adapter) Ping(ctx context.Context, params *schema.PingRequestParams, options ...client.RequestOption) (*schema.PingResult, error)

Ping pings the handler

func (*Adapter) ReadResource added in v0.2.5 

func (a *Adapter) ReadResource(ctx context.Context, params *schema.ReadResourceRequestParams, options ...client.RequestOption) (*schema.ReadResourceResult, error)

ReadResource reads a resource

func (*Adapter) SetLevel added in v0.2.5 

func (a *Adapter) SetLevel(ctx context.Context, params *schema.SetLevelRequestParams, options ...client.RequestOption) (*schema.SetLevelResult, error)

SetLevel sets the logging level

func (*Adapter) Subscribe added in v0.2.5 

func (a *Adapter) Subscribe(ctx context.Context, params *schema.SubscribeRequestParams, options ...client.RequestOption) (*schema.SubscribeResult, error)

Subscribe subscribes to a resource

func (*Adapter) Unsubscribe added in v0.2.5 

func (a *Adapter) Unsubscribe(ctx context.Context, params *schema.UnsubscribeRequestParams, options ...client.RequestOption) (*schema.UnsubscribeResult, error)

Unsubscribe unsubscribes from a resource

type Client 

type Client struct {
	transport.Transport
	transport.Sequencer
	// contains filtered or unexported fields
}

Client implements mcp-protocol/client.Operations for the handler side. It allows handler implementers to invoke client-side RPC methods over the same transport channel on which the original request arrived.

func NewClient added in v0.2.11 

func NewClient(implements map[string]bool, aTransport transport.Transport) *Client

NewClient create a client

func (*Client) CreateMessage 

func (c *Client) CreateMessage(ctx context.Context, request *jsonrpc.TypedRequest[*schema.CreateMessageRequest]) (*schema.CreateMessageResult, *jsonrpc.Error)

CreateMessage creates a sampling message on the client side.

func (*Client) Elicit added in v0.2.10 

func (c *Client) Elicit(ctx context.Context, request *jsonrpc.TypedRequest[*schema.ElicitRequest]) (*schema.ElicitResult, *jsonrpc.Error)

Elicit asks the client to elicit additional information from the user.

func (*Client) Implements added in v0.2.11 

func (c *Client) Implements(method string) bool

func (*Client) Init added in v0.2.11 

func (c *Client) Init(ctx context.Context, capabilities *schema.ClientCapabilities)

func (*Client) ListRoots 

func (c *Client) ListRoots(ctx context.Context, request *jsonrpc.TypedRequest[*schema.ListRootsRequest]) (*schema.ListRootsResult, *jsonrpc.Error)

func (*Client) NextRequestId added in v0.4.2 

func (c *Client) NextRequestId() uint64

type Cors added in v0.2.5 

type Cors struct {
	AllowCredentials *bool    `yaml:"AllowCredentials,omitempty"`
	AllowHeaders     []string `yaml:"AllowHeaders,omitempty"`
	AllowMethods     []string `yaml:"AllowMethods,omitempty"`
	AllowOrigins     []string `yaml:"AllowOrigins,omitempty"`
	ExposeHeaders    []string `yaml:"ExposeHeaders,omitempty"`
	MaxAge           *int64   `yaml:"MaxAge,omitempty"`
}

func (*Cors) OriginMap added in v0.2.5 

func (c *Cors) OriginMap() map[string]bool

type Handler 

type Handler struct {
	transport.Notifier
	*Logger
	*Server

	Initialized bool
	// contains filtered or unexported fields
}

Handler represents handler

func (*Handler) CallTool 

func (h *Handler) CallTool(ctx context.Context, request *jsonrpc.Request) (*schema.CallToolResult, *jsonrpc.Error)

CallTool handles the tools/call method

func (*Handler) Cancel 

func (h *Handler) Cancel(ctx context.Context, notification *jsonrpc.Notification) *jsonrpc.Error

func (*Handler) CancelOperation added in v0.24.1 

func (h *Handler) CancelOperation(id int)

CancelOperation cancels only an operation received by this handler. A client cancellation notification cannot cancel another client's equal request ID.

func (*Handler) Close added in v0.24.1 

func (h *Handler) Close()

Close ends this handler's owning transport session once. HTTP uses its native final-session hook; in-process adapters may explicitly close their handler.

func (*Handler) Complete 

func (h *Handler) Complete(ctx context.Context, request *jsonrpc.Request) (*schema.CompleteResult, *jsonrpc.Error)

Complete handles the completion/complete method

func (*Handler) Discover added in v0.18.0 

func (h *Handler) Discover(ctx context.Context) (*schema.DiscoverResult, *jsonrpc.Error)

func (*Handler) GetPrompt 

func (h *Handler) GetPrompt(ctx context.Context, request *jsonrpc.Request) (*schema.GetPromptResult, *jsonrpc.Error)

GetPrompt handles the prompts/get method

func (*Handler) GetSkill added in v0.24.0 

func (h *Handler) GetSkill(ctx context.Context, request *jsonrpc.Request) (*schema.GetSkillResult, *jsonrpc.Error)

func (*Handler) Initialize 

func (h *Handler) Initialize(ctx context.Context, request *jsonrpc.Request) (*schema.InitializeResult, *jsonrpc.Error)

Initialize handles the legacy initialize method. July clients use Discover.

func (*Handler) ListPrompts 

func (h *Handler) ListPrompts(ctx context.Context, request *jsonrpc.Request) (*schema.ListPromptsResult, *jsonrpc.Error)

ListPrompts handles the prompts/list method

func (*Handler) ListResourceTemplates 

func (h *Handler) ListResourceTemplates(ctx context.Context, request *jsonrpc.Request) (*schema.ListResourceTemplatesResult, *jsonrpc.Error)

ListResourceTemplates handles the resources/templates/list method

func (*Handler) ListResources 

func (h *Handler) ListResources(ctx context.Context, request *jsonrpc.Request) (*schema.ListResourcesResult, *jsonrpc.Error)

ListResources handles the resources/list method

func (*Handler) ListSkills added in v0.24.0 

func (h *Handler) ListSkills(ctx context.Context, request *jsonrpc.Request) (*schema.ListSkillsResult, *jsonrpc.Error)

func (*Handler) ListTools 

func (h *Handler) ListTools(ctx context.Context, request *jsonrpc.Request) (*schema.ListToolsResult, *jsonrpc.Error)

ListTools handles the tools/list method

func (*Handler) Listen added in v0.18.0 

func (h *Handler) Listen(ctx context.Context, request *jsonrpc.Request) (*schema.SubscriptionsListenResult, *jsonrpc.Error)

Listen establishes the July notification stream, acknowledges the accepted filter first, and remains active until its request context is cancelled.

func (*Handler) OnNotification 

func (h *Handler) OnNotification(ctx context.Context, notification *jsonrpc.Notification)

OnNotification handles incoming JSON-RPC notifications

func (*Handler) Ping 

func (h *Handler) Ping(ctx context.Context, request *jsonrpc.Request) (*schema.PingResult, *jsonrpc.Error)

Ping handles the ping method

func (*Handler) ReadResource 

func (h *Handler) ReadResource(ctx context.Context, request *jsonrpc.Request) (*schema.ReadResourceResult, *jsonrpc.Error)

ReadResource handles the resources/read method

func (*Handler) Serve 

func (h *Handler) Serve(parent context.Context, request *jsonrpc.Request, response *jsonrpc.Response)

Serve handles incoming JSON-RPC requests

func (*Handler) SetLevel 

func (h *Handler) SetLevel(ctx context.Context, request *jsonrpc.Request) (*schema.SetLevelResult, *jsonrpc.Error)

SetLevel handles the logging/setLevel method

func (*Handler) Subscribe 

func (h *Handler) Subscribe(ctx context.Context, request *jsonrpc.Request) (*schema.SubscribeResult, *jsonrpc.Error)

Subscribe handles the resources/subscribe method

func (*Handler) Unsubscribe 

func (h *Handler) Unsubscribe(ctx context.Context, request *jsonrpc.Request) (*schema.UnsubscribeResult, *jsonrpc.Error)

Unsubscribe handles the resources/unsubscribe method

type Logger 

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

func NewLogger 

func NewLogger(name string, level *schema.LoggingLevel, notifier transport.Notifier) *Logger

func (*Logger) Alert 

func (l *Logger) Alert(ctx context.Context, data interface{}) error

func (*Logger) Critical 

func (l *Logger) Critical(ctx context.Context, data interface{}) error

func (*Logger) Debug 

func (l *Logger) Debug(ctx context.Context, data interface{}) error

func (*Logger) Emergency 

func (l *Logger) Emergency(ctx context.Context, data interface{}) error

func (*Logger) Error 

func (l *Logger) Error(ctx context.Context, data interface{}) error

func (*Logger) Info 

func (l *Logger) Info(ctx context.Context, data interface{}) error

func (*Logger) Logger 

func (l *Logger) Logger(name string) logger.Logger

Logger creates a new logger with a name

func (*Logger) Notice 

func (l *Logger) Notice(ctx context.Context, data interface{}) error

func (*Logger) Warning 

func (l *Logger) Warning(ctx context.Context, data interface{}) error

type Middleware added in v0.2.5 

type Middleware func(next http.Handler) http.Handler

Middleware is a function that takes an http.Handler and returns an http.Handler

type Option 

type Option func(s *Server) error

Option is a function that configures the handler.

func WithAuthorizer 

func WithAuthorizer(authorizer Middleware) Option

WithAuthorizer adds a new authorizer to the handler.

func WithBFFAuthStore added in v0.24.1 

func WithBFFAuthStore(store streamauth.Store) Option

WithBFFAuthStore binds an auth grant store to this HTTP listener. The same store must be passed to the listener's auth.Service via auth.Config.

func WithCORS added in v0.2.5 

func WithCORS(cors *Cors) Option

WithCORS adds a new CORS handler to the handler.

func WithCustomHTTPHandler added in v0.4.0 

func WithCustomHTTPHandler(path string, handler http.HandlerFunc) Option

WithCustomHTTPHandler adds a custom handler to the handler.

func WithEndpointAddress added in v0.2.10 

func WithEndpointAddress(addr string) Option

WithEndpointAddress sets the protocol version.

func WithImplementation 

func WithImplementation(implementation schema.Implementation) Option

WithImplementation sets the handler implementation.

func WithJRPCAuthorizer added in v0.2.5 

func WithJRPCAuthorizer(authorizer auth.JRPCAuthorizer) Option

WithJRPCAuthorizer adds a new JRPCAuthorizer to the handler.

func WithLoggerName 

func WithLoggerName(name string) Option

WithLoggerName sets the logger name.

func WithMaxRequestBodyBytes added in v0.24.1 

func WithMaxRequestBodyBytes(limit int64) Option

WithMaxRequestBodyBytes selects an explicit bounded HTTP request limit. The default remains 4 MiB. This never disables request-size enforcement.

func WithNewHandler added in v0.4.0 

func WithNewHandler(newHandler server.NewHandler) Option

WithNewHandler sets the new handler.

func WithOnSessionClose added in v0.24.1 

func WithOnSessionClose(closed func(transport.Notifier)) Option

WithOnSessionClose observes final transport-session removal. A temporary streaming disconnect remains resumable and does not close the session.

func WithProtectedResourcesHandler added in v0.2.5 

func WithProtectedResourcesHandler(handler http.HandlerFunc) Option

func WithProtocolVersion added in v0.2.10 

func WithProtocolVersion(version string) Option

WithProtocolVersion sets the protocol version for the handler.

func WithRequestContext added in v0.24.0 

func WithRequestContext(prepare func(context.Context) (context.Context, error)) Option

WithRequestContext prepares an invocation context before method lookup, authorization and dispatch. It applies to every transport, including stdio.

func WithRootRedirect added in v0.7.0 

func WithRootRedirect(enable bool) Option

WithRootRedirect enables redirect from "/" to the active transport base URI.

func WithSSEMessageURI added in v0.7.0 

func WithSSEMessageURI(uri string) Option

WithSSEMessageURI sets the message POST URI for SSE transport (default "/message").

func WithSSEURI added in v0.7.0 

func WithSSEURI(uri string) Option

WithSSEURI sets the base URI for the SSE endpoint (default "/sse").

func WithStreamableURI added in v0.7.0 

func WithStreamableURI(uri string) Option

WithStreamableURI sets the base URI for the streamable HTTP endpoint (default "/mcp").

func WithToolProtocolErrors added in v0.18.0 

func WithToolProtocolErrors() Option

WithToolProtocolErrors preserves JSON-RPC errors returned by tools/call. The default converts those errors into CallToolResult values for compatibility.

type ProtocolRequest added in v0.18.0 

type ProtocolRequest struct {
	Version      string
	Capabilities schema.ClientCapabilities
	ClientInfo   *schema.Implementation
	LogLevel     *schema.LoggingLevel
}

ProtocolRequest describes the immutable July metadata attached to one MCP request. It must not be retained or reused for a later request.

func ProtocolRequestFromContext added in v0.18.0 

func ProtocolRequestFromContext(ctx context.Context) (*ProtocolRequest, bool)

ProtocolRequestFromContext returns the current request's July metadata.

type Server 

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

Server represents MCP protocol handler

func New 

func New(options ...Option) (*Server, error)

New creates a new Server instance

func (*Server) AsClient added in v0.2.5 

func (s *Server) AsClient(ctx context.Context) client.Interface

AsClient returns a client.Interface implementation that uses this handler directly

func (*Server) CancelOperation added in v0.4.2 

func (s *Server) CancelOperation(id int)

func (*Server) HTTP 

func (s *Server) HTTP(_ context.Context, addr string) *http.Server

HTTP creates and returns an HTTP handler with OAuth2 authorizer and SSE handlers.

func (*Server) NewHandler 

func (s *Server) NewHandler(ctx context.Context, transport transport.Transport) transport.Handler

NewHandler creates a new handler instance

func (*Server) Stdio 

func (s *Server) Stdio(ctx context.Context) *stdio.Server

Stdio return stdio handler

func (*Server) UseStreamableHTTP added in v0.7.0 

func (s *Server) UseStreamableHTTP(flag bool)

UseStreamableHTTP sets whether to use streamableHTTP or SSE for the HTTP handler.

Source Files

View all Source files

Directories

Path Synopsis
Package auth exposes helpers that make it easy to protect an MCP server with OAuth2/OIDC.
 Package auth exposes helpers that make it easy to protect an MCP server with OAuth2/OIDC.
Package namespace provides a reusable, policy-aware namespace resolution utility for MCP servers and services.
 Package namespace provides a reusable, policy-aware namespace resolution utility for MCP servers and services.
Package oob provides minimal, generic primitives to manage out-of-band (OOB) interactions using typed pending entries bound to a namespace.
 Package oob provides minimal, generic primitives to manage out-of-band (OOB) interactions using typed pending entries bound to a namespace.

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.