服务端概述

McpServer 类向连接的 MCP 客户端暴露能力（工具、资源、提示）。

创建服务端

cpp

auto transport = std::make_shared<StdioServerTransport>();

ServerOptions opts;
opts.server_info = Implementation{"MyServer", "1.0.0"};

auto server = McpServer::Create(transport, opts);
server->Run();

对于 Streamable HTTP 模式：

cpp

StreamableHttpServerOptions http_opts;
http_opts.port = 3001;
http_opts.stateless = true;  // 或 false 使用会话模式

auto transport = std::make_shared<StreamableHttpServerTransport>(http_opts);

ServerOptions opts;
opts.server_info = Implementation{"MyServer", "1.0.0"};

auto server = McpServer::Create(transport, opts);
server->Run();

ServerOptions

字段	类型	描述
`server_info`	`optional<Implementation>`	服务端标识（名称、版本）
`protocol_version`	`optional<string>`	固定到特定协议版本
`server_instructions`	`optional<string>`	发送给客户端的指令
`initialization_timeout`	`chrono::seconds`	握手超时时间（默认 60s）
`declare_logging`	`bool`	显式声明 logging 能力（合并进推导能力，默认 `false`）
`declare_completions`	`bool`	显式声明 completions 能力（默认 `false`）
`task_store`	`shared_ptr<IMcpTaskStore>`	任务持久化后端
`request_state_verifier`	`function<bool(string_view)>`	MRTR 的 HMAC/AEAD 验证器
`request_state_key`	`optional<string>`	MRTR 服务端请求状态签名密钥（HMAC）；设置后若未显式提供 `request_state_verifier`，自动接线内置验证器，在处理器前拒绝篡改/过期的状态（返回 -32602 且 `data.reason="invalid_request_state"`）
`request_state_ttl`	`chrono::seconds`	签发的请求状态最大寿命（默认 0 = 不检查过期）
`cache_hints`	`optional<map<string, CacheHint, less<>>>`	按方法的缓存提示（ttlMs, cacheScope）
`cache_hint_resolver`	`function<optional<CacheHint>(string_view)>`	按方法动态解析缓存提示的逃生钩子（优先于 `cache_hints` 静态表；运行时可经 `SetCacheable` 替换）
`supported_protocol_versions`	`optional<vector<string>>`	窄化服务端支持版本表（discover 应答、initialize 候选集、`_meta` 门控与错误 `data.supported` 三处同时生效；空即全表）
`subscriptions_enabled`	`bool`	订阅总开关（默认 `true`；关闭则 `subscriptions/listen` 回 `MethodNotFound`）
`max_tool_input_elements`	`optional<size_t>`	工具参数元素数上限（对象键数/数组长度；超限回 `is_error` 工具结果而非协议错误）
`input_required_config`	`optional<InputRequiredConfig>`	MRTR/elicitation 行为的配置
`input_required_config.max_rounds`	`int`	最大启发式收集轮次（默认 10）
`input_required_config.round_timeout`	`chrono::seconds`	每轮超时时间（默认 600s）
`input_required_config.legacy_shim`	`bool`	启用旧版兼容垫片（默认 true）
`on_request`	`function`	收到每个入站 JSON-RPC 请求时回调，包含方法名和完整请求体
`on_response`	`function`	发送每个出站 JSON-RPC 响应时回调
`on_error`	`function`	发送每个出站 JSON-RPC 错误时回调
`on_notification`	`function`	收到每个入站 JSON-RPC 通知时回调
`on_method_called`	`function(string_view)`	简写——仅方法名（与 `on_request` 同时触发）
`on_protocol_error`	`function(string_view)`	简写——仅错误消息（与 `on_error` 同时触发）
`on_client_connected`	`function(const Implementation&)`	客户端完成 `initialize` 时回调
`on_initialized`	`function()`	客户端发送 `notifications/initialized` 时回调
`on_transport_close`	`function()`	传输连接关闭时回调
`on_transport_error`	`function(string_view)`	传输层错误时回调
`incoming_filters`	`shared_ptr<FilterPipeline>`	用于拦截/修改/阻断入站消息的管道
`outgoing_filters`	`shared_ptr<FilterPipeline>`	用于拦截/修改/阻断出站消息的管道

简写回调（on_method_called、on_protocol_error）和完整消息回调（on_request、on_error）为链式触发 — 同时设置时两者都会触发。

RequestContext<TParams>

每个工具处理器接收到一个 RequestContext<CallToolRequestParams>，提供请求上下文：

成员	返回类型	说明
`Params()`	`const TParams&`	反序列化后的请求参数
`Server()`	`McpServer&`	所属服务端实例的引用
`GetRequest()`	`const JsonRpcRequest&`	原始 JSON-RPC 请求
`LogLevel()`	`optional<LoggingLevel>`	来自 `_meta` 的每请求日志级别（2026 时代）
`Log(level, data)`	`void`	发送日志通知，受 `LogLevel()` 过滤
`IsCancellationRequested()`	`bool`	本请求是否已收到 `notifications/cancelled`；handler 轮询该标志实现协作取消

Log() 方法遵循每请求日志级别：低于请求 LogLevel() 的消息会被静默丢弃。

McpServerTool

对于可复用的工具定义，可以继承 McpServerTool 或使用 McpServerTool::Create：

cpp

auto tool = McpServerTool::Create("get_weather",
    [](const RequestContext<CallToolRequestParams>& ctx) -> CallToolResult {
        // ...
    },
    ToolOptions{}.Description("获取天气"));
server->RegisterTool(tool);

McpServerTool 抽象类暴露：

ProtocolTool() — 返回协议层的 Tool 结构体
InvokeAsync(ctx, promise) — 重写以实现自定义异步执行

基于 lambda 的 RegisterTool 重载内部同样创建 McpServerTool，行为一致。

属性

方法	返回类型	说明
`GetClientCapabilities()`	`std::shared_ptr<const ClientCapabilities>`	仅在 2025 时代客户端 `initialize` 握手时填充；2026 时代（无 initialize）下恒为 nullptr
`GetClientInfo()`	`std::shared_ptr<const Implementation>`	客户端标识（连接前为 nullptr）
`GetNegotiatedProtocolVersion()`	`std::string`	协商后的协议版本字符串
`GetCapabilities()`	`const ServerCapabilities&`	从注册原语自动推导的服务端能力
`IsMrtrSupported()`	`bool`	是否支持 MRTR（多轮工具检索）

通知

方法	说明
`SendToolListChanged()`	通知客户端工具列表已变更
`SendResourceListChanged()`	通知客户端资源列表已变更
`SendResourceUpdated(uri)`	通知客户端某个资源的内容已变更（只投递给订阅了该 uri 的订阅者）
`SendPromptListChanged()`	通知客户端提示列表已变更
`SendLoggingMessage(level, data)`	发送日志消息（遵循客户端的 `logging/setLevel`）
`SendLoggingMessage(level, data, min_level)`	重载，带有显式最低级别覆盖

补全处理器

为 completion/complete 请求注册可选处理器（如参数自动补全）：

cpp

server->SetCompletionHandler(
    [](const CompleteRequestParams& params) -> CompleteResult {
        CompleteResult result;
        result.completion = JsonValue::Parse(R"({"values":["value1","value2"]})");
        return result;
    });

生命周期

构造：McpServer::Create — 创建会话处理器、挂载处理器、启动消息循环
注册：通过 RegisterTool、RegisterResource、RegisterResourceTemplate、RegisterPrompt 注册工具、资源、提示
运行：server->Run() — 阻塞直到 Close() 被调用；会话处理器异步处理消息
关闭：server->Close() — 等待待处理的异步调用、关闭处理器和传输层

能力推导

能力从注册的原语中自动推导。例如，注册工具会设置 capabilities.tools.list_changed = true。ServerOptions 没有 capabilities 字段——能力始终从已注册的工具、资源、提示和任务存储自动推导；例外是 declare_logging 与 declare_completions，为 true 时即使尚未注册对应处理器也会显式声明 logging/completions 能力（合并进推导结果）。

服务端概述 ​

创建服务端 ​

ServerOptions ​

RequestContext<TParams> ​

McpServerTool ​

属性 ​

通知 ​

补全处理器 ​

生命周期 ​

能力推导 ​