Move to cxxmcp from other MCP SDKs.

From TypeScript SDK

The TypeScript SDK uses a class-based Server with callback registration. cxxmcp uses a builder pattern with ServerPeer::builder().

Server Setup

Side-by-Side: Echo Server

// TypeScript
import { McpServer } from "@modelcontextprotocol/sdk/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";

const server = new McpServer({ name: "echo", version: "1.0.0" });
server.tool("echo", { input: { type: "object" } }, async ({ input }) => ({
    content: [{ type: "text", text: JSON.stringify(input) }],
}));
const transport = new StdioServerTransport();
await server.connect(transport);

// cxxmcp
#include <cxxmcp/peer.hpp>
#include <cxxmcp/run.hpp>

int main() {
    return mcp::ServerPeer::builder()
        .name("echo").version("1.0.0").stdio()
        .tool<Json, Json>("echo",
            [](const Json& input) { return input; })
        .run();
}

Key Differences

• Async: TS uses async/await; cxxmcp uses synchronous handlers by default, with task-aware async support
• Types: TS uses JSON schema objects; cxxmcp uses CXXMCP_REFLECT for typed DTOs
• Transport: TS requires manual transport construction; cxxmcp uses builder methods
• Error handling: TS throws exceptions; cxxmcp returns Result<T>

From Python SDK

Server Setup

Side-by-Side: Echo Server

# Python
from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("echo")

@server.tool()
async def echo(input: dict) -> dict:
    return input

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write)

// cxxmcp
#include <cxxmcp/peer.hpp>
#include <cxxmcp/run.hpp>

int main() {
    return mcp::ServerPeer::builder()
        .name("echo").version("1.0.0").stdio()
        .tool<Json, Json>("echo",
            [](const Json& input) { return input; })
        .run();
}

Key Differences

• Decorators vs builder: Python uses @server.tool() decorators; cxxmcp uses method chaining on a builder
• Async: Python is async-first; cxxmcp is synchronous-first with optional async tasks
• Types: Python uses type hints; cxxmcp uses compile-time CXXMCP_REFLECT
• Deployment: Python needs a runtime; cxxmcp compiles to a native binary

From Rust SDK (RMCP)

Architecture Mapping

Key Differences

• Concurrency: RMCP uses tokio async; cxxmcp uses threads and task managers
• Macros: RMCP uses proc macros (#[tool]); cxxmcp uses CXXMCP_REFLECT for DTOs
• Memory: RMCP uses Rust ownership; cxxmcp uses std::unique_ptr and move semantics
• Conformance: cxxmcp scores 109/110 server, 448/448 client; RMCP scores 48/95 server

Upgrading cxxmcp Versions

v1.0.0 to v1.1.0

• HTTP transport now requires CXXMCP_ENABLE_HTTP=ON (was always-on before)
• Add -DCXXMCP_ENABLE_HTTP=ON to your CMake command if you use HTTP
• No API changes — only build configuration

v1.1.0 to v1.1.1

• SSE retry/reconnection in client HTTP transport
• No breaking changes — drop-in upgrade

General Upgrade Rule

cxxmcp follows SemVer. Patch versions (1.1.0 → 1.1.1) are always backward-compatible. Minor versions (1.0.x → 1.1.0) add features without breaking existing code. See Stability for the full policy.

Next Steps

• Tutorials — build your first server
• Concepts — understand the architecture
• Cookbook — common code patterns