README
¶
client
MCP client implementation: HTTP transports, auth retry, reconnection, logging.
What belongs here
Clientstruct and options (NewClient,WithSSEClient,WithTransport, etc.)- HTTP transports: Streamable HTTP (
streamableClientTransport), SSE (sseClientTransport) - Auth retry (
DoWithAuthRetry) — 401 token refresh, 403 scope step-up - Reconnection (
WithMaxRetries,WithReconnectBackoff) - Transport logging (
WithClientLogging) - Server-to-client request handling (
HandleServerRequest,WithSamplingHandler,WithElicitationHandler) - Notification callback (
WithNotificationCallback)
Dependencies
core/— protocol types (Request, Response, ToolDef, etc.)- Does NOT import
server/
Usage
import (
"github.com/panyam/mcpkit/client"
"github.com/panyam/mcpkit/core"
)
c := client.NewClient("http://localhost:8787/mcp",
core.ClientInfo{Name: "my-client", Version: "1.0"},
client.WithSamplingHandler(mySamplingHandler),
)
c.Connect()
result, _ := c.ToolCall("greet", map[string]any{"name": "world"})
Transport interface
The client accepts any core.Transport via WithTransport(). This enables:
server.NewInProcessTransportfor testing (no HTTP)- Custom transports for stdio, WebSocket, etc.
Documentation
¶
Index ¶
- func DoWithAuthRetry(ts core.TokenSource, buildReq func() (*http.Request, error), ...) (*http.Response, error)
- func ExtractMethodFromJSON(data []byte) string
- func IsTransientError(err error) bool
- type CallResult
- type Client
- func (c *Client) Call(method string, params any) (*CallResult, error)
- func (c *Client) Close() error
- func (c *Client) Connect() error
- func (c *Client) HandleServerRequest(req *core.Request) *core.Response
- func (c *Client) ListResourceTemplates() ([]core.ResourceTemplate, error)
- func (c *Client) ListResources() ([]core.ResourceDef, error)
- func (c *Client) ListTools() ([]core.ToolDef, error)
- func (c *Client) ListToolsForModel() ([]core.ToolDef, error)
- func (c *Client) ReadResource(uri string) (string, error)
- func (c *Client) ServerSupportsExtension(id string) bool
- func (c *Client) ServerSupportsUI() bool
- func (c *Client) SessionID() string
- func (c *Client) SetTransport(t core.Transport)
- func (c *Client) SetURL(url string)
- func (c *Client) SubscribeResource(uri string) error
- func (c *Client) ToolCall(name string, args any) (string, error)
- func (c *Client) URL() string
- func (c *Client) UnsubscribeResource(uri string) error
- type ClientAuthError
- type ClientOption
- func WithClientBearerToken(token string) ClientOption
- func WithClientLogging(logger *log.Logger) ClientOption
- func WithElicitationHandler(h ElicitationHandler) ClientOption
- func WithExtension(id string, cap core.ClientExtensionCap) ClientOption
- func WithMaxRetries(n int) ClientOption
- func WithNotificationCallback(fn func(method string, params any)) ClientOption
- func WithReconnectBackoff(d time.Duration) ClientOption
- func WithSSEClient() ClientOption
- func WithSamplingHandler(h SamplingHandler) ClientOption
- func WithTokenSource(ts core.TokenSource) ClientOption
- func WithTransport(t core.Transport) ClientOption
- func WithUIExtension() ClientOption
- type ElicitationHandler
- type SamplingHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DoWithAuthRetry ¶
func DoWithAuthRetry( ts core.TokenSource, buildReq func() (*http.Request, error), do func(*http.Request) (*http.Response, error), ) (*http.Response, error)
DoWithAuthRetry executes an HTTP request with automatic retry on 401/403.
Retry budget: max 1 retry for 401 (token refresh), max 1 retry for 403 (scope step-up). Total max 2 retries per request.
On 401: calls core.TokenSource.Token() to get a fresh token, retries once. On 403: parses WWW-Authenticate for required scopes, calls core.ScopeAwareTokenSource.TokenForScopes if available, retries once.
buildReq must create a new *http.Request each call (body may be consumed). do is typically httpClient.Do.
func ExtractMethodFromJSON ¶
extractMethodFromJSON extracts the "method" field from a JSON-RPC envelope without full deserialization. Returns "<unknown>" if extraction fails.
func IsTransientError ¶
isTransientError returns true if the error indicates a recoverable transport failure that may succeed on reconnection. Network errors (EOF, connection reset, refused) are transient. Auth errors (401/403) and JSON-RPC errors are NOT transient — the server responded, just said no.
Types ¶
type CallResult ¶
type CallResult struct {
Raw any
}
CallResult holds the raw result from a JSON-RPC call.
func (*CallResult) JSON ¶
func (r *CallResult) JSON() string
JSON returns the result as indented JSON.
func (*CallResult) Unmarshal ¶
func (r *CallResult) Unmarshal(v any) error
Unmarshal decodes the result into the given value.
type Client ¶
type Client struct {
// ServerInfo is populated after Connect.
ServerInfo core.ServerInfo
// contains filtered or unexported fields
}
Client is an MCP client that communicates over Streamable HTTP or SSE.
func NewClient ¶
func NewClient(url string, info core.ClientInfo, opts ...ClientOption) *Client
NewClient creates a new MCP client targeting the given server URL. By default uses Streamable HTTP. Use WithSSEClient() for SSE transport. Call Connect() to perform the protocol handshake.
func (*Client) Call ¶
func (c *Client) Call(method string, params any) (*CallResult, error)
Call makes a JSON-RPC call and returns the parsed response.
func (*Client) Connect ¶
Connect establishes the transport and performs the MCP initialize handshake.
func (*Client) HandleServerRequest ¶
handleServerRequest dispatches an incoming server-to-client JSON-RPC request to the appropriate registered handler (sampling or elicitation). Returns a JSON-RPC response to send back to the server.
func (*Client) ListResourceTemplates ¶
func (c *Client) ListResourceTemplates() ([]core.ResourceTemplate, error)
ListResourceTemplates returns all registered resource templates.
func (*Client) ListResources ¶
func (c *Client) ListResources() ([]core.ResourceDef, error)
ListResources returns all registered static resources.
func (*Client) ListToolsForModel ¶
ListToolsForModel returns tools visible to the LLM, filtering out tools that are only visible to apps (visibility: ["app"]). Tools with no visibility set (nil/empty) are included — the default means visible to both model and app. This is a client-side convenience; the server always returns all tools.
func (*Client) ReadResource ¶
ReadResource reads a resource by URI and returns the first text content.
func (*Client) ServerSupportsExtension ¶
ServerSupportsExtension checks whether the server advertised support for the given extension ID in its initialize response. Call after Connect().
func (*Client) ServerSupportsUI ¶
ServerSupportsUI checks whether the server advertised MCP Apps (io.modelcontextprotocol/ui) support. Convenience wrapper around ServerSupportsExtension.
func (*Client) SetTransport ¶
SetTransport sets the transport for the client. Use when the transport needs to reference the client (e.g., InProcessTransport with ServerRequestHandler that delegates to the client's sampling/elicitation handlers). Must be called before Connect().
func (*Client) SetURL ¶
SetURL updates the client's target URL. Used in reconnection tests to simulate DNS/load balancer changes.
func (*Client) SubscribeResource ¶
SubscribeResource subscribes to change notifications for a resource URI. The server will send notifications/resources/updated when the resource changes.
func (*Client) UnsubscribeResource ¶
UnsubscribeResource removes a subscription for a resource URI.
type ClientAuthError ¶
type ClientAuthError struct {
// StatusCode is the HTTP status (401 or 403).
StatusCode int
// Message describes the failure.
Message string
// WWWAuthenticate is the raw WWW-Authenticate header from the server response.
WWWAuthenticate string
// RequiredScopes are the scopes parsed from the WWW-Authenticate header (403 only).
RequiredScopes []string
}
ClientAuthError is returned by the client transport when the server rejects a request with 401 or 403 and the transport has exhausted its retry budget.
func (*ClientAuthError) Error ¶
func (e *ClientAuthError) Error() string
type ClientOption ¶
type ClientOption func(*Client)
ClientOption configures a Client.
func WithClientBearerToken ¶
func WithClientBearerToken(token string) ClientOption
WithClientBearerToken sets a static bearer token for all client requests.
func WithClientLogging ¶
func WithClientLogging(logger *log.Logger) ClientOption
WithClientLogging enables debug logging of all client transport operations. Every connect, call, notify, and close is logged with method name, latency, and error details. Pass nil to use the default logger.
Example:
client := mcpkit.NewClient(url, info,
mcpkit.WithClientLogging(log.Default()),
)
func WithElicitationHandler ¶
func WithElicitationHandler(h ElicitationHandler) ClientOption
WithElicitationHandler registers a handler for server-to-client elicitation requests. When set, the client advertises the "elicitation" capability during initialization.
func WithExtension ¶
func WithExtension(id string, cap core.ClientExtensionCap) ClientOption
WithExtension advertises support for an extension during the initialize handshake. The extension ID and capability are included in the client's capabilities.extensions map, allowing the server to detect client support via core.ClientSupportsExtension(ctx, id) in tool handlers.
func WithMaxRetries ¶
func WithMaxRetries(n int) ClientOption
WithMaxRetries sets the maximum number of reconnection attempts on transient transport failure. Default 0 (reconnection disabled). Each retry includes a full reconnect + initialize handshake.
Example:
client := mcpkit.NewClient(url, info,
mcpkit.WithMaxRetries(3),
mcpkit.WithReconnectBackoff(time.Second),
)
func WithNotificationCallback ¶
func WithNotificationCallback(fn func(method string, params any)) ClientOption
WithNotificationCallback sets a callback for server-to-client notifications (logging, progress, resource updates). Works across all transports.
func WithReconnectBackoff ¶
func WithReconnectBackoff(d time.Duration) ClientOption
WithReconnectBackoff sets the base delay for exponential backoff between reconnection attempts. Default 1s. Actual delay is base * 2^attempt + jitter.
func WithSSEClient ¶
func WithSSEClient() ClientOption
WithSSEClient configures the client to use SSE transport instead of Streamable HTTP. The URL should point to the SSE endpoint (e.g., "http://localhost:8787/mcp/sse").
func WithSamplingHandler ¶
func WithSamplingHandler(h SamplingHandler) ClientOption
WithSamplingHandler registers a handler for server-to-client sampling requests. When set, the client advertises the "sampling" capability during initialization.
func WithTokenSource ¶
func WithTokenSource(ts core.TokenSource) ClientOption
WithTokenSource sets a dynamic token source for all client requests. Use this for OAuth flows where tokens are refreshed automatically.
func WithTransport ¶
func WithTransport(t core.Transport) ClientOption
WithTransport sets a core.Transport for the client, bypassing the default HTTP transport creation. Use with server.NewInProcessTransport for testing or embedded scenarios.
Example:
transport := server.NewInProcessTransport(srv)
c := client.New("memory://", info, client.WithTransport(transport))
func WithUIExtension ¶
func WithUIExtension() ClientOption
WithUIExtension is a convenience wrapper that advertises MCP Apps (io.modelcontextprotocol/ui) support with the standard app MIME type.
type ElicitationHandler ¶
type ElicitationHandler func(context.Context, core.ElicitationRequest) (core.ElicitationResult, error)
ElicitationHandler handles a server-to-client elicitation/create request. The client prompts the user for input and returns the result.
type SamplingHandler ¶
type SamplingHandler func(context.Context, core.CreateMessageRequest) (core.CreateMessageResult, error)
SamplingHandler handles a server-to-client sampling/createMessage request. The client performs LLM inference and returns the result.
Source Files