CppFastMCP

A modern C++20 client library for the Model Context Protocol (MCP).

CppFastMCP provides a robust, asynchronous, and type-safe implementation of the MCP client specification, enabling C++ applications to connect and interact with local or remote MCP servers. It is built with modern C++ and leverages the Boost.Asio library for high-performance, portable asynchronous I/O.

This library is an independent C++ implementation inspired by the official Python MCP SDK.

Overview

The Model Context Protocol (MCP) is an open standard for connecting AI applications to external systems, tools, and data sources. CppFastMCP allows your C++ application to act as an MCP client, consuming context from any MCP-compliant server.

This library handles the complexity of the MCP lifecycle, message serialization, and transport layers, allowing you to focus on building your application's logic.

Features

• Modern C++20 Design: Utilizes C++20 features for a clean, safe, and expressive API.
• Asynchronous Everywhere: Built on Boost.Asio and C++20 coroutines (co_await) for highly scalable, non-blocking operations.
• Type-Safe Protocol: Implements the MCP type system as C++ structs with compile-time validation where possible.
• JSON Native: Uses nlohmann/json for seamless and efficient JSON-RPC message serialization and deserialization.
• Multiple Transports:
  • StdioTransport: Connect to local MCP servers running as child processes.
  • StreamableHttpTransport: Connect to remote MCP servers over HTTP/S with Server-Sent Events (SSE) for streaming.
• Easy to Integrate: A modern CMake build system makes it simple to fetch dependencies and integrate the library into your project.

Requirements

• A C++20 compliant compiler (GCC 10+, Clang 12+, MSVC v19.29+).
• CMake 3.16 or later.
• Boost 1.74.0 or later (specifically Asio, Beast, and System libraries).
• An internet connection (for FetchContent to download dependencies).

Building the Project

CppFastMCP uses a CMake-based build system. Dependencies like nlohmann/json, CLI11, and GoogleTest are fetched automatically.

# 1. Clone the repository
git clone https://github.com/your-username/cppfastmcp.git
cd cppfastmcp

# 2. Configure the project using CMake
# This will download dependencies and generate build files.
cmake -B build

# 3. Build the library, examples, and tests
cmake --build build -j $(nproc) # Use -j with the number of your CPU cores

The built executables for examples and tests will be located in the build/examples and build/tests directories, respectively.

Getting Started: A Simple Client

Here is a complete example of a client that connects to a local Python MCP server, lists its tools, and calls one of them.

First, ensure you have a simple MCP server available. You can use the simple_echo.py server from the official Python SDK examples/fastmcp directory.

examples/fastmcp/simple_echo.py

"""
FastMCP Echo Server
"""

from mcp.server.fastmcp import FastMCP

# Create server
mcp = FastMCP("Echo Server")


@mcp.tool()
def echo(text: str) -> str:
    """Echo the input text"""
    return text

Run this server using a Python environment where mcp is installed: python path/to/simple_echo.py.

Now, you can write the C++ client to connect to it.

examples/full_client.cpp

#include <iostream>
#include <boost/asio/co_spawn.hpp>
#include <boost/asio/io_context.hpp>
#include <boost/asio/signal_set.hpp>
#include <boost/asio/use_future.hpp>

#include "cppfastmcp/client_session.hpp"
#include "cppfastmcp/stdio_transport.hpp"
#include "cppfastmcp/protocol_types.hpp"

// Our main logic will run in this coroutine
boost::asio::awaitable<void> run_client(const std::string& server_script_path) {
    try {
        // 1. Create a transport to communicate with a local server
        // The transport will spawn the Python script as a child process.
        auto& executor = co_await boost::asio::this_coro::executor;
        StdioTransport transport(executor, "python", {server_script_path});

        // 2. Create a client session using the transport
        ClientSession session(std::move(transport));

        // 3. Perform the MCP initialization handshake
        std::cout << "Initializing session..." << std::endl;
        auto init_result = co_await session.async_initialize({
            .protocolVersion = "2025-06-18",
            .clientInfo = {"CppFastMCP Client", "0.1.0"}
        });
        std::cout << "Connected to server: " << init_result.serverInfo.name
                  << " v" << init_result.serverInfo.version << std::endl;

        // 4. List the tools available on the server
        std::cout << "\nListing available tools..." << std::endl;
        auto tools_result = co_await session.async_list_tools();
        for (const auto& tool : tools_result.tools) {
            std::cout << "- " << tool.name << ": " << (tool.description ? *tool.description : "No description") << std::endl;
        }

        // 5. Call a specific tool
        std::cout << "\nCalling 'echo' tool..." << std::endl;
        nlohmann::json args = {{"text", "Hello from C++!"}};
        auto call_result = co_await session.async_call_tool("echo", args);

        if (!call_result.isError && !call_result.content.empty()) {
            // The result is a variant, we need to check the type
            if (const auto* text_content = std::get_if<TextContent>(&call_result.content[0])) {
                std::cout << "Server response: " << text_content->text << std::endl;
            }
        } else {
            std::cerr << "Tool call failed or returned empty content." << std::endl;
        }

    } catch (const std::exception& e) {
        std::cerr << "An error occurred: " << e.what() << std::endl;
    }

    // Signal the io_context to stop
    (co_await boost::asio::this_coro::executor).context().stop();
}

int main(int argc, char* argv[]) {
    if (argc != 2) {
        std::cerr << "Usage: " << argv[0] << " <path_to_python_server_script>" << std::endl;
        return 1;
    }

    try {
        boost::asio::io_context io_context;

        // Run the client coroutine
        boost::asio::co_spawn(io_context, run_client(argv[1]), boost::asio::detached);

        // Run the Asio event loop
        io_context.run();

    } catch (const std::exception& e) {
        std::cerr << "Exception in main: " << e.what() << std::endl;
        return 1;
    }

    return 0;
}

Running the Example

1. Make sure you have built the project as described above.
2. Run the example client, passing the path to the Python server script.

# From the project root directory
./build/examples/full_client path/to/examples/fastmcp/simple_echo.py

You should see output similar to this:

Initializing session...
Connected to server: Echo Server v0.1.0

Listing available tools...
- echo: Echo the input text

Calling 'echo' tool...
Server response: Hello from C++!

Project Structure

• include/cppfastmcp/: Public headers for the library. This is what you include in your own projects.
• src/: Private implementation source files.
• tests/: Unit and integration tests for the library, built using GoogleTest.
• examples/: Standalone example applications demonstrating how to use the library.

Development & Testing

To run the library's test suite, build the project and then run ctest.

# From the build directory
cd build
ctest --verbose

Roadmap

This library is under active development. Key features planned for future releases include:

• Full implementation of the StreamableHttpTransport.
• OAuth 2.0 authentication support for the HTTP transport.
• Implementation of ClientSessionGroup for managing multiple server connections.
• Handling of server-initiated requests (sampling, elicitation).
• Comprehensive Doxygen API documentation.

Contributing

Contributions are welcome! Please feel free to open an issue to discuss a bug or feature, or submit a pull request. See CONTRIBUTING.md for more details.

License

This project is licensed under the MIT License. See the LICENSE file for details.