Model Context Protocol (MCP) is an open protocol that provides a standardized way for AI models and agents to interact with various resources, tools, and services. This framework implements the core functionality of the MCP protocol, conforming to the 2024-11-05 basic protocol specification.
- JSON-RPC 2.0 Communication: Request/response communication based on JSON-RPC 2.0 standard
- Resource Abstraction: Standard interfaces for resources such as files, APIs, etc.
- Tool Registration: Register and call tools with structured parameters
- Extensible Architecture: Easy to extend with new resource types and tools
- Multi-Transport Support: Supports HTTP and standard input/output (stdio) communication methods
Example of building with CMake:
cmake -B build
cmake --build build --config ReleaseBuild with tests:
git submodule update --init --recursive # Get GoogleTest
cmake -B build -DMCP_BUILD_TESTS=ON
cmake --build build --config Release
Build with SSL support:
git submodule update --init --recursive # Get GoogleTest
cmake -B build -DMCP_SSL=ON
cmake --build build --config Release
Here are some open-source projects that are using this repository.
If you're using it too, feel free to submit a PR to be featured here!
- humanus.cpp: Lightweight C++ LLM agent framework
- ...waiting for your contribution...
The MCP C++ library includes the following main components:
Defines the abstract interface for MCP clients, which all concrete client implementations inherit from.
Client implementation that communicates with MCP servers using HTTP and Server-Sent Events (SSE).
Client implementation that communicates with MCP servers using standard input/output, capable of launching subprocesses and communicating with them.
Handles serialization and deserialization of JSON-RPC messages.
Manages and invokes MCP tools.
Manages MCP resources.
Implements MCP server functionality.
Example MCP server implementation with custom tools:
- Time tool: Get the current time
- Calculator tool: Perform mathematical operations
- Echo tool: Echo input with optional transformations (to uppercase, reverse)
- Greeting tool: Returns
Hello,+ input name +!, defaults toHello, World!
Example MCP client connecting to a server:
- Get server information
- List available tools
- Call tools with parameters
- Access resources
Demonstrates how to use the stdio client to communicate with a local server:
- Launch a local server process
- Access filesystem resources
- Call server tools
| Option | Description |
|---|---|
--base-url |
LLM base URL (e.g. https://openrouter.ai) |
--endpoint |
LLM endpoint (default to /v1/chat/completions/) |
--api-key |
LLM API key |
--model |
Model name (e.g. gpt-3.5-turbo) |
--system-prompt |
System prompt |
--max-tokens |
Maximum number of tokens to generate (default to 2048) |
--temperature |
Temperature (default to 0.0) |
--max-steps |
Maximum steps calling tools without user input (default to 3) |
Example usage:
./build/examples/agent_example --base-url <base_url> --endpoint <endpoint> --api-key <api_key> --model <model_name>
Note: Remember to compile with -DMCP_SSL=ON when connecting to an https base URL.
// Create and configure the server
mcp::server server("localhost", 8080); // Host and port
server.set_server_info("MCP Example Server", "0.1.0"); // Name and version
// Register tools
mcp::json hello_handler(const mcp::json& params, const std::string /* session_id */) {
std::string name = params.contains("name") ? params["name"].get<std::string>() : "World";
// Server will catch exceptions and return error contents
// For example, you can use `throw mcp::mcp_exception(mcp::error_code::invalid_params, "Invalid name");` to report an error
// Content should be a JSON array, see: https://modelcontextprotocol.io/specification/2024-11-05/server/tools#tool-result
return {
{
{"type", "text"},
{"text", "Hello, " + name + "!"}
}
};
}
mcp::tool hello_tool = mcp::tool_builder("hello")
.with_description("Say hello")
.with_string_param("name", "Name to say hello to", "World")
.build();
server.register_tool(hello_tool, hello_handler);
// Register resources
auto file_resource = std::make_shared<mcp::file_resource>("<file_path>");
server.register_resource("file://<file_path>", file_resource);
// Start the server
server.start(true); // Blocking mode// Connect to the server
mcp::sse_client client("localhost", 8080);
// Initialize the connection
client.initialize("My Client", "1.0.0");
// Call a tool
mcp::json params = {
{"name", "Client"}
};
mcp::json result = client.call_tool("hello", params);The SSE client uses HTTP and Server-Sent Events (SSE) to communicate with MCP servers. This is a communication method based on Web standards, suitable for communicating with servers that support HTTP/SSE.
#include "mcp_sse_client.h"
// Create a client, specifying the server address and port
mcp::sse_client client("localhost", 8080);
// Or use a base URL
// mcp::sse_client client("http://localhost:8080");
// Set an authentication token (if needed)
client.set_auth_token("your_auth_token");
// Set custom request headers (if needed)
client.set_header("X-Custom-Header", "value");
// Initialize the client
if (!client.initialize("My Client", "1.0.0")) {
// Handle initialization failure
}
// Call a tool
json result = client.call_tool("tool_name", {
{"param1", "value1"},
{"param2", 42}
});The Stdio client can communicate with any MCP server that supports stdio transport, such as:
- @modelcontextprotocol/server-everything - Example server
- @modelcontextprotocol/server-filesystem - Filesystem server
- Other MCP servers that support stdio transport
#include "mcp_stdio_client.h"
// Create a client, specifying the server command
mcp::stdio_client client("npx -y @modelcontextprotocol/server-everything");
// mcp::stdio_client client("npx -y @modelcontextprotocol/server-filesystem /path/to/directory");
// Initialize the client
if (!client.initialize("My Client", "1.0.0")) {
// Handle initialization failure
}
// Access resources
json resources = client.list_resources();
json content = client.read_resource("resource://uri");
// Call a tool
json result = client.call_tool("tool_name", {
{"param1", "value1"},
{"param2", "value2"}
});This framework is provided under the MIT license. For details, please see the LICENSE file.