mcpcpp - C++ Model Context Protocol Library

A modern C++ implementation of the Model Context Protocol (MCP) for building AI-powered applications with external tool integration.

🚀 Features

✅ Full MCP Protocol Support - JSON-RPC 2.0 based protocol (v2024-11-05)
✅ Dual Transport - STDIO and SSE/HTTP modes
✅ Tools - Register C++ functions as AI-callable tools
✅ Resources - Serve data, configurations, and files
✅ Prompts - Provide reusable prompt templates
✅ Client Library - Connect to MCP servers from C++
✅ Dynamic Configuration - Load tools from JSON config files
✅ Header-Only Option - Easy integration
✅ Modern C++17 - Type-safe and efficient

📦 Quick Start

Installation

git clone https://github.com/nlpresearchai/mcpcpp.git
cd mcpcpp
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
sudo cmake --install .

Basic Usage

#include <cppmcp/mcp_server.hpp>

int main() {
    // Create server
    mcp::MCPServer server("my-server", "1.0.0");
    
    // Add a tool
    server.add_tool(
        "add",
        "Add two numbers",
        {
            {"type", "object"},
            {"properties", {
                {"a", {{"type", "number"}}},
                {"b", {{"type", "number"}}}
            }},
            {"required", {"a", "b"}}
        },
        [](const json& args) -> json {
            return {{"result", args["a"].get<double>() + args["b"].get<double>()}};
        }
    );
    
    // Run server (STDIO mode)
    server.run_stdio();
    
    return 0;
}

Using in Your Project

CMakeLists.txt:

find_package(cppmcp REQUIRED)

add_executable(my_server main.cpp)
target_link_libraries(my_server PRIVATE cppmcp::cppmcp)

📚 Documentation

Core Components

1. MCP Server (`mcp_server.hpp`)

Create servers that expose tools, resources, and prompts to AI applications.

mcp::MCPServer server("server-name", "1.0.0");

// Add tool
server.add_tool("tool_name", "description", input_schema, 
    [](const json& args) { return result; });

// Add resource
server.add_resource("uri://resource", "name", "description", "mime-type",
    []() { return "data"; });

// Add prompt
server.add_prompt("prompt_name", "description", arguments,
    [](const json& args) { return prompt; });

// Run
server.run_stdio();  // or server.run_sse(port);

2. MCP Client (`mcp_client.hpp`)

Connect to MCP servers and call tools.

mcp::MCPClient client("client-name", "1.0.0");

// Connect
client.connect_sse("http://localhost:8080");
client.initialize();

// List and call tools
auto tools = client.list_tools();
auto result = client.call_tool("add", {{"a", 5}, {"b", 3}});

// Read resources
auto resources = client.list_resources();
auto data = client.read_resource("config://app");

3. Dynamic Server (`dynamic_mcp_server.hpp`)

Load server configuration from JSON files.

#include <cppmcp/dynamic_mcp_server.hpp>

dynamic_mcp::ConfigLoader loader("tasks_config.json");
loader.load();

// Server is automatically configured from JSON

📖 Examples

See the examples/ directory:

simple_server.cpp - Minimal MCP server
server_with_tools.cpp - Server with multiple tools, resources, and prompts
dynamic_server.cpp - Configuration-driven server
client_example.cpp - MCP client usage

Building Examples

cd build
cmake .. -DCPPMCP_BUILD_EXAMPLES=ON
cmake --build .
./examples/simple_server stdio
./examples/server_with_tools sse 8080

🏗️ Project Structure

mcpcpp/
├── include/cppmcp/          # Public headers
│   ├── mcp_server.hpp       # Server API
│   ├── mcp_client.hpp       # Client API
│   └── dynamic_mcp_server.hpp  # Dynamic configuration
├── src/                     # Implementation
│   ├── mcp_server.cpp
│   ├── mcp_sse.cpp
│   ├── mcp_client.cpp
│   └── dynamic_mcp_server.cpp
├── examples/                # Usage examples
├── tests/                   # Unit tests
├── docs/                    # Documentation
└── CMakeLists.txt          # Build configuration

🛠️ Building

Requirements

C++17 compiler (GCC 7+, Clang 5+, MSVC 2017+)
CMake 3.14+
libcurl (for HTTP/SSE support)

Dependencies (auto-fetched by CMake):

nlohmann/json - JSON parsing
cpp-httplib - HTTP server

CMake Options

-DCPPMCP_BUILD_EXAMPLES=ON   # Build examples (default: ON)
-DCPPMCP_BUILD_TESTS=ON      # Build tests (default: ON)
-DCPPMCP_BUILD_SHARED=ON     # Build shared library (default: ON)
-DCPPMCP_BUILD_STATIC=ON     # Build static library (default: ON)

Ubuntu/Debian

sudo apt-get install build-essential cmake libcurl4-openssl-dev

macOS

brew install cmake curl

🧪 Testing

cd build
cmake .. -DCPPMCP_BUILD_TESTS=ON
cmake --build .
ctest

🔌 Integration with AI Clients

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cppmcp-example": {
      "command": "/path/to/build/examples/simple_server",
      "args": ["stdio"]
    }
  }
}

Custom Python Client

import httpx
import json

# Connect to SSE server
response = httpx.post(
    "http://localhost:8080/message",
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
            "protocolVersion": "2024-11-05",
            "capabilities": {},
            "clientInfo": {"name": "python-client", "version": "1.0"}
        }
    }
)
print(response.json())

📊 Performance

Low Latency - Direct C++ execution, no Python overhead
High Throughput - Handles thousands of requests per second
Memory Efficient - Minimal allocations, optimized data structures
Async Ready - Non-blocking SSE connections

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🔗 Related Projects

Model Context Protocol - Official MCP specification
mcp Python SDK - Official Python implementation
mcp TypeScript SDK - Official TypeScript implementation

📬 Contact

Issues: GitHub Issues
Discussions: GitHub Discussions

⭐ Star History

If you find this project helpful, please consider giving it a star!

Built with ❤️ for the AI and C++ communities

mcpcpp