Crate tmcp 

tmcp

A complete Rust implementation of the Model Context Protocol (MCP), providing both client and server capabilities for building AI-integrated applications.

Overview

tmcp offers an ergonomic API for implementing MCP servers and clients with support for tools, resources, and prompts. The library uses async/await patterns with Tokio and provides procedural macros to eliminate boilerplate.

Features

• Derive Macros: Simple #[mcp_server] attribute for automatic implementation
• Multiple Transports: TCP, HTTP (with SSE), and stdio support
• Type Safety: Strongly typed protocol messages with serde
• Async-First: Built on Tokio for high-performance async I/O

Transport Options

• TCP: server.listen_tcp("127.0.0.1:3000")
• HTTP: server.listen_http("127.0.0.1:3000") (uses SSE for server->client)
• Stdio: server.listen_stdio() for subprocess integration

Building Servers: Macro vs Trait

tmcp provides two approaches for implementing MCP servers:

The #[mcp_server] Macro

Best for simple servers that primarily expose tools. The macro automatically:

• Generates ServerHandler trait implementation
• Derives tool schemas from function signatures using schemars
• Registers tools in list_tools and routes calls in call_tool
• Provides sensible defaults for initialize

use schemars::JsonSchema;
use serde::Deserialize;
use tmcp::{mcp_server, schema::CallToolResult, tool, ServerCtx, ToolResult};

#[derive(Debug, Deserialize, JsonSchema)]
struct GreetParams {
    name: String,
}

#[mcp_server]
impl MyServer {
    #[tool]
    async fn greet(&self, _ctx: &ServerCtx, params: GreetParams) -> ToolResult {
        Ok(CallToolResult::new().with_text_content(format!(
            "Hello, {}!",
            params.name
        )))
    }
}

The ServerHandler Trait

Use the trait directly when you need:

• Custom initialization: Validate clients, negotiate capabilities, or reject connections
• Per-connection state: Access to ServerCtx in all methods for client-specific data
• Resources and prompts: Full access to MCP features beyond tools
• Fine-grained error handling: Custom error responses and logging

use tmcp::{ServerHandler, ServerCtx, Result};
use async_trait::async_trait;

struct MyServer;

#[async_trait]
impl ServerHandler for MyServer {
    async fn initialize(&self, ctx: &ServerCtx, ...) -> Result<InitializeResult> {
        // Custom capability negotiation
    }

    async fn list_tools(&self, ctx: &ServerCtx, ...) -> Result<ListToolsResult> {
        // Dynamic tool registration
    }
}

See ServerHandler documentation for the default behavior philosophy.

Re-exports

pub use schema::ToolResponse;

Modules

auth

OAuth Authentication Module for MCP

schema

Public schema types for MCP messages. MCP protocol schema types.

testutils

Test utilities for tmcp.

Structs

Arguments

Generic argument map used for passing parameters to tools and prompts.

Client

MCP Client implementation

ClientCtx

Context provided to ClientHandler implementations for interacting with the server

Server

MCP Server implementation

ServerCtx

Context provided to ServerHandler implementations for interacting with clients

ServerHandle

Handle for controlling a running MCP server instance

SpawnedServer

Handle to an MCP server spawned as a subprocess.

TcpServerHandle

Handle for controlling a running TCP MCP server

ToolError

Error type for tool calls that should be surfaced as tool results.

Enums

Error

Error type for MCP operations.

Constants

TOOL_ERROR_INTERNAL

Standard error code for internal errors.

TOOL_ERROR_INVALID_INPUT

Standard error code for invalid input parameters.

TOOL_ERROR_NOT_FOUND

Standard error code for resource not found.

TOOL_ERROR_TIMEOUT

Standard error code for operation timeout.

Traits

ClientHandler

Handler trait that client implementers must implement.

ServerHandler

Handler trait for implementing MCP servers.

Type Aliases

Result

Result alias using the crate error type.

ToolResult

Result alias for tool calls that return structured tool errors.

Attribute Macros

mcp_server

Derive the ServerHandler methods from an impl block.

tool

Mark a method as an mcp tool.

tool_params

Add serde + schemars derives for tool parameter structs.

tool_result

Add serde + schemars derives plus ToolResponse for tool result structs.

Derive Macros

ToolResponse

Derive ToolResponse by encoding the type as structured content.