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

#include <server.hpp>

Public Types
using	JsonHandler = std::function< core::Result< protocol::Json >(const protocol::Json &)>
	Handles JSON-shaped extension requests such as completion or sampling.

using	JsonContextHandler = std::function< core::Result< protocol::Json >(const protocol::Json &, const SessionContext &)>

using	JsonRequestContextHandler = std::function< core::Result< protocol::Json >(const protocol::Json &, const SessionContext &, CancellationToken)>

using	LoggingHandler = std::function< void(std::string_view, std::string_view)>
	Handles logging messages from clients.

using	RawRequestHandler = std::function< std::optional< protocol::JsonRpcResponse >(const protocol::JsonRpcRequest &, const SessionContext &)>
	Optionally handles raw or custom requests before built-in fallback.

using	RawRequestContextHandler = std::function< std::optional< protocol::JsonRpcResponse >(const protocol::JsonRpcRequest &, const SessionContext &, CancellationToken)>

using	RawNotificationHandler = std::function< core::Result< core::Unit >(const protocol::JsonRpcNotification &, const SessionContext &)>
	Handles raw or custom notifications.

using	TaskListHandler = std::function< core::Result< protocol::TaskListResult >(const protocol::TaskListParams &, const SessionContext &)>
	Handles task list requests.

using	ToolsListHandler = std::function< core::Result< protocol::ToolsListResult >(const protocol::PaginatedRequestParams &, const SessionContext &)>
	Handles tools/list requests.

using	PromptsListHandler = std::function< core::Result< protocol::PromptsListResult >(const protocol::PaginatedRequestParams &, const SessionContext &)>
	Handles prompts/list requests.

using	ResourcesListHandler = std::function< core::Result< protocol::ResourcesListResult >(const protocol::PaginatedRequestParams &, const SessionContext &)>
	Handles resources/list requests.

using	ResourceTemplatesListHandler = std::function< core::Result< protocol::ResourceTemplatesListResult >(const protocol::PaginatedRequestParams &, const SessionContext &)>
	Handles resources/templates/list requests.

using	TaskGetHandler = std::function< core::Result< protocol::Task >(const protocol::TaskGetParams &, const SessionContext &)>
	Handles task get requests.

using	TaskCancelHandler = std::function< core::Result< protocol::Task >(const protocol::TaskCancelParams &, const SessionContext &)>
	Handles task cancel requests.

using	TaskResultHandler = std::function< core::Result< protocol::Json >(const protocol::TaskResultParams &, const SessionContext &)>
	Handles task result requests.

using	RootsListChangedHandler = std::function< core::Result< core::Unit >(const SessionContext &)>
	Handles client roots-list-changed notifications.

using	ProgressHandler = std::function< core::Result< core::Unit >(const protocol::ProgressNotificationParams &, const SessionContext &)>
	Handles client progress notifications.

using	ListChangedHandler = std::function< core::Result< core::Unit >(const SessionContext &)>
	Handles client list-changed notifications.

using	ResourceUpdatedHandler = std::function< core::Result< core::Unit >(const std::string &uri, const SessionContext &)>
	Handles client resource-updated notifications.

Public Member Functions
	Server (ServerOptions options)
	Constructs a server from explicit options.

	~Server ()
	Stops transports and task workers before owned registries vanish.

	Server (const Server &)=delete

Server &	operator= (const Server &)=delete

	Server (Server &&) noexcept

Server &	operator= (Server &&) noexcept

ServerInfo	get_info () const
	Returns server metadata advertised during initialization.

const protocol::ServerCapabilities &	capabilities () const noexcept
	Returns the capabilities advertised to clients.

ToolRegistry &	tools () noexcept
	Returns the mutable tool registry.

const ToolRegistry &	tools () const noexcept
	Returns the tool registry.

std::vector< protocol::ToolDefinition >	list_tools () const
	Lists registered tool definitions.

core::Result< protocol::ToolsListResult >	list_tools (const protocol::PaginatedRequestParams &params, const SessionContext &context) const
	Handles a paginated tools/list request.

core::Result< protocol::ToolDefinition >	get_tool (std::string_view name) const
	Gets a registered tool definition by name.

core::Result< protocol::ToolResult >	call_tool (std::string_view name, protocol::Json arguments=protocol::Json::object(), const std::string &session_id={}) const
	Invokes a registered tool.

core::Result< protocol::ToolResult >	call_tool (std::string_view name, protocol::Json arguments, const SessionContext &context, CancellationToken cancellation=CancellationToken::none()) const

Server &	use_task_manager (TaskOperationProcessorOptions options={})
	Enables the built-in SDK task processor.

Server &	use_task_manager (std::shared_ptr< TaskOperationProcessor > processor)
	Installs a caller-owned task processor shared with this server.

std::shared_ptr< TaskOperationProcessor >	task_manager () const noexcept
	Returns the installed task processor, if any.

PromptRegistry &	prompts () noexcept
	Returns the mutable prompt registry.

const PromptRegistry &	prompts () const noexcept
	Returns the prompt registry.

std::vector< protocol::Prompt >	list_prompts () const
	Lists registered prompts.

core::Result< protocol::PromptsListResult >	list_prompts (const protocol::PaginatedRequestParams &params, const SessionContext &context) const
	Handles a paginated prompts/list request.

core::Result< protocol::PromptsGetResult >	get_prompt (std::string_view name, protocol::Json arguments=protocol::Json::object(), const std::string &session_id={}) const
	Gets a registered prompt result.

core::Result< protocol::PromptsGetResult >	get_prompt (std::string_view name, protocol::Json arguments, const SessionContext &context, CancellationToken cancellation=CancellationToken::none()) const

ResourceRegistry &	resources () noexcept
	Returns the mutable resource registry.

const ResourceRegistry &	resources () const noexcept
	Returns the resource registry.

std::vector< protocol::Resource >	list_resources () const
	Lists registered resources.

core::Result< protocol::ResourcesListResult >	list_resources (const protocol::PaginatedRequestParams &params, const SessionContext &context) const
	Handles a paginated resources/list request.

core::Result< protocol::ResourcesReadResult >	read_resource (std::string_view uri, protocol::Json params=protocol::Json::object(), const std::string &session_id={}) const
	Reads a registered resource.

core::Result< protocol::ResourcesReadResult >	read_resource (std::string_view uri, protocol::Json params, const SessionContext &context, CancellationToken cancellation=CancellationToken::none()) const

ResourceTemplateRegistry &	resource_templates () noexcept
	Returns the mutable resource-template registry.

const ResourceTemplateRegistry &	resource_templates () const noexcept
	Returns the resource-template registry.

std::vector< protocol::ResourceTemplate >	list_resource_templates () const
	Lists registered resource templates.

core::Result< protocol::ResourceTemplatesListResult >	list_resource_templates (const protocol::PaginatedRequestParams &params, const SessionContext &context) const
	Handles a paginated resources/templates/list request.

core::Result< protocol::Json >	initialize ()
	Builds the JSON result for an initialize request.

core::Result< protocol::Json >	ping (const SessionContext &context={})
	Handles a ping request.

core::Result< protocol::JsonRpcResponse >	handle_request (const protocol::JsonRpcRequest &request, const SessionContext &context)
	Dispatches an inbound JSON-RPC request from a transport.

core::Result< SessionContext >	authenticate_context (const SessionContext &context)
	Applies the configured AuthProvider to a session context.

core::Result< core::Unit >	handle_notification (const protocol::JsonRpcNotification &notification, const SessionContext &context)
	Dispatches an inbound JSON-RPC notification from a transport.

core::Result< core::Unit >	notify_roots_list_changed ()
	Notifies connected clients that roots changed.

core::Result< core::Unit >	notify_tool_list_changed ()
	Notifies connected clients that the tool list changed.

core::Result< core::Unit >	notify_prompt_list_changed ()
	Notifies connected clients that the prompt list changed.

core::Result< core::Unit >	notify_resource_list_changed ()
	Notifies connected clients that the resource list changed.

core::Result< core::Unit >	notify_resource_updated (std::string_view uri)
	Notifies subscribed clients that a resource URI was updated.

core::Result< core::Unit >	set_resource_subscription (const SessionContext &context, std::string_view uri, bool subscribed)
	Updates resource subscription routing for a transport session.

core::Result< core::Unit >	notify_progress (const protocol::ProgressNotificationParams &params)
	Sends a progress notification to connected clients.

core::Result< core::Unit >	notify_logging_message (const protocol::LoggingMessageNotificationParams &params)
	Sends a logging message notification to connected clients.

core::Result< core::Unit >	notify_elicitation_complete (std::string elicitation_id)
	Sends an elicitation-complete notification.

core::Result< core::Unit >	notify_task_status (const protocol::Task &task)
	Sends a task status notification.

core::Result< protocol::CreateTaskResult >	enqueue_task (const protocol::Task &task)
	Sends a server-to-client request to create a new task.

core::Result< core::Unit >	add_transport (std::unique_ptr< Transport > transport)
	Adds a transport owned by the server.

core::Result< core::Unit >	add_session_transport (Transport &transport)
	Registers a borrowed session transport for outbound server events.

void	set_auth_provider (std::unique_ptr< AuthProvider > auth_provider)
	Installs an authentication provider used by supported transports.

void	set_rate_limiter (std::unique_ptr< RateLimiter > rate_limiter)
	Installs a rate limiter used by supported transports.

void	set_schema_validator (std::shared_ptr< const JsonSchemaValidator > validator)
	Installs an optional JSON Schema validator.

std::shared_ptr< const JsonSchemaValidator >	schema_validator () const noexcept
	Returns the configured JSON Schema validator, if any.

core::Result< core::Unit >	start ()
	Starts every registered transport.

void	stop () noexcept
	Stops all transports.

void	set_completion_handler (JsonHandler handler)
	Registers the completion request handler.

void	set_completion_handler (JsonContextHandler handler)

void	set_completion_handler (JsonRequestContextHandler handler)

void	set_sampling_handler (JsonHandler handler)
	Registers the sampling request handler.

void	set_sampling_handler (JsonContextHandler handler)

void	set_sampling_handler (JsonRequestContextHandler handler)

void	set_logging_handler (LoggingHandler handler)
	Registers the logging notification handler.

void	set_raw_request_handler (RawRequestHandler handler)
	Registers a raw request hook.

void	set_raw_request_handler (RawRequestContextHandler handler)

const RawRequestHandler &	raw_request_handler () const noexcept
	Returns the registered raw request handler, if any.

const RawRequestContextHandler &	raw_request_context_handler () const noexcept
	Returns the registered raw request context handler, if any.

void	set_raw_notification_handler (RawNotificationHandler handler)
	Registers a raw notification hook.

void	set_custom_request_handler (RawRequestHandler handler)
	Registers a custom request handler.

void	set_custom_request_handler (RawRequestContextHandler handler)

void	set_custom_notification_handler (RawNotificationHandler handler)
	Registers a custom notification handler.

void	set_task_list_handler (TaskListHandler handler)
	Registers a task list request handler.

void	set_tools_list_handler (ToolsListHandler handler)
	Registers a tools/list request handler.

void	set_prompts_list_handler (PromptsListHandler handler)
	Registers a prompts/list request handler.

void	set_resources_list_handler (ResourcesListHandler handler)
	Registers a resources/list request handler.

void	set_resource_templates_list_handler (ResourceTemplatesListHandler handler)
	Registers a resources/templates/list request handler.

void	set_task_get_handler (TaskGetHandler handler)
	Registers a task get request handler.

void	set_task_cancel_handler (TaskCancelHandler handler)
	Registers a task cancel request handler.

void	set_task_result_handler (TaskResultHandler handler)
	Registers a task result request handler.

void	set_progress_handler (ProgressHandler handler)
	Registers a progress notification handler.

void	set_roots_list_changed_handler (RootsListChangedHandler handler)
	Registers a roots-list-changed notification handler.

void	set_tool_list_changed_handler (ListChangedHandler handler)
	Registers a tool-list-changed notification handler.

void	set_prompt_list_changed_handler (ListChangedHandler handler)
	Registers a prompt-list-changed notification handler.

void	set_resource_list_changed_handler (ListChangedHandler handler)
	Registers a resource-list-changed notification handler.

void	set_resource_updated_handler (ResourceUpdatedHandler handler)
	Registers a resource-updated notification handler.

Server &	set_handler (const ServerHandler &handler)
	Installs every non-empty callback from a ServerHandler aggregate.

Server &	set_handler (const ServerHandlerInterface &handler)
	Installs callbacks from a borrowed ServerHandlerInterface contract.

Server &	set_handler (std::shared_ptr< const ServerHandlerInterface > handler)
	Installs callbacks from an owned ServerHandlerInterface contract.

Detailed Description

High-level MCP server compatibility API.

Server owns the configured transports and registries. Register tools, prompts, resources, and resource templates before start(), then use transports to serve JSON-RPC requests. Direct list/get/call/read methods are also available for tests, embedded use, and custom routing. New applications should prefer ServerPeer and Service as their entry points; Server remains a stable embeddable layer and compatibility surface.

Member Typedef Documentation

◆ RawRequestHandler

using mcp::server::Server::RawRequestHandler = std::function<std::optional<protocol::JsonRpcResponse>( const protocol::JsonRpcRequest&, const SessionContext&)>

Optionally handles raw or custom requests before built-in fallback.

Returns: A response when handled, or std::nullopt to let normal dispatch continue.

Constructor & Destructor Documentation

◆ Server()

mcp::server::Server::Server ( ServerOptions options )

explicit

Constructs a server from explicit options.

Parameters

options Server capabilities, name, version, and instructions.

Member Function Documentation

◆ add_session_transport()

core::Result< core::Unit > mcp::server::Server::add_session_transport ( Transport & transport )

Registers a borrowed session transport for outbound server events.

The server does not own, start, or stop this transport. Peer/Service uses this low-level hook to keep server-initiated notifications and resource subscription routing working when the receive loop is driven by a role-generic transport.

◆ add_transport()

core::Result< core::Unit > mcp::server::Server::add_transport ( std::unique_ptr< Transport > transport )

Adds a transport owned by the server.

Parameters

transport Transport to start when start() is called. It must not be null.

◆ authenticate_context()

core::Result< SessionContext > mcp::server::Server::authenticate_context ( const SessionContext & context )

Applies the configured AuthProvider to a session context.

Returns the input context unchanged when no provider is configured or the context already contains an authenticated identity. ServerPeer uses this hook before native dispatch so peer-boundary handlers cannot bypass server auth policy.

◆ call_tool()

core::Result< protocol::ToolResult > mcp::server::Server::call_tool	(	std::string_view	name,
		protocol::Json	arguments = `protocol::Json::object()`,
		const std::string &	session_id = `{}`
	)		const

Invokes a registered tool.

Parameters

name	Registered tool name.
arguments	JSON arguments supplied to the tool handler.
session_id	Optional session identifier passed into the tool context.

Returns: Tool result, or an MCP error if the tool is missing or fails.

◆ enqueue_task()

core::Result< protocol::CreateTaskResult > mcp::server::Server::enqueue_task ( const protocol::Task & task )

Sends a server-to-client request to create a new task.

This lets the server proactively create a task on the client, for example when a long-running background job is initiated server-side. The returned CreateTaskResult carries the client-accepted task snapshot.

◆ get_prompt()

core::Result< protocol::PromptsGetResult > mcp::server::Server::get_prompt	(	std::string_view	name,
		protocol::Json	arguments = `protocol::Json::object()`,
		const std::string &	session_id = `{}`
	)		const

Gets a registered prompt result.

Parameters

name	Registered prompt name.
arguments	JSON arguments supplied to the prompt handler.
session_id	Optional session identifier passed into the prompt context.

◆ handle_request()

core::Result< protocol::JsonRpcResponse > mcp::server::Server::handle_request	(	const protocol::JsonRpcRequest &	request,
		const SessionContext &	context
	)

Dispatches an inbound JSON-RPC request from a transport.

Parameters

request	Incoming request.
context	Session and transport context associated with the request.

Returns: JSON-RPC response, or an error before response construction.

◆ notify_elicitation_complete()

core::Result< core::Unit > mcp::server::Server::notify_elicitation_complete ( std::string elicitation_id )

Sends an elicitation-complete notification.

Parameters

elicitation_id Identifier of the completed elicitation request.

◆ notify_resource_updated()

core::Result< core::Unit > mcp::server::Server::notify_resource_updated ( std::string_view uri )

Notifies subscribed clients that a resource URI was updated.

Parameters

uri	Resource URI that changed.

◆ ping()

core::Result< protocol::Json > mcp::server::Server::ping ( const SessionContext & context = {} )

Handles a ping request.

Parameters

context Session context for the requester.

◆ read_resource()

core::Result< protocol::ResourcesReadResult > mcp::server::Server::read_resource	(	std::string_view	uri,
		protocol::Json	params = `protocol::Json::object()`,
		const std::string &	session_id = `{}`
	)		const

Reads a registered resource.

Parameters

uri	Registered resource URI.
params	Optional JSON parameters supplied to the resource handler.
session_id	Optional session identifier passed into the resource context.

◆ set_handler() [1/3]

Server & mcp::server::Server::set_handler ( const ServerHandler & handler )

inline

Installs every non-empty callback from a ServerHandler aggregate.

Installs all non-empty callbacks from a ServerHandler.

Parameters

handler Callback aggregate. Empty members leave existing callbacks unchanged.

Returns: Reference to this server for chaining.; Reference to this server for chaining.

◆ set_handler() [2/3]

Server & mcp::server::Server::set_handler ( const ServerHandlerInterface & handler )

inline

Installs callbacks from a borrowed ServerHandlerInterface contract.

Installs callbacks from a borrowed contract-style server handler.

Parameters

handler Handler contract. The caller must keep it alive until all installed callbacks are replaced or the Server is destroyed. Unimplemented methods fall back to the server's built-in dispatch or a method-not-found response.

◆ set_handler() [3/3]

Server & mcp::server::Server::set_handler ( std::shared_ptr< const ServerHandlerInterface > handler )

inline

Installs callbacks from an owned ServerHandlerInterface contract.

Installs callbacks from an owned contract-style server handler.

Parameters

handler Shared handler contract kept alive by installed callbacks. Unimplemented methods fall back to the server's built-in dispatch or a method-not-found response.

Exceptions

std::invalid_argument if handler is null.

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

sdk/server/include/cxxmcp/server/server.hpp
sdk/server/include/cxxmcp/server/handler.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ RawRequestHandler

Constructor & Destructor Documentation

◆ Server()

Member Function Documentation

◆ add_session_transport()

◆ add_transport()

◆ authenticate_context()

◆ call_tool()

◆ enqueue_task()

◆ get_prompt()

◆ handle_request()

◆ notify_elicitation_complete()

◆ notify_resource_updated()

◆ ping()

◆ read_resource()

◆ set_handler() [1/3]

◆ set_handler() [2/3]

◆ set_handler() [3/3]