Migration Guide

# Move to cxxmcp from other MCP SDKs.

API mapping tables and side-by-side examples for migrating from the TypeScript, Python, and Rust 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

TypeScript | cxxmcp
--- | ---
`new McpServer({name, version})` | `ServerPeer::builder().name(n).version(v)`
`server.tool(name, desc, handler)` | `.tool<In, Out>(name, handler)`
`server.resource(name, uri, handler)` | `.resource(uri, handler)`
`server.prompt(name, handler)` | `.prompt(Prompt{...}, handler)`
`StdioServerTransport` | `.stdio()`
`StreamableHTTPServerTransport` | `.streamable_http(host, port, path)`

### 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

Python | cxxmcp
--- | ---
`Server("name")` | `ServerPeer::builder().name("name")`
`@server.tool()` | `.tool<In, Out>(name, handler)`
`@server.resource(uri)` | `.resource(uri, handler)`
`@server.prompt()` | `.prompt(Prompt{...}, handler)`
`stdio_server()` | `.stdio()`

### 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

RMCP | cxxmcp
--- | ---
`ServerHandler` trait | `ServerPeer::builder()` with registered handlers
`#[tool]` attribute macro | `.tool<In, Out>(name, handler)`
`serve_server()` | `mcp::serve(peer)`
`axum` / `tower` | built-in `cpp-httplib`
`tokio` runtime | no runtime dependency

### 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