# cxxmcp

[![C++17](https://img.shields.io/badge/C%2B%2B-17-00599C.svg)](https://isocpp.org/)
[![CMake](https://img.shields.io/badge/build-CMake-064F8C.svg)](https://cmake.org/)
[![Release gates](https://github.com/caomengxuan666/cxxmcp/actions/workflows/release-gates.yml/badge.svg)](https://github.com/caomengxuan666/cxxmcp/actions/workflows/release-gates.yml)
[![Pages](https://github.com/caomengxuan666/cxxmcp/actions/workflows/pages.yml/badge.svg)](https://caomengxuan666.github.io/cxxmcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/protocol-Model%20Context%20Protocol-111827.svg)](https://modelcontextprotocol.io/)
[![Server Conformance](https://img.shields.io/badge/Server%20Conformance-272%2F272%20(100%25)-brightgreen.svg)](docs/conformance_evidence.md)
[![Client Conformance](https://img.shields.io/badge/Client%20Conformance-501%2F501%20(100%25)-brightgreen.svg)](docs/conformance_evidence.md)

A production-ready C++17 SDK for the [Model Context Protocol](https://modelcontextprotocol.io/) — build MCP servers and clients that embed directly into native C++ applications, with full protocol coverage and cross-SDK conformance validation.

Read this in [Chinese](README_zh.md).

## Quick Start

```cmake
find_package(cxxmcp CONFIG REQUIRED)
target_link_libraries(my_server PRIVATE cxxmcp::server)
target_link_libraries(my_client PRIVATE cxxmcp::client)
```

```cpp
#include <cxxmcp/peer.hpp>
#include <cxxmcp/run.hpp>

int main() {
    return mcp::ServerPeer::builder()
        .name("demo-server")
        .version("1.0.0")
        .stdio()
        .tool<mcp::protocol::Json, mcp::protocol::Json>("echo",
            [](const mcp::protocol::Json& input) {
                return mcp::protocol::Json{{"echo", input}};
            })
        .run();
}
```

```cpp
// Client side
#include <cxxmcp/peer.hpp>
#include <cxxmcp/run.hpp>

int main() {
    int status = 0;
    const auto run_status = mcp::ClientPeer::builder()
        .streamable_http("http://127.0.0.1:3000/mcp")
        .run([&status](auto& svc) {
            if (!svc.peer().initialize().has_value() ||
                !svc.peer().notify_initialized().has_value() ||
                !svc.peer().list_all_tools().has_value() ||
                !svc.peer()
                     .call_tool("echo",
                                mcp::protocol::Json{{"value", "hello"}})
                     .has_value()) {
                status = 1;
            }
        });
    return run_status == 0 ? status : run_status;
}
```

## What It Covers

| Area | Status |
|---|---|
| Protocol versions | `2024-11-05` → `2026-07-28` + `DRAFT-2026-v1`, negotiated at initialize; per-request stateless wire on draft |
| Protocol & JSON-RPC | Typed models, serialization, `CXXMCP_REFLECT` DTO macros, initialize validation, raw escape hatches |
| Server SDK | Tool/prompt/resource registries, typed handlers, task-aware calls, notifications, subscriptions/listen streaming |
| Client SDK | HTTP (stateful + stateless), stdio, process-stdio, async helpers, roots, sampling, elicitation, tasks |
| Transports | stdio, process stdio, Streamable HTTP (stateful sessions + SEP-2575 stateless wire), legacy SSE compat, WebSocket (auto-reconnect) |
| Auth (opt-in) | OAuth 2.1 / PKCE, DPoP (RFC 9449) proofs and nonce retry, WIF JWT-bearer, dynamic client registration, authorization-server migration |
| Packaging | CMake `find_package`, Conan 2, vcpkg overlay, FetchContent / CPM |
| Peer/Service boundary | RMCP-style role-aware `Peer<Role>` and `Service<Role>` |

**Protocol coverage:** tool, prompt, resource, resource template, completion, logging, roots, sampling, elicitation, task lifecycle (SEP-2663), skills (SEP-2640), subscriptions, progress, cancellation, and raw JSON-RPC escape hatches for vendor extensions.

**Conformance:** Validated against the official `modelcontextprotocol/conformance` runner (`--suite all`).

| | cxxmcp | RMCP |
|---|---|---|
| Server | **272/272** (100%) | 48/95 (51%) |
| Client | **501/501** (100%) | — (runner crashed) |

Full details in [conformance evidence](docs/conformance_evidence.md).

## Capability Snapshot

cxxmcp is a release-candidate-quality C++ MCP SDK with full protocol coverage, cross-SDK conformance validation, and multiple transport options. See [conformance evidence](docs/conformance_evidence.md) and [ecosystem maturity evidence](docs/ecosystem_maturity_evidence.md) for details.

## Install

```cmake
find_package(cxxmcp CONFIG REQUIRED)

# Server
target_link_libraries(my_server PRIVATE cxxmcp::server)
# Client
target_link_libraries(my_client PRIVATE cxxmcp::client)
# Everything
target_link_libraries(my_app PRIVATE cxxmcp::sdk)
```

Build from source:

```powershell
cmake -S . -B build -DCXXMCP_BUILD_CLIENT=ON -DCXXMCP_BUILD_SERVER=ON
cmake --build build --config Release
cmake --install build --config Release --prefix out/install/cxxmcp
```

The quick-start client uses Streamable HTTP, so source builds that compile that
client path must also set `-DCXXMCP_ENABLE_HTTP=ON`.

Package managers: `conanfile.py` (Conan 2), `packaging/vcpkg/ports/cxxmcp-sdk` (vcpkg overlay), `packaging/xmake/` (xmake). See [package consumption](docs/package_consumption.md).

## CMake Options

| Option | Default | Description |
|---|---:|---|
| `CXXMCP_BUILD_SDK` | `ON` | Build the aggregate SDK layer (protocol + client + server) |
| `CXXMCP_BUILD_PROTOCOL` | `ON` | Build the MCP protocol library |
| `CXXMCP_BUILD_CLIENT` | `OFF` | Build the MCP client library |
| `CXXMCP_BUILD_SERVER` | `OFF` | Build the MCP server library |
| `CXXMCP_BUILD_EXAMPLES` | `OFF` | Build example executables |
| `CXXMCP_BUILD_TESTS` | `BUILD_TESTING` | Build tests |
| `CXXMCP_BUILD_BENCHMARKS` | `OFF` | Build benchmark executables |
| `CXXMCP_BUILD_DOCS` | `OFF` | Build Doxygen API documentation |
| `CXXMCP_ENABLE_HTTP` | `OFF` | Build HTTP/SSE transport (uses bundled `cpp-httplib` unless `CXXMCP_USE_SYSTEM_DEPS=ON`) |
| `CXXMCP_ENABLE_OPENSSL` | `OFF` | Enable OpenSSL-backed HTTP/WebSocket TLS support |
| `CXXMCP_ENABLE_AUTH` | `OFF` | Build the optional OAuth 2.1 / DPoP auth target |
| `CXXMCP_AUTH_CRYPTO` | `NONE` | Optional auth crypto backend (`NONE` or `OpenSSL`; requires `CXXMCP_ENABLE_AUTH=ON`) |
| `CXXMCP_ENABLE_WEBSOCKET` | `OFF` | Build WebSocket transport (requires `CXXMCP_ENABLE_HTTP`) |
| `CXXMCP_USE_SYSTEM_DEPS` | `OFF` | Use package-manager dependencies instead of bundled header-only SDK dependencies |
| `CXXMCP_SDK_CXX_STANDARD` | `17` | Minimum C++ standard required by exported SDK targets (`17`, `20`, `23`, or `26`) |
| `CXXMCP_MSVC_RUNTIME_LIBRARY` | empty | Optional MSVC runtime library override; empty keeps the toolchain default |

## Package Targets

| Target | Purpose |
|---|---|
| `cxxmcp::protocol` | MCP protocol models and JSON-RPC serialization |
| `cxxmcp::transport` | Role-generic transport contracts |
| `cxxmcp::handler` | Client/server handler interfaces |
| `cxxmcp::peer` | Role-aware execution boundary |
| `cxxmcp::service` | Service lifecycle boundary |
| `cxxmcp::client` | Embeddable MCP client SDK |
| `cxxmcp::server` | Embeddable MCP server SDK |
| `cxxmcp::auth` | Optional OAuth 2.1 / DPoP contract (`CXXMCP_ENABLE_AUTH=ON`) |
| `cxxmcp::auth_openssl` | Optional OpenSSL-backed JOSE/JWT/DPoP helpers (`CXXMCP_ENABLE_AUTH=ON`, `CXXMCP_AUTH_CRYPTO=OpenSSL`) |
| `cxxmcp::sdk` | Aggregate public SDK target |

## Why cxxmcp

- Standard CMake SDK consumption — `find_package` and go
- C++17 public API, no runtime dependencies beyond the standard library
- Full MCP protocol coverage with typed, capability-gated helpers
- Cross-SDK conformance validation against the official runner
- RMCP-style Peer/Service architecture designed for embedding
- stdio, process-stdio, Streamable HTTP, and WebSocket transports out of the box

## Examples

In-tree examples cover server/client peers, auth, tasks, elicitation, and transport adapters. Run them with:

```powershell
cmake --preset examples && cmake --build --preset examples && ctest --preset examples
```

See [examples.md](docs/examples.md) for the full list. The separate [cxxmcp-examples](https://github.com/caomengxuan666/cxxmcp-examples) repository exercises the SDK through an external CMake project with advanced scenarios.

## Documentation

- [GitHub Pages](https://caomengxuan666.github.io/cxxmcp/) — API reference
- [Conformance evidence](docs/conformance_evidence.md) — test results and known exceptions
- [Compatibility policy](docs/compatibility_policy.md) — versioning, compiler matrix, ABI
- [Dependency policy](DEPENDENCY_POLICY.md) — update policy and package dependency boundaries
- [HTTP transport backend evidence](docs/compatibility_policy.md#http-transport-backend-evidence)
- [Release gates](docs/release_gates.md) — release-blocking checks
- [Runtime gateway](docs/runtime_gateway.md) — external gateway boundary
- [Examples](docs/examples.md) — full example list
- [Auth design](docs/auth_design.md) — OAuth 2.1 / DPoP direction
- [Request lifecycle](docs/request_lifecycle.md) — timeout, cancellation, progress, shutdown
- [Contributing](CONTRIBUTING.md) | [Security](SECURITY.md) | [Changelog](CHANGELOG.md)

## Status

cxxmcp is a community C++ MCP SDK preparing official SDK candidate evidence. The Peer/Service boundary, transport layer, and conformance gates are in release-candidate shape. It is not an official MCP SDK unless accepted by the MCP maintainers.

### Compiler Compatibility

MinGW UCRT64 GCC and MinGW CLANG64 Clang are tracked as provisional, best-effort compiler compatibility evidence. These targets are not release-supported. The `compiler-compat` workflow runs them with `continue-on-error: true` while they remain provisional.