MCP C++ SDK

中文版文档：README_zh.md

C++17 implementation of the Model Context Protocol (MCP), providing both client and server libraries for building MCP-based AI tooling integrations.

<details> <summary>Table of Contents</summary>

• What is MCP?
• Requirements
• Installation
• Quick Start
• Architecture
• Transports
• Usage
• OAuth Support
• Protocol Versions
• Conformance Tests
• Examples
• Related Projects
• Unsupported Declarations
• License

</details>

What is MCP?

The Model Context Protocol lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. With this SDK you can:

• Build MCP servers that expose tools, resources, and prompts to any MCP host
• Build MCP clients that connect to any MCP server
• Support every standard transport: stdio, Streamable HTTP, SSE, WebSocket

Requirements

| Dependency | Minimum Version | Notes | |----------------|----------------|------------------------------| | CMake | 3.28 | Generator: Ninja recommended | | C++ Compiler | C++17 | MSVC, Clang, GCC | | OpenSSL | (optional) | Controlled by the MCP_WITH_OPENSSL switch (AUTO/ON/OFF, default AUTO). Required for TLS (WebSocket, SSE HTTPS); OAuth PKCE works without it (built-in SHA-256 fallback). Install: vcpkg install openssl / apt install libssl-dev / brew install openssl |

Supported platforms: Windows (MSVC, clang-cl), Linux (GCC, Clang), macOS (Clang).

Installation

Consume the SDK in your own CMake project via FetchContent:

include(FetchContent)
FetchContent_Declare(
    mcp-cpp-sdk
    GIT_REPOSITORY https://github.com/jesspig/modelcontextprotocol-cpp-sdk.git
    GIT_TAG        master
)
FetchContent_MakeAvailable(mcp-cpp-sdk)

target_link_libraries(your_target PRIVATE mcp-client mcp-server)

Available library targets: mcp-core, mcp-transport, mcp-protocol, mcp-server, mcp-client, mcp-http. All libraries are static.

Quick Start

cmake --preset debug
cmake --build --preset debug
ctest --preset debug --output-on-failure

Configure presets: debug, release. Ninja generator required.

Architecture

┌─────────────────────────────────────┐
│  mcp-server        mcp-client       │  Server & Client API
├─────────────────────────────────────┤
│  mcp-protocol                       │  WireCodec, McpSessionHandler
├─────────────────────────────────────┤
│  mcp-transport       mcp-http       │  Transports, Streamable HTTP, SSE
├─────────────────────────────────────┤
│  mcp-core                           │  Types, JSON-RPC, interfaces
└─────────────────────────────────────┘

Library dependency chain: mcp-core (STATIC) → mcp-transport → mcp-protocol → mcp-server | mcp-client. mcp-http depends on mcp-transport. All libraries are static.

• mcp-core — Core types, JSON-RPC message structures, error codes, capabilities, content types, transport interfaces.
• mcp-transport — Transport implementations: StdioServerTransport, StdioClientTransport, SseClientTransport, InMemoryTransport, WebSocketClientTransport, StreamableHttpServerTransport, StreamableHttpClientTransport. Platform-specific I/O in detail/ (posix, win32).
• mcp-protocol — McpSessionHandler (JSON-RPC engine), dual-era WireCodec (2025-11-25 / 2026-07-28), request/response correlation with timeout, MessageFilter pipeline.
• mcp-server — McpServer with tool/resource/prompt registration, IMcpTaskStore (incl. FileTaskStore), MRTR (InputRequiredResult), server → client elicitation, subscription management.
• mcp-client — McpClient with server discovery (server/discover → initialize fallback), version negotiation, OAuth (PKCE/CIMD with DCR fallback), MRTR (InputRequired loop), tool cache, FileTokenCache.
• mcp-http — HTTP server for Streamable HTTP mode: HttpServer, EventStore (SSE event persistence), StreamableHttpServerTransport, StreamableHttpClientTransport.

All transports

| Transport | Client | Server | Description | |-----------------|--------|--------|--------------------------------------------------| | Stdio | Yes | Yes | stdin/stdout pipes, subprocess communication | | Streamable HTTP | Yes | Yes | HTTP POST with JSON/session-mode responses | | SSE | Yes | Yes¹ | Server-Sent Events for push notifications | | WebSocket | Yes | No | TCP-based bidirectional (self-hosted WebSocketClient) | | InMemory | Yes | Yes | In-process transport for testing |

¹ SSE server-side is provided through StreamableHttpServerTransport when enable_legacy_sse is true, which serves an SSE stream via HTTP GET.

Usage

Server

#include <mcp/server/McpServer.hpp>
#include <mcp/transport/StdioServerTransport.hpp>

using namespace mcp;

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

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

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

    server->RegisterTool("echo",
        ToolOptions{}.Description("Echo input text back"),
        [](const RequestContext<CallToolRequestParams>& ctx) -> CallToolResult {
            std::string text;
            if (ctx.Params().arguments) {
                auto* v = ctx.Params().arguments->Find("text");
                if (v) text = v->GetString();
            }
            CallToolResult result;
            result.content.push_back(TextContent{"text", text});
            return result;
        });

    server->Run();
    return 0;
}

Client

#include <mcp/client/McpClient.hpp>
#include <mcp/transport/StdioClientTransport.hpp>

using namespace mcp;

StdioClientTransportOptions transport_opts;
transport_opts.command = "path/to/server";
auto factory = std::make_shared<StdioClientTransport>(transport_opts);
auto transport = factory->Connect();
ClientOptions opts;
opts.client_info = Implementation{"MyClient", "1.0.0"};

auto client = McpClient::Create(transport, opts);

auto tools = client->ListTools();
for (const auto& tool : tools.tools) {
    std::cout << tool.name << "\n";
}

auto result = client->CallTool("echo",
    JsonValue::Object{{"text", "Hello, MCP!"}});

OAuth Support

The client supports the MCP OAuth authorization flow:

• Authorization Code + PKCE flow with S256 code challenge
• CIMD client identity with DCR fallback (an http(s):// client_id is fetched as a client metadata document; dynamic registration only when no client_id is configured)
• Token refresh and revocation
• Pluggable token cache (ITokenCache), persistent FileTokenCache included
• DPoP (RFC 9449): server-side proof verification on the Streamable HTTP resource server — off by default, turned on per deployment with the experimental enable_dpop switch (StreamableHttpServerOptions::bearer_auth->enable_dpop), and requires OpenSSL; the client side can bind the authorization scheme and mint proofs (OAuthClientOptions::enable_dpop), but transports attach per-request DPoP proof when apply_per_request_headers/observe_response_challenge are bound via ApplyDPoPProofHeader/ObserveDPoPNonce

OAuthClientOptions oauth_opts;
oauth_opts.server_url = "https://auth.server.com/.well-known/oauth-authorization-server";
oauth_opts.client_id = "client-id";
oauth_opts.redirect_uri = "http://localhost:3000/callback";

OAuthClientProvider auth(oauth_opts);
auth.Authenticate();

Protocol Versions

| Version | Status | Key Features | |-------------|---------|-----------------------------------| | 2025-11-25 | Legacy | initialize handshake, standalone sampling/roots/list | | 2026-07-28 | Current | server/discover, per-request _meta, MRTR (InputRequiredResult), subscriptions/listen |

The WireCodec factory auto-selects the correct codec for the negotiated version via a simple string comparison (version >= "2026-07-28").

Conformance Tests

113 conformance tests covering protocol type serialization across both eras:

• JSON-RPC message round-trips (request, notification, response, error)
• WireCodec era-gating (2025 vs 2026 method/notification sets)
• Tool, Resource, Prompt serialization with annotations and icons
• Content variant dispatch (text, image, audio, embedded resource)
• Elicitation and ElicitResultTyped<T>
• MRTR (InputRequiredResult, InputRequests, factory helpers)
• Structured meta (RequestMetaObject, NotificationMetaObject)
• Extensions capability, ResultType enum, SubscriptionFilter
• Tasks (get/update/cancel), Logging (8 levels)
• Pagination, caching, protocol version helpers

Examples

Runnable examples in examples/:

| Example | Description | |----------------------------------|------------------------------------------------| | EchoServer | Minimal server with tool, resource, and prompt | | WeatherServer | Server with external API integration | | SimpleClient | Client that connects to a server in-process |

Build and run:

cmake --preset debug -DMCP_BUILD_EXAMPLES=ON
cmake --build --preset debug
# Run the echo server:
build/debug/examples/EchoServer/EchoServer

References

This SDK was developed against the official MCP protocol specification and reference implementations:

| Language | Repository | Tier | |------------|-----------------------------------------------------------------|--------| | Python | modelcontextprotocol/python-sdk | Tier 1 | | TypeScript | modelcontextprotocol/typescript-sdk | Tier 1 | | Go | modelcontextprotocol/go-sdk | Tier 1 | | C# | modelcontextprotocol/csharp-sdk | Tier 1 | | Rust | modelcontextprotocol/rust-sdk | Tier 1 | | Ruby | modelcontextprotocol/ruby-sdk | Tier 1 | | Java | modelcontextprotocol/java-sdk | Tier 2 | | Swift | modelcontextprotocol/swift-sdk | Tier 3 | | PHP | modelcontextprotocol/php-sdk | Tier 3 | | Kotlin | modelcontextprotocol/kotlin-sdk | Tier 3 |

Tiers follow the official SDK list (2026-07-28 revision): 6 Tier 1 (TypeScript, Python, C#, Go, Rust, Ruby — Rust promoted to Tier 1 via [PR #3287](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/328