client

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 WithClientBearerToken ¶

func WithClientBearerToken(token string) ClientOption

WithClientBearerToken sets a static bearer token for all client requests.

func WithClientKeepalive ¶ added in v0.1.11

func WithClientKeepalive(interval time.Duration, maxFailures int) ClientOption

WithClientKeepalive enables application-level keepalive pings. The client periodically sends JSON-RPC ping requests to the server. If maxFailures consecutive pings fail (timeout or error), the client triggers reconnection (if retries are configured) or closes.

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 WithClientMiddleware ¶ added in v0.2.29

func WithClientMiddleware(mw ...ClientMiddleware) ClientOption

WithClientMiddleware registers middleware that wraps all outgoing client calls (ToolCall, ListTools, ReadResource, etc.). Middleware executes in registration order: first registered = outermost (runs first on request, last on response).

func WithCommandTransport ¶ added in v0.1.14

func WithCommandTransport(name string, args []string, opts ...CommandOption) ClientOption

WithCommandTransport configures the client to spawn a subprocess MCP server and communicate over stdin/stdout. A fresh process is started on each Connect() (and on each reconnection if WithMaxRetries is set).

Example:

c := client.NewClient("", info,
    client.WithCommandTransport("python", []string{"my_server.py"},
        client.WithEnv("DEBUG=1"),
    ),
)
err := c.Connect()

func WithConnectTimeout ¶ added in v0.1.16

func WithConnectTimeout(d time.Duration) ClientOption

WithConnectTimeout sets a deadline for Connect() to complete. This covers both the transport connection (subprocess start, SSE stream open) and the MCP initialize handshake. If the timeout expires, Connect() returns an error immediately instead of blocking indefinitely.

This is especially important for CommandTransport: if the subprocess starts but doesn't speak Content-Length framed JSON-RPC (e.g., wrong mode, missing env vars), Connect() would block forever without a timeout.

Default is 0 (no timeout).

func WithContentChunkHandler ¶ added in v0.1.17

func WithContentChunkHandler(fn func(chunk core.ContentChunk)) ClientOption

WithContentChunkHandler sets a callback for streaming tool content chunks. The callback is invoked for each content chunk notification received during tool execution (method matching the server's configured content chunk method, default "notifications/tools/content_chunk").

If not set, content chunk notifications are silently ignored and the client relies on the final ToolResult for the complete response.

func WithElicitationCompleteHandler ¶ added in v0.2.41

func WithElicitationCompleteHandler(h ElicitationCompleteHandler) ClientOption

WithElicitationCompleteHandler registers a handler for notifications/elicitation/complete notifications (SEP-1036).

func WithElicitationHandler ¶

func WithElicitationHandler(h ElicitationHandler) ClientOption

WithElicitationHandler registers a handler for server-to-client elicitation requests. When set, the client advertises form-mode elicitation capability during initialization. To also support URL-mode elicitation, combine with WithElicitationURLSupport.

func WithElicitationURLSupport ¶ added in v0.2.41

func WithElicitationURLSupport() ClientOption

WithElicitationURLSupport enables URL-mode elicitation capability. The same ElicitationHandler receives both form and URL mode requests; it should branch on req.Mode. Must be combined with WithElicitationHandler.

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 WithGetSSEStream ¶

func WithGetSSEStream() ClientOption

WithGetSSEStream enables a background GET SSE stream on the Streamable HTTP endpoint after Connect(). The stream receives server-initiated notifications (list-changed, log messages, resource updates) that arrive outside POST request-response cycles. Only applies to Streamable HTTP transport; ignored for SSE and in-memory transports.

The notification callback (set via WithNotificationCallback) must be goroutine-safe when WithGetSSEStream is enabled, as notifications may arrive concurrently from both the GET SSE stream and POST SSE responses.

func WithIOTransport ¶ added in v0.2.27

func WithIOTransport(r io.Reader, w io.Writer) ClientOption

WithIOTransport configures a Client to use Content-Length framed JSON-RPC over arbitrary reader/writer streams. This is the generic IO transport — use it for Unix sockets, named pipes, SSH tunnels, test pipe pairs, or any other stream-based transport.

Example (pipe pair for testing):

sr, cw := io.Pipe()
cr, sw := io.Pipe()
go srv.RunIO(ctx, sr, sw)
c := client.NewClient("", info, client.WithIOTransport(cr, cw))

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 WithModifyRequest ¶ added in v0.1.14

func WithModifyRequest(fn func(*http.Request)) ClientOption

WithModifyRequest sets a callback that is invoked on every outgoing HTTP request before authentication headers are applied. Use it to add custom headers (API keys, tracing IDs, tenant identifiers) without needing a custom http.RoundTripper.

The callback must not modify the request body or URL. Only applies to HTTP transports (Streamable HTTP, SSE); ignored for stdio and in-process transports.

Example:

c := client.NewClient(url, info,
    client.WithModifyRequest(func(req *http.Request) {
        req.Header.Set("X-Tenant-ID", "acme")
        req.Header.Set("X-Request-ID", uuid.New().String())
    }),
)

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 WithRootsHandler ¶ added in v0.1.24

func WithRootsHandler(h RootsHandler) ClientOption

WithRootsHandler registers a handler for server-to-client roots/list requests. When set, the client advertises the "roots" capability (with listChanged: true) during initialization, enabling the server to fetch the client's filesystem roots after receiving a notifications/roots/list_changed notification.

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 WithStdioTransport ¶

func WithStdioTransport(r io.Reader, w io.Writer) ClientOption

WithStdioTransport configures a Client to use stdio transport. This is equivalent to WithIOTransport with the given reader/writer pair — kept for backward compatibility and naming clarity when used with subprocess servers (where r is stdout and w is stdin of the child process).

func WithTasksExtension ¶ added in v0.2.41

func WithTasksExtension() ClientOption

WithTasksExtension advertises SEP-2663 Tasks support (io.modelcontextprotocol/tasks). v2 servers gate task creation and the tasks/* methods on this declaration — clients that omit it see synchronous tools/call responses and -32601 for tasks/get / tasks/cancel / tasks/update.

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.

func WithDir ¶ added in v0.1.14

func WithDir(dir string) CommandOption

WithDir sets the working directory for the subprocess.

func WithEnv ¶ added in v0.1.14

func WithEnv(env ...string) CommandOption

WithEnv adds environment variables to the subprocess. Each value should be in KEY=VALUE format. These are appended to the current process environment.

func WithShutdownTimeout ¶ added in v0.1.14

func WithShutdownTimeout(d time.Duration) CommandOption

WithShutdownTimeout sets the duration to wait after sending SIGTERM before escalating to SIGKILL. Default is 5 seconds.

func WithStderr ¶ added in v0.1.14

func WithStderr(w io.Writer) CommandOption

WithStderr sets an additional writer for subprocess stderr output. Stderr is always captured in an internal buffer (for error messages on crash); this option tees it to an additional destination (e.g., os.Stderr, a logger).

func NewCommandTransport ¶ added in v0.1.14

func NewCommandTransport(name string, args []string, opts ...CommandOption) *CommandTransport

NewCommandTransport creates a CommandTransport that will spawn the given command with args when Connect() is called.

func DefaultInputHandler ¶ added in v0.2.41

func DefaultInputHandler(c *Client) InputHandler

DefaultInputHandler returns an InputHandler that resolves the standard MRTR inputRequest methods using the client's existing capability handlers:

• "elicitation/create" → samplingElicit via elicitationHandler
• "sampling/createMessage" → samplingHandler
• "roots/list" → rootsHandler

Unknown methods produce an error. Returns an error from the underlying handler too — CallToolWithInputs propagates it and aborts the loop.

This is a starting point. Wrap or replace it for custom inputRequest methods, alternative routing, or to inject non-default response payloads (e.g., declining elicitation requests, returning canned sampling output in tests).

func WithMaxMRTRRounds ¶ added in v0.2.41

func WithMaxMRTRRounds(n int) MRTROption

WithMaxMRTRRounds caps how many times CallToolWithInputs will retry a tools/call when the server keeps returning IncompleteResult. Default is 16 (enough for any sane workflow; high enough that hitting it suggests a bug). Zero or negative values fall back to the default.

func NewStdioTransport ¶

func NewStdioTransport(r io.Reader, w io.Writer) *StdioTransport

NewStdioTransport creates a client transport that communicates via Content-Length framed JSON-RPC over the given reader/writer pair.

Typically the reader is connected to the server's stdout and the writer to the server's stdin (or pipe ends in tests).

Example:

cmd := exec.Command("my-mcp-server")
stdin, _ := cmd.StdinPipe()
stdout, _ := cmd.StdoutPipe()
cmd.Start()
transport := client.NewStdioTransport(stdout, stdin)
c := client.NewClient("stdio://", info, client.WithTransport(transport))

func CallToolWithInputs ¶ added in v0.2.41

func CallToolWithInputs(ctx context.Context, c *Client, name string, args any, handler InputHandler, opts ...MRTROption) (*ToolCallResult, error)

CallToolWithInputs invokes a tool with automatic SEP-2322 MRTR retry. On IncompleteResult, the handler is called to resolve the inputRequests; the call is then retried with inputResponses + the echoed requestState. The loop terminates as soon as the server returns a complete ToolResult, a CreateTaskResult, or an error. Returns ErrMRTRMaxRounds if the round cap (default 16) is hit.

Pass DefaultInputHandler(c) to handle the standard inputRequest methods using the client's existing capability handlers.

func ToolCall ¶ added in v0.2.41

func ToolCall(c *Client, name string, args any) (*ToolCallResult, error)

ToolCall invokes a tool, transparently handling both the sync ToolResult and the SEP-2663 CreateTaskResult shapes. Branch on result.IsTask() (or the Sync / Task fields directly) to know which arrived.

Servers gate task creation on the io.modelcontextprotocol/tasks extension, so this only ever returns a Task result if the client declared the extension during initialize (or per-request via SEP-2575 _meta).