MCP C++ SDK

The first fully MCP 2025-11-25 compliant C++ SDK - Build production-ready MCP servers and clients with complete protocol support including Streamable HTTP transport and OAuth-based authorization.

Features

Complete MCP 2025-11-25 Implementation

• Transports: stdio + Streamable HTTP (single endpoint, resumable SSE)
• Server Features: Tools, Resources, Prompts with full CRUD operations
• Client Features: Roots, Sampling, Elicitation (form + URL modes)
• Utilities: Ping, Cancellation, Progress, Tasks, Pagination, Logging, Completion
• Authorization: OAuth 2.1 + PKCE, RFC9728 discovery, WWW-Authenticate challenges
• Security: Origin validation, SSRF protection, runtime limits, token storage abstraction

Cross-Platform Support

• Linux (Ubuntu 24.04+)
• macOS (14+)
• Windows (Server 2022+)

Production-Ready

• Comprehensive test suite (18K+ lines, conformance + integration tests)
• CI/CD with pinned dependencies for reproducible builds
• Extensive documentation and security guidelines
• Zero raw pointers - RAII throughout

Quick Start

Prerequisites

• CMake 3.16+
• C++17 compiler (GCC 7+, Clang 5+, MSVC 2017+)
• vcpkg (for dependency management)
• Python 3.12+ (for codebase checks)

Build

# Clone the repository
git clone https://github.com/itcv-GmbH/cpp-mcp-sdk.git
cd cpp-mcp-sdk

# Configure (macOS/Linux)
cmake --preset vcpkg-unix-release

# Configure (Windows)
cmake --preset vcpkg-windows-release

# Build
cmake --build build/vcpkg-unix-release        # macOS/Linux
cmake --build build/vcpkg-windows-release --config Release --parallel  # Windows

Test

# Run all tests
ctest --test-dir build/vcpkg-unix-release

# Run specific test
ctest --test-dir build/vcpkg-unix-release -R mcp_sdk_smoke_test -V

Basic Example - MCP Server

#include <string>

#include <mcp/schema/schema_builder.hpp>
#include <mcp/server/simple_server.hpp>

auto main() -> int
{
  auto server = mcp::server::SimpleServer::create("example", "1.0.0");

  server
    .tool("echo",
          "Echo text",
          mcp::schema::object().requiredString("text").build(),
          [](const mcp::server::ToolCallContext &context) -> mcp::server::CallToolResult
          {
            return mcp::server::CallToolResult::text("echo: " + context.arguments["text"].as<std::string>());
          })
    .staticResource("resource://about", "about", "Server metadata", "Example simple server");

  return server.runStdio();
}

Basic Example - MCP Client

#include <exception>
#include <iostream>
#include <utility>

#include <mcp/client.hpp>
#include <mcp/jsonrpc/types.hpp>
#include <mcp/transport/http/http_client_options.hpp>

auto main() -> int
{
  try
  {
    // Create client
    auto client = mcp::Client::create();
    
    // Connect to MCP server via HTTP and start its transport lifecycle.
    mcp::transport::http::HttpClientOptions httpOptions;
    httpOptions.endpointUrl = "http://localhost:8080/mcp";
    client->connectHttp(httpOptions);
    client->start();

    // Initialize session
    client->initialize().get();

    // List available tools
    const auto toolsResult = client->listTools();
    std::cout << "Available tools: " << toolsResult.tools.size() << '\n';

    // Call a tool
    mcp::jsonrpc::JsonValue arguments = mcp::jsonrpc::JsonValue::object();
    arguments["message"] = "Hello, MCP!";
    client->callTool("echo", std::move(arguments));

    client->stop();
    return 0;
  }
  catch (const std::exception& e)
  {
    std::cerr << "Client error: " << e.what() << '\n';
    return 1;
  }
}

Installation

Using vcpkg (Overlay Port)

# In your CMakeLists.txt
find_package(mcp_sdk CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE mcp::sdk)

Using CMake FetchContent

include(FetchContent)

FetchContent_Declare(
  mcp_sdk
  GIT_REPOSITORY https://github.com/itcv-GmbH/cpp-mcp-sdk.git
  GIT_TAG        v0.1.5  # or specific commit
)

FetchContent_MakeAvailable(mcp_sdk)
target_link_libraries(your_target PRIVATE mcp::sdk)

Documentation

• API Overview - High-level architecture
• Server Quickstart - Building MCP servers
• Client Quickstart - Building MCP clients
• Security Guidelines - Security best practices
• Dependencies - Dependency management
• Version Policy - Protocol versioning strategy

Examples

See examples/ directory for complete working examples:

• minimal_example.cpp - Basic SDK usage
• stdio_server/ - stdio transport server
• dual_transport_server/ - Multi-transport server (stdio + HTTP)
• http_listen_example/ - HTTP server with listen mode
• bidirectional_sampling_elicitation/ - Client sampling and elicitation
• http_server_auth/ - HTTP server with OAuth (requires TLS)
• http_client_auth/ - HTTP client with authentication (requires TLS)
• consumer_find_package/ - CMake consumer example
• consumer_vcpkg_overlay/ - vcpkg overlay consumer example

Architecture

include/mcp/
├── server/          # Server component (tools, resources, prompts)
├── client/          # Client component (roots, sampling, elicitation)
├── transport/       # Transports (stdio, Streamable HTTP)
├── jsonrpc/         # JSON-RPC 2.0 layer
├── auth/            # OAuth authorization
├── security/        # Security policies and limits
├── schema/          # JSON Schema validation
├── lifecycle/       # Session lifecycle management
└── util/            # Utilities (tasks, cancellation, progress)

Testing

Test Categories

• Unit Tests: Individual component testing
• Conformance Tests: MCP spec compliance verification
• Integration Tests: Cross-SDK interoperability
• Feature Matrix Tests: Build configuration variants

Run Tests

# All tests
ctest --test-dir build/vcpkg-unix-release

# Conformance tests only
ctest --test-dir build/vcpkg-unix-release -L conformance

# Integration tests (requires MCP_SDK_INTEGRATION_TESTS=ON)
ctest --test-dir build/vcpkg-unix-release -L integration

Build Options

Compliance

This SDK is fully compliant with MCP specification 2025-11-25:

• ✅ Streamable HTTP transport (single endpoint, resumable SSE)
• ✅ OAuth 2.1 + PKCE authorization
• ✅ RFC9728 resource metadata discovery
• ✅ All server features (tools, resources, prompts)
• ✅ All client features (roots, sampling, elicitation)
• ✅ All utilities (ping, cancellation, progress, tasks)
• ✅ Cross-platform (Linux, macOS, Windows)

See the MCP specification in .docs/requirements/mcp-spec-2025-11-25/ for detailed protocol requirements.

Dependencies

Managed via vcpkg:

• jsoncons - JSON handling
• Boost.Asio - Async I/O
• Boost.Beast - HTTP/WebSocket
• Boost.Process - Process management
• OpenSSL - TLS/crypto (optional)
• Catch2 - Testing framework

Contributing

1. Read AGENTS.md for development guidelines
2. Create a feature branch
3. Make changes following code style (clang-format/clang-tidy)
4. Run tests: ctest --test-dir build/vcpkg-unix-release
5. Run codebase checks: cmake --build build/vcpkg-unix-release --target codebase-check
6. Submit a pull request

Code Quality

# Format code
cmake --build build/vcpkg-unix-release --target clang-format

# Check formatting
cmake --build build/vcpkg-unix-release --target clang-format-check

# Run all codebase checks
python3 tools/checks/run_checks.py

License

This project is dual-licensed:

ORDIS Co., Ltd. is the principal licensor of the ORDIS-controlled portions of this software. The GitHub repository is hosted and administered by itcv GmbH under authority from ORDIS Co., Ltd.

See LICENSE, COMMERCIAL_LICENSE.md, and the licensing history note in LICENSE_HISTORY.md.

Acknowledgments

• Model Context Protocol specification team
• vcpkg for dependency management
• Catch2 for testing framework