typename Session = stateless

Per-session state type. stateless (the default) disables sessions: no Mcp-Session-Id header is issued or required. Any other type enables stateful mode: a session is created on initialize, identified by Mcp-Session-Id, serialised (one call at a time), and removed by DELETE or after the idle timeout.

typename... Context

Context types forwarded from the HTTP session (the connection context, keyed contexts from wrappers). Tool and resource callables may request any of these and, in stateful mode, the Session type and session_info (the session's id).

explicit endpoint(server_info info);

endpoint(endpoint const &) = delete;

endpoint & operator=(endpoint const &) = delete;

template<typename Callable, typename... Providers> 
  endpoint & tool(std::string name, std::string description, 
                  Callable && callable, Providers... providers);

Leading context parameters are injected; the rest come from mcp_arg providers. The callable may return a plain value (rendered as text plus structuredContent) or one of the typed results in <boost/taar/mcp/content.hpp>: tool_result, image, audio, embedded_resource or text.

template<typename Callable, typename... Providers> 
  endpoint & tool(tool_spec spec, Callable && callable, 
                  Providers... providers);

template<typename Completer> 
  endpoint & complete_prompt(std::string prompt, std::string argument, 
                             Completer completer);

completer is called with a completion_request, or just the typed value as a std::string_view, and returns a completion_result or a std::vector<std::string>.

template<typename Completer> 
  endpoint & complete_resource(std::string uri_template, std::string argument, 
                               Completer completer);

template<typename Callable, typename... Providers> 
  endpoint & resource(std::string uri, std::string mime_type, 
                      std::string description, Callable && callable, 
                      Providers... providers);

template<typename Callable, typename... Providers> 
  endpoint & prompt(std::string name, std::string description, 
                    Callable && callable, Providers... providers);

Arguments are bound with mcp_arg from params.arguments (prompt arguments are strings). The callable may return a std::string (one user text message), a boost::json::array of messages, or an object with messages (and optional description).

std::vector< prompt_info > prompts() const;

std::size_t resource_updated(std::string const & uri);

Returns the number notified.

std::size_t tools_changed();

std::size_t resources_changed();

std::size_t prompts_changed();

template<typename F> endpoint & on_initialize(F f);

In stateful mode the callable is (Session&, initialize_params const&) and runs on the freshly created session; if it throws, the session is discarded and the client receives an error. In stateless mode it is (initialize_params const&).

awaitable< boost::json::value > 
request(std::string const & session_id, std::string method, 
        boost::json::value params = {}, 
        std::chrono::steady_clock::duration timeout = {});

The request travels over the session's GET stream (or stdout on stdio); the client answers by posting a JSON-RPC response to the endpoint. Returns the result. Failures throw boost::taar::exception whose failure carries

Cancelling the awaiting coroutine (for instance through request_scope) abandons the request.

Usable from a tool: it does not need the session lock, which the calling tool already holds. A zero timeout means server_info::request_timeout.

awaitable< boost::json::value > 
create_message(std::string const & session_id, boost::json::object params, 
               std::chrono::steady_clock::duration timeout = {});

awaitable< boost::json::value > 
elicit(std::string const & session_id, std::string message, 
       boost::json::object requested_schema, 
       std::chrono::steady_clock::duration timeout = {});

requested_schema is a flat JSON Schema object describing the fields. The result is the protocol's {action, content} object, where action is accept, decline or cancel.

awaitable< boost::json::value > 
list_roots(std::string const & session_id, 
           std::chrono::steady_clock::duration timeout = {});

void on_client_notification(std::string method, 
                            std::function< void(contexts_type const &, boost::json::value const &)> handler);

Runs under the session lock with the session contexts; the second argument is params.

void set_tool_error_handler(tool_error_handler h);

See default_tool_error_handler.

h is invoked as h(taar::failure const&) and returns the isError text, or nullopt to send a JSON-RPC error instead. A handler that throws falls back to the default.

endpoint.set_tool_error_handler([](taar::failure const& f) -> std::optional<std::string>
{
    if (f.as<division_by_zero>()) return std::nullopt;     // a JSON-RPC error
    return mcp::default_tool_error_handler(f);
});

void set_origin_validator(std::function< bool(std::string_view)> v);

rpc_type & rpc() noexcept;

rpc_type const & rpc() const noexcept;

server_info const & info() const noexcept;

std::vector< tool_info > tools() const;

std::vector< resource_info > resources() const;

std::size_t session_count() const;

std::size_t sweep_sessions();

bool notify(std::string const & session_id, std::string_view method, 
            boost::json::value params = {});

Delivered when the client has a GET stream open; otherwise held until it opens one or the session ends. Does not refresh the session's idle timer.

bool log(std::string const & session_id, log_level level, 
         boost::json::value data, std::string logger = {});

Send a notifications/message log entry to one session (stateful mode).

Dropped, returning false, when level is below the level the client set with logging/setLevel (initially server_info::default_log_level) or the session is unknown.

std::size_t log_all(log_level level, boost::json::value data, 
                    std::string logger = {});

std::size_t broadcast(std::string_view method, boost::json::value params = {});

auto stream_handler();

Register it on the same route as handler() for GET:

session.register_request_handler(method == http::verb::get && target == "/mcp", mcp.stream_handler());
session.register_request_handler(target == "/mcp", mcp.handler());

The response is text/event-stream; one stream per session (a second GET while one is open is answered 409). The stream ends when the session is deleted or expires.

handler_type handler();

awaitable< response_type > 
handle(incoming_contexts const & incoming, request_type const & request, 
       matcher::context const & mctx);