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 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 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 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 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 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))