Skip to content

0xeb/fastmcpp

BranchesTags

Repository files navigation

fastmcpp logo

High-performance C++ implementation of the Model Context Protocol (MCP)

CI License

fastmcpp is a C++ port of the Python fastmcp library, providing native performance for MCP servers and clients with support for tools, resources, prompts, and multiple transport layers (STDIO, HTTP/SSE, WebSocket).

Status: Beta – core MCP features track the Python fastmcp reference.

Current version: 2.15.0

Features

  • Core MCP protocol implementation (JSON‑RPC).
  • Multiple transports: STDIO, HTTP (SSE), Streamable HTTP, WebSocket.
  • Streamable HTTP transport (MCP spec 2025-03-26) with session management.
  • Tool management and invocation.
  • Resources and prompts support.
  • Resource templates with URI pattern matching.
  • Resource annotations (MCP 2025-11-25): audience targeting, priority hints, icons.
  • JSON Schema validation.
  • FastMCP high-level application class.
  • ProxyApp for backend server proxying.
  • Providers system for modular tool/resource composition.
  • Provider transforms: namespace prefixing, visibility filtering, tool wrapping.
  • ServerSession for bidirectional communication, sampling, and server-initiated notifications.
  • Built-in middleware: Logging, Timing, Caching, RateLimiting, ErrorHandling.
  • Tool transforms for input/output processing.
  • Integration with MCP‑compatible CLI tools.
  • Cross‑platform: Windows, Linux, macOS.

Requirements

  • C++17 or later compiler.
  • CMake 3.20 or higher.
  • nlohmann/json (fetched automatically).

Optional:

  • libcurl (for HTTP POST streaming; can be fetched when FASTMCPP_FETCH_CURL=ON).
  • cpp‑httplib (HTTP server, fetched automatically).
  • easywsclient (WebSocket client, fetched automatically).

Building

Basic build

git clone https://github.com/0xeb/fastmcpp.git
cd fastmcpp

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j

Recommended configuration options

cmake -B build -S . \
  -DCMAKE_BUILD_TYPE=Release \
  -DFASTMCPP_ENABLE_POST_STREAMING=ON \
  -DFASTMCPP_FETCH_CURL=ON \
  -DFASTMCPP_ENABLE_STREAMING_TESTS=ON \
  -DFASTMCPP_ENABLE_WS_STREAMING_TESTS=ON

Key options:

Option Default Description
CMAKE_BUILD_TYPE Debug Build configuration (Debug/Release/RelWithDebInfo)
FASTMCPP_ENABLE_POST_STREAMING OFF Enable HTTP POST streaming (requires libcurl)
FASTMCPP_FETCH_CURL OFF Fetch and build curl (via FetchContent) if not found
FASTMCPP_ENABLE_STREAMING_TESTS OFF Enable SSE streaming tests
FASTMCPP_ENABLE_WS_STREAMING_TESTS OFF Enable WebSocket streaming tests

Platform notes

Windows (Visual Studio):

cmake -B build -S . -G "Visual Studio 17 2022"
cmake --build build --config Release

Linux/macOS:

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"

Testing

# Run all tests
ctest --test-dir build -C Release --output-on-failure

# Parallel
ctest --test-dir build -C Release -j4 --output-on-failure

# Run a specific test
ctest --test-dir build -C Release -R fastmcp_smoke --output-on-failure

# List tests
ctest --test-dir build -C Release -N

Basic Usage

STDIO MCP server

#include <fastmcpp/tools/manager.hpp>
#include <fastmcpp/mcp/handler.hpp>
#include <fastmcpp/server/stdio_server.hpp>

int main() {
    fastmcpp::tools::ToolManager tm;
    // register tools on tm...

    auto handler = fastmcpp::mcp::make_mcp_handler(
        "myserver", "1.0.0", tm
    );

    fastmcpp::server::StdioServerWrapper server(handler);
    server.run();  // blocking
    return 0;
}

HTTP server

#include <fastmcpp/server/server.hpp>
#include <fastmcpp/server/http_server.hpp>

int main() {
    auto srv = std::make_shared<fastmcpp::server::Server>();
    srv->register_get("/health", [](const nlohmann::json&) {
        return nlohmann::json{{"status", "ok"}};
    });

    fastmcpp::server::HttpServerWrapper http(srv, "127.0.0.1", 8080);
    http.start();  // non‑blocking

    std::this_thread::sleep_for(std::chrono::hours(1));
    http.stop();
    return 0;
}

HTTP client

#include <fastmcpp/client/client.hpp>
#include <fastmcpp/client/transports.hpp>

int main() {
    // Create client with HTTP transport
    fastmcpp::client::Client client(
        std::make_unique<fastmcpp::client::HttpTransport>("http://localhost:8080")
    );

    // Initialize MCP session
    auto init = client.initialize();
    std::cout << "Connected to: " << init.serverInfo.name << std::endl;

    // List available tools
    auto tools = client.list_tools();
    for (const auto& tool : tools) {
        std::cout << "Tool: " << tool.name << std::endl;
    }

    // Call a tool
    auto result = client.call_tool("calculator", {{"a", 5}, {"b", 3}});
    std::cout << "Result: " << result.text() << std::endl;

    return 0;
}

Streamable HTTP server (MCP spec 2025-03-26)

#include <fastmcpp/tools/manager.hpp>
#include <fastmcpp/mcp/handler.hpp>
#include <fastmcpp/server/streamable_http_server.hpp>

int main() {
    fastmcpp::tools::ToolManager tm;
    // register tools on tm...

    auto handler = fastmcpp::mcp::make_mcp_handler(
        "myserver", "1.0.0", tm
    );

    // Streamable HTTP server on /mcp endpoint
    fastmcpp::server::StreamableHttpServerWrapper server(
        handler, "127.0.0.1", 8080, "/mcp"
    );
    server.start();  // non-blocking

    std::this_thread::sleep_for(std::chrono::hours(1));
    server.stop();
    return 0;
}

Streamable HTTP client

#include <fastmcpp/client/client.hpp>
#include <fastmcpp/client/transports.hpp>

int main() {
    // Create client with Streamable HTTP transport (MCP spec 2025-03-26)
    fastmcpp::client::Client client(
        std::make_unique<fastmcpp::client::StreamableHttpTransport>(
            "http://localhost:8080", "/mcp"
        )
    );

    // Initialize MCP session (session ID managed automatically)
    auto init = client.initialize();
    std::cout << "Server: " << init.serverInfo.name << std::endl;

    // Use the same clean API as other transports
    auto tools = client.list_tools();
    auto result = client.call_tool("echo", {{"message", "Hello!"}});

    return 0;
}

Proxy server

Create a proxy that forwards requests to a backend MCP server while allowing local overrides:

#include <fastmcpp/proxy.hpp>
#include <fastmcpp/server/sse_server.hpp>
#include <fastmcpp/util/schema_build.hpp>

int main() {
    using fastmcpp::util::schema_build::to_object_schema_from_simple;

    // Create a proxy to a remote backend
    auto proxy = fastmcpp::create_proxy("http://backend:8080/mcp");

    // Add local tools that extend or override remote capabilities
    proxy.local_tools().register_tool({
        "double",
        to_object_schema_from_simple({{"n", "number"}}),  // input: {n: number}
        {{"type", "number"}},                             // output schema
        [](const fastmcpp::Json& args) { return args["n"].get<int>() * 2; }
    });

    // Create MCP handler and serve via SSE
    auto handler = fastmcpp::mcp::make_mcp_handler(proxy);
    fastmcpp::server::SseServerWrapper server(handler, "127.0.0.1", 8080);
    server.start();

    // Server runs until stopped...
    return 0;
}

The create_proxy() factory function automatically detects the transport type from the URL:

  • http:// or https:// URLs use HTTP transport
  • ws:// or wss:// URLs use WebSocket transport

Local tools, resources, and prompts take precedence over remote ones with the same name.

Providers

Providers enable modular composition of tools and resources with automatic transforms:

#include <fastmcpp/providers/filesystem_provider.hpp>
#include <fastmcpp/providers/local_provider.hpp>

int main() {
    using namespace fastmcpp::providers;

    // Create a filesystem provider that exposes directory contents
    FilesystemProvider fs_provider("./data", {
        .allowed_extensions = {".txt", ".json", ".md"},
        .max_file_size = 1024 * 1024  // 1MB
    });

    // Create a local provider with custom tools
    LocalProvider local;
    local.add_tool("greet", /*...*/);

    // Apply namespace transform to prefix all tool names
    auto namespaced = apply_transform<NamespaceTransform>(local, "myapp");
    // Tools now: myapp_greet, etc.

    auto handler = fastmcpp::mcp::make_mcp_handler(namespaced);
    // ...
}

Provider Transforms:

Transform Description
NamespaceTransform Prefix tool/resource names (e.g., math_add)
VisibilityTransform Filter which tools/resources are exposed
ToolTransform Wrap tool inputs/outputs for preprocessing

Resource Annotations (MCP 2025-11-25)

Resources can include metadata hints for clients:

fastmcpp::resources::ResourceDefinition res;
res.uri = "config://settings";
res.name = "Application Settings";
res.mime_type = "application/json";
res.annotations = Json{
    {"audience", Json::array({"user", "assistant"})},
    {"priority", 0.8}
};
res.icons = {{"icon.png", "image/png"}};
res.provider = [](const Json&) {
    return ResourceContent{"config://settings", "application/json",
                           R"({"theme": "dark"})"};
};

Annotations help clients:

  • audience: Who should see this resource (user, assistant, or both)
  • priority: Relative importance (0.0–1.0) for display ordering
  • icons: Visual indicators for UI rendering

Examples

See the examples/ directory for complete programs, including:

  • stdio_server.cpp – STDIO MCP server.
  • server_quickstart.cpp – HTTP server with routes.
  • client_quickstart.cpp – HTTP client usage.
  • tool_example.cpp – tool registration and invocation.
  • middleware_example.cpp – request/response middleware.

Project Structure

fastmcpp/
  include/fastmcpp/   # Public headers (client, server, tools, etc.)
  src/                # Implementation
  tests/              # Test suite (GoogleTest)
  examples/           # Example programs
  CMakeLists.txt      # Build configuration
  LICENSE             # Apache 2.0 license
  NOTICE              # Attribution notices
  README.md           # This file

Projects Using This Library

Project Description
copilot-sdk-cpp C++ SDK for GitHub Copilot CLI
claude-agent-sdk-cpp C++ SDK for Claude Code CLI with MCP support

Want to add your project? Open a PR!

Contributing

Contributions are welcome. Please:

  1. Ensure all tests pass.
  2. Follow the existing code style.
  3. Add tests for new features.
  4. Update documentation as needed.

Author

Elias Bachaalany (@0xeb)

Pair-programmed with Claude Code and Codex.

License

Copyright 2025 Elias Bachaalany

Licensed under the Apache License 2.0. See LICENSE and NOTICE for details.

This is a C++ port of fastmcp by Jeremiah Lowin. The Python library is the canonical implementation; fastmcpp aims to match its behavior for core features.

Support

For issues and questions, use the GitHub issue tracker: https://github.com/0xeb/fastmcpp/issues.

About

C++ port of the fastmcp Python library

Resources

Readme

License

Apache-2.0 license
Activity

Stars

93 stars

Watchers

4 watching

Forks

6 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages