Skip to content
BranchesTags

Repository files navigation

fastmcpp logo

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

CILicense

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 MCP-standard transport layers (STDIO, HTTP/SSE, Streamable HTTP).

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

Current version: 3.4.4

Features

  • Core MCP protocol implementation (JSON‑RPC).
  • Multiple transports: STDIO, HTTP (SSE), Streamable HTTP.
  • 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).

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

Key options:

OptionDefaultDescription
CMAKE_BUILD_TYPEDebugBuild configuration (Debug/Release/RelWithDebInfo)
FASTMCPP_ENABLE_POST_STREAMINGOFFEnable HTTP POST streaming (requires libcurl)
FASTMCPP_FETCH_CURLOFFFetch and build curl (via FetchContent) if not found
FASTMCPP_ENABLE_STREAMING_TESTSOFFEnable SSE 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>intmain() {
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(); // blockingreturn0;
}

HTTP server

#include<fastmcpp/server/server.hpp>
#include<fastmcpp/server/http_server.hpp>intmain() {
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‑blockingstd::this_thread::sleep_for(std::chrono::hours(1));
http.stop();
return0;
}

HTTP client

#include<fastmcpp/client/client.hpp>
#include<fastmcpp/client/transports.hpp>intmain() {
// Create client with HTTP transport
fastmcpp::client::Client client(
std::make_unique<fastmcpp::client::HttpTransport>("http://localhost:8080")
);
// Initialize MCP sessionauto init = client.initialize();
std::cout << "Connected to: " << init.serverInfo.name << std::endl;
// List available toolsauto tools = client.list_tools();
for (constauto& tool : tools) {
std::cout << "Tool: " << tool.name << std::endl;
}
// Call a toolauto result = client.call_tool("calculator", {{"a", 5}, {"b", 3}});
std::cout << "Result: " << result.text() << std::endl;
return0;
}

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>intmain() {
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-blockingstd::this_thread::sleep_for(std::chrono::hours(1));
server.stop();
return0;
}

Streamable HTTP client

#include<fastmcpp/client/client.hpp>
#include<fastmcpp/client/transports.hpp>intmain() {
// 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 transportsauto tools = client.list_tools();
auto result = client.call_tool("echo", {{"message", "Hello!"}});
return0;
}

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>intmain() {
using fastmcpp::util::schema_build::to_object_schema_from_simple;
// Create a proxy to a remote backendauto 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 SSEauto handler = fastmcpp::mcp::make_mcp_handler(proxy);
fastmcpp::server::SseServerWrapper server(handler, "127.0.0.1", 8080);
server.start();
// Server runs until stopped...return0;
}

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

  • http:// or https:// URLs use HTTP 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>intmain() {
usingnamespacefastmcpp::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 namesauto namespaced = apply_transform<NamespaceTransform>(local, "myapp");
// Tools now: myapp_greet, etc.auto handler = fastmcpp::mcp::make_mcp_handler(namespaced);
// ...
}

Provider Transforms:

TransformDescription
NamespaceTransformPrefix tool/resource names (e.g., math_add)
VisibilityTransformFilter which tools/resources are exposed
ToolTransformWrap 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

ProjectDescription
copilot-sdk-cppC++ SDK for GitHub Copilot CLI
claude-agent-sdk-cppC++ 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
Apache-2.0 license
Activity

Stars

130 stars

Watchers

5 watching

Forks

17 forks
Report repository

Releases

Packages

Contributors

Languages