mcp::client::Client Class Reference

High-level MCP client compatibility API. More...

#include <client.hpp>

Classes
struct	StdioEndpoint
	Endpoint options for launching a child process over stdio. More...

Public Types
using	Root = protocol::Root
using	LoggingMessageHandler = std::function< void(std::string_view, std::string_view)>
	Receives logging messages from the server.
using	InitializedHandler = std::function< void()>
	Receives notifications that the peer completed initialization.
using	CancelledHandler = std::function< void(const protocol::RequestId &, std::string_view)>
	Receives cancellation notifications for in-flight requests.
using	ListChangedHandler = std::function< void()>
	Receives list-change notifications for prompts, resources, tools, or roots.
using	ResourceUpdatedHandler = std::function< void(const std::string &)>
	Receives resource update notifications.
using	ProgressHandler = std::function< void(const protocol::ProgressNotificationParams &)>
	Receives progress notifications associated with a progress token.
using	ElicitationCompleteHandler = std::function< void(std::string_view)>
	Receives completion notifications for elicitation flows.
using	TaskStatusHandler = std::function< void(const protocol::Task &)>
	Receives task status notifications.
using	RootsListRequestHandler = std::function< core::Result< protocol::RootsListResult >()>
	Handles a server request for the client's current roots.
using	RootsListRequestCancellationHandler = std::function< core::Result< protocol::RootsListResult >(CancellationToken)>
using	SamplingRequestHandler = std::function< core::Result< protocol::CreateMessageResult >(const protocol::CreateMessageParams &)>
	Handles a server sampling request.
using	SamplingRequestCancellationHandler = std::function< core::Result< protocol::CreateMessageResult >(const protocol::CreateMessageParams &, CancellationToken)>
using	ElicitationRequestHandler = std::function< core::Result< protocol::CreateElicitationResult >(const protocol::CreateElicitationRequestParam &)>
	Handles a server elicitation request.
using	ElicitationRequestCancellationHandler = std::function< core::Result< protocol::CreateElicitationResult >(const protocol::CreateElicitationRequestParam &, CancellationToken)>
using	CustomRequestHandler = std::function< core::Result< protocol::Json >(const protocol::JsonRpcRequest &)>
	Handles non-built-in server requests.
using	CustomRequestCancellationHandler = std::function< core::Result< protocol::Json >(const protocol::JsonRpcRequest &, CancellationToken)>
using	ListRootsRequestHandler = RootsListRequestHandler
using	CreateMessageRequestHandler = SamplingRequestHandler
using	CreateElicitationRequestHandler = ElicitationRequestHandler
using	RawNotificationHandler = std::function< void(const protocol::JsonRpcNotification &)>
	Observes every inbound notification after built-in dispatch.

Public Member Functions
	Client (std::unique_ptr< Transport > transport)
	Constructs a client from a custom transport.
	Client (const Client &)=delete
Client &	operator= (const Client &)=delete
	Client (Client &&other) noexcept
Client &	operator= (Client &&other) noexcept
core::Result< protocol::Json >	initialize (std::string client_name="cxxmcp", std::string client_version="0")
	Sends the MCP initialize request.
core::Result< protocol::Json >	initialize (std::string client_name, std::string client_version, RequestOptions options)
	Sends the MCP initialize request with per-request options.
std::optional< protocol::ServerCapabilities >	server_capabilities () const
	Returns server capabilities learned from initialize(), if known.
core::Result< core::Unit >	notify_initialized ()
	Sends the initialized notification after a successful initialize exchange.
core::Result< core::Unit >	notify_cancelled (protocol::RequestId request_id, std::string reason={})
	Sends a cancellation notification for a request.
core::Result< core::Unit >	notify_progress (protocol::ProgressToken progress_token, double progress, std::optional< double > total=std::nullopt, std::string message={})
	Sends a progress notification.
core::Result< core::Unit >	notify_roots_list_changed ()
	Notifies the server that the client's roots list changed.
core::Result< core::Unit >	ping ()
	Sends an MCP ping request.
core::Result< std::vector< protocol::Prompt > >	list_prompts ()
	Lists one page of prompts advertised by the server.
core::Result< protocol::PromptsListResult >	list_prompts_page (const protocol::PaginatedRequestParams &params={})
	Lists one typed page of prompts, preserving pagination metadata.
core::Result< std::vector< protocol::Prompt > >	list_all_prompts ()
	Lists all prompts, following pagination cursors until exhausted.
core::Result< protocol::PromptsGetResult >	get_prompt (const protocol::PromptsGetParams &params)
	Gets a prompt by protocol parameter object.
core::Result< protocol::PromptsGetResult >	get_prompt (std::string_view name, const protocol::Json &arguments=protocol::Json::object())
	Gets a prompt by name and optional JSON arguments.
core::Result< std::vector< protocol::Resource > >	list_resources ()
	Lists one page of resources advertised by the server.
core::Result< protocol::ResourcesListResult >	list_resources_page (const protocol::PaginatedRequestParams &params={})
	Lists one typed page of resources, preserving pagination metadata.
core::Result< std::vector< protocol::Resource > >	list_all_resources ()
	Lists all resources, following pagination cursors until exhausted.
core::Result< protocol::ResourcesReadResult >	read_resource (const protocol::ResourcesReadParams &params)
	Reads a resource by protocol parameter object.
core::Result< protocol::ResourcesReadResult >	read_resource (std::string_view uri)
	Reads a resource by URI.
core::Result< std::vector< protocol::ResourceTemplate > >	list_resource_templates ()
	Lists one page of resource templates advertised by the server.
core::Result< protocol::ResourceTemplatesListResult >	list_resource_templates_page (const protocol::PaginatedRequestParams &params={})
	Lists one typed page of resource templates.
core::Result< std::vector< protocol::ResourceTemplate > >	list_all_resource_templates ()
	Lists all resource templates, following pagination cursors until exhausted.
core::Result< std::vector< protocol::ToolDefinition > >	list_tools ()
	Lists one page of tool definitions advertised by the server.
core::Result< protocol::ToolsListResult >	list_tools_page (const protocol::PaginatedRequestParams &params={})
	Lists one typed page of tool definitions.
core::Result< std::vector< protocol::ToolDefinition > >	list_all_tools ()
	Lists all tool definitions, following pagination cursors until exhausted.
core::Result< protocol::ToolResult >	call_tool (const protocol::ToolCall &call)
	Calls a tool using a protocol ToolCall object.
core::Result< protocol::CreateTaskResult >	call_tool_task (const protocol::ToolCall &call)
	Calls a task-aware tool and returns the created task handle.
core::Result< protocol::ToolResult >	call_raw (std::string_view name, const protocol::Json &arguments=protocol::Json::object())
	Calls a tool by name with optional JSON arguments.
core::Result< protocol::CompleteResult >	complete (const protocol::CompleteParams &request)
	Requests completion using typed protocol parameters.
core::Result< protocol::Json >	complete (const protocol::Json &request)
	Requests completion using raw JSON parameters.
core::Result< protocol::CompletionResult >	complete_prompt_argument (std::string_view prompt_name, std::string_view argument_name, std::string current_value, protocol::Json context=protocol::Json::object())
	Completes a prompt argument using RMCP-style helper parameters.
core::Result< protocol::CompletionResult >	complete_resource_argument (std::string_view uri_template, std::string_view argument_name, std::string current_value, protocol::Json context=protocol::Json::object())
	Completes a resource template argument using RMCP-style helper parameters.
core::Result< std::vector< std::string > >	complete_prompt_simple (std::string_view prompt_name, std::string_view argument_name, std::string current_value, protocol::Json context=protocol::Json::object())
	Returns prompt completion values only.
core::Result< std::vector< std::string > >	complete_resource_simple (std::string_view uri_template, std::string_view argument_name, std::string current_value, protocol::Json context=protocol::Json::object())
	Returns resource completion values only.
core::Result< protocol::CreateMessageResult >	create_message (const protocol::CreateMessageParams &request)
	Sends a sampling createMessage request using typed protocol parameters.
core::Result< protocol::Json >	create_message (const protocol::Json &request)
	Sends a sampling createMessage request using raw JSON parameters.
core::Result< protocol::CreateElicitationResult >	create_elicitation (const protocol::CreateElicitationRequestParam &request)
	Sends an elicitation request using typed protocol parameters.
core::Result< protocol::Json >	create_elicitation (const protocol::Json &request)
	Sends an elicitation request using raw JSON parameters.
core::Result< std::vector< protocol::Task > >	list_tasks ()
	Lists one page of tasks advertised by the server.
core::Result< protocol::TaskListResult >	list_tasks_page (const protocol::TaskListParams &request={})
	Lists one typed task page, preserving pagination metadata.
core::Result< std::vector< protocol::Task > >	list_all_tasks ()
	Lists all tasks, following pagination cursors until exhausted.
core::Result< protocol::Task >	get_task (const protocol::TaskGetParams &request)
	Gets a task using typed protocol parameters.
core::Result< protocol::Task >	get_task (std::string_view task_id)
	Gets a task by task identifier.
core::Result< protocol::Task >	cancel_task (const protocol::TaskCancelParams &request)
	Cancels a task using typed protocol parameters.
core::Result< protocol::Task >	cancel_task (std::string_view task_id)
	Cancels a task by task identifier.
core::Result< protocol::Json >	task_result (const protocol::TaskResultParams &request)
	Gets a task result using typed protocol parameters.
core::Result< protocol::Json >	task_result (std::string_view task_id)
	Gets a task result by task identifier.
core::Result< core::Unit >	set_level (const protocol::LoggingSetLevelParams &params)
	Sets the server logging level using typed protocol parameters.
core::Result< core::Unit >	set_level (std::string_view level)
	Sets the server logging level by level name.
core::Result< core::Unit >	subscribe (std::string_view uri)
	Subscribes to resource update notifications for a URI.
core::Result< core::Unit >	unsubscribe (std::string_view uri)
	Unsubscribes from resource update notifications for a URI.
core::Result< protocol::Json >	request (const protocol::JsonRpcRequest &request)
	Sends a raw JSON-RPC request and returns its result JSON.
RequestHandle< protocol::Json >	request_async (std::string method, protocol::Json params=protocol::Json::object(), RequestOptions options={})
	Sends a cancellable raw request with an auto-generated id.
template<class T , class Parser >
RequestHandle< T >	request_async (std::string method, protocol::Json params, Parser parser, RequestOptions options={})
	Sends a cancellable typed request and parses its result payload.
RequestHandle< std::vector< protocol::ToolDefinition > >	list_tools_async (RequestOptions options={})
	Asynchronously lists tools and parses the typed response.
RequestHandle< std::vector< protocol::Prompt > >	list_prompts_async (RequestOptions options={})
	Asynchronously lists prompts and parses the typed response.
RequestHandle< std::vector< protocol::Resource > >	list_resources_async (RequestOptions options={})
	Asynchronously lists resources and parses the typed response.
RequestHandle< std::vector< protocol::ResourceTemplate > >	list_resource_templates_async (RequestOptions options={})
	Asynchronously lists resource templates and parses the typed response.
RequestHandle< protocol::ToolResult >	call_tool_async (const protocol::ToolCall &call, RequestOptions options={})
	Asynchronously calls a tool and parses the typed response.
RequestHandle< protocol::ToolResult >	call_tool_async (std::string_view name, const protocol::Json &arguments=protocol::Json::object(), RequestOptions options={})
	Asynchronously calls a tool by name.
RequestHandle< protocol::CreateTaskResult >	call_tool_task_async (const protocol::ToolCall &call, RequestOptions options={})
	Asynchronously starts a task-aware tool call.
RequestHandle< protocol::PromptsGetResult >	get_prompt_async (const protocol::PromptsGetParams &params, RequestOptions options={})
	Asynchronously gets a prompt and parses the typed response.
RequestHandle< protocol::PromptsGetResult >	get_prompt_async (std::string_view name, const protocol::Json &arguments=protocol::Json::object(), RequestOptions options={})
	Asynchronously gets a prompt by name.
RequestHandle< protocol::ResourcesReadResult >	read_resource_async (const protocol::ResourcesReadParams &params, RequestOptions options={})
	Asynchronously reads a resource and parses the typed response.
RequestHandle< protocol::ResourcesReadResult >	read_resource_async (std::string_view uri, RequestOptions options={})
	Asynchronously reads a resource by URI.
RequestHandle< protocol::CompleteResult >	complete_async (const protocol::CompleteParams &request, RequestOptions options={})
	Asynchronously completes a prompt/resource argument.
RequestHandle< protocol::Json >	complete_async (const protocol::Json &request, RequestOptions options={})
	Asynchronously sends a raw completion request.
RequestHandle< protocol::CreateMessageResult >	create_message_async (const protocol::CreateMessageParams &request, RequestOptions options={})
	Asynchronously creates a sampling message.
RequestHandle< protocol::Json >	create_message_async (const protocol::Json &request, RequestOptions options={})
	Asynchronously sends a raw sampling request.
RequestHandle< protocol::CreateElicitationResult >	create_elicitation_async (const protocol::CreateElicitationRequestParam &request, RequestOptions options={})
	Asynchronously creates an elicitation request.
RequestHandle< protocol::Json >	create_elicitation_async (const protocol::Json &request, RequestOptions options={})
	Asynchronously sends a raw elicitation request.
RequestHandle< std::vector< protocol::Task > >	list_tasks_async (RequestOptions options={})
	Asynchronously lists tasks and parses the typed response.
RequestHandle< protocol::Task >	get_task_async (const protocol::TaskGetParams &request, RequestOptions options={})
	Asynchronously gets a task using typed protocol parameters.
RequestHandle< protocol::Task >	get_task_async (std::string_view task_id, RequestOptions options={})
	Asynchronously gets a task by identifier.
RequestHandle< protocol::Task >	cancel_task_async (const protocol::TaskCancelParams &request, RequestOptions options={})
	Asynchronously cancels a task using typed protocol parameters.
RequestHandle< protocol::Task >	cancel_task_async (std::string_view task_id, RequestOptions options={})
	Asynchronously cancels a task by identifier.
RequestHandle< protocol::Json >	task_result_async (const protocol::TaskResultParams &request, RequestOptions options={})
	Asynchronously gets a task result using typed protocol parameters.
RequestHandle< protocol::Json >	task_result_async (std::string_view task_id, RequestOptions options={})
	Asynchronously gets a task result by identifier.
core::Result< core::Unit >	notify (const protocol::JsonRpcNotification &notification)
	Sends a raw JSON-RPC notification.
std::vector< protocol::Root >	list_roots () const
	Returns the roots currently advertised by this client.
Client &	set_roots (std::vector< protocol::Root > roots)
	Replaces the roots advertised by this client.
Client &	set_capabilities (protocol::ClientCapabilities capabilities)
	Sets client capabilities used during initialization.
Client &	on_initialized (InitializedHandler handler)
	Registers a callback for initialized notifications.
Client &	on_cancelled (CancelledHandler handler)
	Registers a callback for cancellation notifications.
Client &	on_logging_message (LoggingMessageHandler handler)
	Registers a callback for logging message notifications.
Client &	on_tool_list_changed (ListChangedHandler handler)
	Registers a callback for tool list change notifications.
Client &	on_prompt_list_changed (ListChangedHandler handler)
	Registers a callback for prompt list change notifications.
Client &	on_resource_list_changed (ListChangedHandler handler)
	Registers a callback for resource list change notifications.
Client &	on_resource_updated (ResourceUpdatedHandler handler)
	Registers a callback for resource update notifications.
Client &	on_progress (ProgressHandler handler)
	Registers a callback for progress notifications.
Client &	on_elicitation_complete (ElicitationCompleteHandler handler)
	Registers a callback for elicitation completion notifications.
Client &	on_task_status (TaskStatusHandler handler)
	Registers a callback for task status notifications.
Client &	on_roots_list_changed (ListChangedHandler handler)
	Registers a callback for roots list change notifications.
Client &	on_list_roots_request (ListRootsRequestHandler handler)
	Registers a handler for server list-roots requests.
Client &	on_list_roots_request (RootsListRequestCancellationHandler handler)
Client &	on_create_message_request (CreateMessageRequestHandler handler)
	Registers a handler for server sampling createMessage requests.
Client &	on_create_message_request (SamplingRequestCancellationHandler handler)
Client &	on_create_elicitation_request (CreateElicitationRequestHandler handler)
	Registers a handler for server elicitation requests.
Client &	on_create_elicitation_request (ElicitationRequestCancellationHandler handler)
Client &	on_custom_request (CustomRequestHandler handler)
	Registers a handler for custom server requests not handled by the built-in client dispatcher.
Client &	on_custom_request (CustomRequestCancellationHandler handler)
Client &	on_roots_list_request (RootsListRequestHandler handler)
	Compatibility alias for on_list_roots_request().
Client &	on_roots_list_request (RootsListRequestCancellationHandler handler)
Client &	on_sampling_request (SamplingRequestHandler handler)
	Compatibility alias for on_create_message_request().
Client &	on_sampling_request (SamplingRequestCancellationHandler handler)
Client &	on_elicitation_request (ElicitationRequestHandler handler)
	Compatibility alias for on_create_elicitation_request().
Client &	on_elicitation_request (ElicitationRequestCancellationHandler handler)
Client &	on_raw_notification (RawNotificationHandler handler)
	Registers an observer for raw inbound notifications.
Client &	on_custom_notification (RawNotificationHandler handler)
	Compatibility alias for on_raw_notification().
Client &	set_handler (const ClientHandler &handler)
	Installs every non-empty callback from a ClientHandler aggregate.
Client &	set_handler (const ClientHandlerInterface &handler)
	Installs callbacks from a ClientHandlerInterface contract.
core::Result< core::Unit >	start ()
	Starts the underlying transport receive side if the transport needs explicit startup.
core::Result< core::Unit >	handle_notification (const protocol::JsonRpcNotification &notification)
	Dispatches an inbound notification through built-in and registered handlers.
core::Result< protocol::JsonRpcResponse >	handle_request (const protocol::JsonRpcRequest &request)
	Dispatches an inbound server request through built-in and custom handlers.
core::Result< protocol::Json >	raw_request (const protocol::JsonRpcRequest &request)
	Sends a raw JSON-RPC request and returns the raw result JSON.
core::Result< core::Unit >	raw_notification (const protocol::JsonRpcNotification &notification)
	Sends a raw JSON-RPC notification.
void	stop () noexcept
	Stops the underlying transport and clears receive-side state.
	~Client ()
	Waits for in-flight async requests to complete, then destroys the client.

Static Public Member Functions
static Client	connect_stdio (StdioEndpoint endpoint)
	Creates a client connected to a child process over stdio.

Detailed Description

High-level MCP client compatibility API.

Client owns a Transport and exposes MCP operations such as initialize, discovery, tool invocation, prompt/resource access, roots, logging, sampling, elicitation, and task helpers. Methods return core::Result<T>; protocol and transport failures are reported through that result rather than by changing global state. New applications should prefer ClientPeer and Service as their entry points; Client remains a stable embeddable layer and compatibility surface.

Member Typedef Documentation

CancelledHandler

using mcp::client::Client::CancelledHandler = std::function<void(const protocol::RequestId&, std::string_view)>

Receives cancellation notifications for in-flight requests.

Parameters

request_id	Identifier of the cancelled request.
reason	Optional cancellation reason.

CustomRequestHandler

using mcp::client::Client::CustomRequestHandler = std::function<core::Result<protocol::Json>( const protocol::JsonRpcRequest&)>

Handles non-built-in server requests.

Parameters

request

Raw JSON-RPC request from the server.

Returns

JSON value used as the response result, or an MCP error result.

ElicitationCompleteHandler

using mcp::client::Client::ElicitationCompleteHandler = std::function<void(std::string_view)>

Receives completion notifications for elicitation flows.

Parameters

elicitation_id

Identifier of the completed elicitation request.

ElicitationRequestHandler

using mcp::client::Client::ElicitationRequestHandler = std::function<core::Result<protocol::CreateElicitationResult>( const protocol::CreateElicitationRequestParam&)>

Handles a server elicitation request.

Parameters

params

Elicitation request parameters supplied by the server.

Returns

Elicitation result, or an MCP error result.

LoggingMessageHandler

using mcp::client::Client::LoggingMessageHandler = std::function<void(std::string_view, std::string_view)>

Receives logging messages from the server.

Parameters

level	Server-provided logging level.
message	Human-readable log message.

ResourceUpdatedHandler

using mcp::client::Client::ResourceUpdatedHandler = std::function<void(const std::string&)>

Receives resource update notifications.

Parameters

uri	URI of the updated resource.

RootsListRequestHandler

using mcp::client::Client::RootsListRequestHandler = std::function<core::Result<protocol::RootsListResult>()>

Handles a server request for the client's current roots.

Returns

Roots list result, or an MCP error result.

SamplingRequestHandler

using mcp::client::Client::SamplingRequestHandler = std::function<core::Result<protocol::CreateMessageResult>( const protocol::CreateMessageParams&)>

Handles a server sampling request.

Parameters

params

Sampling parameters supplied by the server.

Returns

Created message, or an MCP error result.

Constructor & Destructor Documentation

Client()

mcp::client::Client::Client ( std::unique_ptr< Transport >  transport )

explicit

Constructs a client from a custom transport.

Parameters

transport

Transport instance to own. It must not be null.

Member Function Documentation

connect_stdio()

static Client mcp::client::Client::connect_stdio ( StdioEndpoint  endpoint )

static

Creates a client connected to a child process over stdio.

Parameters

endpoint

Child process command, arguments, working directory, and environment.

Returns

Client owning a process stdio transport.

initialize() [1/2]

core::Result< protocol::Json > mcp::client::Client::initialize	(	std::string	client_name,
		std::string	client_version,
		RequestOptions	options
	)

Sends the MCP initialize request with per-request options.

Parameters

client_name	Name advertised to the server.
client_version	Version advertised to the server.
options	Per-request options (meta, headers, protocol_version).

Returns

Raw initialize result JSON, or an MCP/transport error.

initialize() [2/2]

core::Result< protocol::Json > mcp::client::Client::initialize	(	std::string	client_name = "cxxmcp",
		std::string	client_version = "0"
	)

Sends the MCP initialize request.

Parameters

client_name	Name advertised to the server.
client_version	Version advertised to the server.

Returns

Raw initialize result JSON, or an MCP/transport error.

notify_cancelled()

core::Result< core::Unit > mcp::client::Client::notify_cancelled	(	protocol::RequestId	request_id,
		std::string	reason = {}
	)

Sends a cancellation notification for a request.

Parameters

request_id	Identifier of the request being cancelled.
reason	Optional cancellation reason.

notify_progress()

core::Result< core::Unit > mcp::client::Client::notify_progress	(	protocol::ProgressToken	progress_token,
		double	progress,
		std::optional< double >	total = std::nullopt,
		std::string	message = {}
	)

Sends a progress notification.

Parameters

progress_token	Token that associates progress with a request.
progress	Current progress value.
total	Optional total value for determinate progress.
message	Optional human-readable status message.

request_async()

template<class T , class Parser >

RequestHandle< T > mcp::client::Client::request_async ( std::string  method, protocol::Json  params, Parser  parser, RequestOptions  options = {}  )

inline

Sends a cancellable typed request and parses its result payload.

Template Parameters

T	Parsed result type.
Parser	Callable returning core::Result<T> from a JSON result.

set_capabilities()

Client & mcp::client::Client::set_capabilities

(

protocol::ClientCapabilities

capabilities

)

Sets client capabilities used during initialization.

Parameters

capabilities

Capabilities to advertise to the server.

Returns

Reference to this client for chaining.

set_handler() [1/2]

Client & mcp::client::Client::set_handler ( const ClientHandler &  handler )

inline

Installs every non-empty callback from a ClientHandler aggregate.

Installs all non-empty callbacks from a ClientHandler.

Parameters

handler

Callback aggregate. Empty members leave existing callbacks unchanged.

Returns

Reference to this client for chaining.

Reference to this client for chaining.

set_handler() [2/2]

Client & mcp::client::Client::set_handler ( const ClientHandlerInterface &  handler )

inline

Installs callbacks from a ClientHandlerInterface contract.

Installs callbacks from a contract-style client handler.

Parameters

handler

Handler contract. Unimplemented request methods fall back to method-not-found errors and notification methods default to no-op.

set_roots()

Client & mcp::client::Client::set_roots

(

std::vector< protocol::Root >

roots

)

Replaces the roots advertised by this client.

Parameters

roots

New roots collection.

Returns

Reference to this client for chaining.

Note

If a roots-list-changed callback is installed, it is invoked after updating.

---

The documentation for this class was generated from the following files:

• sdk/client/include/cxxmcp/client/client.hpp
• sdk/client/include/cxxmcp/client/handler.hpp