Crate turul_http_mcp_server

Expand description

§HTTP MCP Server

Production HTTP transport layer for Model Context Protocol (MCP) servers.

Provides both modern Streamable HTTP and legacy HTTP+SSE transports with automatic protocol detection, CORS support, and session management for maximum compatibility.

§Installation

[dependencies]
turul-http-mcp-server = "0.3"
turul-mcp-server = "0.3"

§Supported Transports

Streamable HTTP: Recommended for production deployments
HTTP+SSE: Legacy transport for backwards compatibility

§Features

Automatic protocol version detection and routing
CORS support for browser-based clients
Session management with cryptographically secure IDs
Graceful error handling and JSON-RPC 2.0 compliance

§Quick Start

use turul_http_mcp_server::HttpMcpServerBuilder;
use std::net::SocketAddr;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let addr: SocketAddr = "127.0.0.1:8080".parse()?;
    let server = HttpMcpServerBuilder::new()
        .bind_address(addr)
        .cors(true)
        .build();

    println!("Server running on http://127.0.0.1:8080/mcp");
    server.run().await?;
    Ok(())
}

Re-exports§

pub use cors::CorsLayer;
pub use notification_bridge::BroadcastError;
pub use notification_bridge::NotificationBroadcaster;
pub use notification_bridge::SharedNotificationBroadcaster;
pub use notification_bridge::StreamManagerNotificationBroadcaster;
pub use protocol::McpProtocolVersion;
pub use protocol::extract_last_event_id;
pub use protocol::extract_protocol_version;
pub use protocol::extract_session_id;
pub use routes::RouteBody;
pub use routes::RouteHandler;
pub use routes::RouteRegistry;
pub use routes::RouteValidationError;
pub use server::HttpMcpServer;
pub use server::HttpMcpServerBuilder;
pub use server::ServerConfig;
pub use server::ServerStats;
pub use session_handler::SessionMcpHandler;
pub use session_handler::SessionSseStream;
pub use stream_manager::StreamConfig;
pub use stream_manager::StreamError;
pub use stream_manager::StreamManager;
pub use stream_manager::StreamStats;
pub use streamable_http::StreamableHttpContext;
pub use streamable_http::StreamableHttpHandler;

Modules§

completion: Core MCP protocol types and error handling MCP Completion Protocol Types
content: Core MCP protocol types and error handling Content types for MCP 2025-11-25 specification
cors: CORS (Cross-Origin Resource Sharing) support
elicitation: Core MCP protocol types and error handling MCP Elicitation Protocol Types
handler: SSE stream body utilities for MCP protocol
icons: Core MCP protocol types and error handling MCP Icon Types
initialize: Core MCP protocol types and error handling MCP Initialize Protocol Types
json_rpc: Core MCP protocol types and error handling JSON-RPC 2.0 Implementation for MCP 2025-11-25
json_rpc_responses: JSON-RPC 2.0 response builders for HTTP transport
logging: Core MCP protocol types and error handling MCP Logging Protocol Types
mcp_session: Streamable HTTP session management for MCP transport
meta: Core MCP protocol types and error handling _meta Field Support for MCP 2025-11-25
middleware: Middleware system for MCP servers
notification_bridge: Notification Bridge - Connects NotificationBroadcaster to StreamManager
notifications: Core MCP protocol types and error handling MCP Notifications Protocol Types
param_extraction: Core MCP protocol types and error handling Parameter extraction utilities for MCP protocol
ping: Core MCP protocol types and error handling MCP Ping Protocol Types
prelude: HTTP MCP Server Prelude
prompts: Core MCP protocol types and error handling MCP Prompts Protocol Types
protocol: MCP Protocol Version Detection and Features
resources: Core MCP protocol types and error handling MCP Resources Protocol Types
roots: Core MCP protocol types and error handling MCP Roots Protocol Types
routes: Route registry for custom HTTP paths (e.g., .well-known endpoints)
sampling: Core MCP protocol types and error handling MCP Sampling Protocol Types
schema: Core MCP protocol types and error handling JSON Schema Support for MCP
server: HTTP MCP Server with SessionStorage integration
session_handler: JSON-RPC 2.0 over HTTP handler for MCP requests with SessionStorage integration
sse: Server-Sent Events (SSE) support for MCP
stream_manager: Enhanced Stream Manager with MCP 2025-11-25 Resumability
streamable_http: Streamable HTTP Transport for MCP 2025-11-25
tasks: Core MCP protocol types and error handling MCP Tasks Protocol Types
tools: Core MCP protocol types and error handling MCP Tools Protocol Types
traits: Core MCP protocol types and error handling Traits for JSON-RPC types as per MCP specification (2025-11-25)
version: Core MCP protocol types and error handling MCP Protocol Version Support

Macros§

impl_serde_extractor: Core MCP protocol types and error handling Macro to implement SerdeParamExtractor for any Params type that implements Deserialize

Structs§

Annotations: Core MCP protocol types and error handling Annotations for resources, prompts, and tools (matches TypeScript Annotations per MCP 2025-11-25). See MCP spec
BlobResourceContents: Core MCP protocol types and error handling Binary resource contents (matches TypeScript BlobResourceContents exactly)
CallToolRequest: Core MCP protocol types and error handling Complete tools/call request (matches TypeScript CallToolRequest interface)
CallToolResult: Core MCP protocol types and error handling Result for tools/call (per MCP spec)
CancelTaskParams: Core MCP protocol types and error handling Parameters for tasks/cancel request
CancelTaskRequest: Core MCP protocol types and error handling Complete tasks/cancel request
CancelTaskResult: Core MCP protocol types and error handling Result for tasks/cancel — flattens Task fields per TS Result & Task
CancelledNotification: Core MCP protocol types and error handling Method: “notifications/cancelled”
ClientCapabilities: Core MCP protocol types and error handling Capabilities that a client may support (per MCP 2025-11-25)
CreateTaskResult: Core MCP protocol types and error handling Returned when a task-augmented request is accepted (instead of the operation’s direct result).
ElicitCreateParams: Core MCP protocol types and error handling Parameters for elicitation/create request (per MCP spec)
ElicitCreateRequest: Core MCP protocol types and error handling Complete elicitation/create request (matches TypeScript ElicitRequest interface)
ElicitResult: Core MCP protocol types and error handling The client’s response to an elicitation request (per MCP spec)
ElicitationBuilder: Core MCP protocol types and error handling Builder for creating common elicitation patterns
ElicitationCompleteNotification: Core MCP protocol types and error handling Method: “notifications/elicitation/complete” (per MCP 2025-11-25)
ElicitationSchema: Core MCP protocol types and error handling Restricted schema for elicitation (only primitive types, no nesting) - per MCP spec
EmptyParams: Core MCP protocol types and error handling
EmptyResult: Core MCP protocol types and error handling Empty result for successful operations (per MCP spec)
GetPromptRequest: Core MCP protocol types and error handling Complete prompts/get request (matches TypeScript GetPromptRequest interface)
GetPromptResult: Core MCP protocol types and error handling Result for prompts/get (per MCP spec)
GetTaskParams: Core MCP protocol types and error handling Parameters for tasks/get request
GetTaskPayloadParams: Core MCP protocol types and error handling Parameters for tasks/result request (retrieves the original operation’s result)
GetTaskPayloadRequest: Core MCP protocol types and error handling Complete tasks/result request
GetTaskRequest: Core MCP protocol types and error handling Complete tasks/get request
GetTaskResult: Core MCP protocol types and error handling Result for tasks/get — flattens Task fields per TS Result & Task
Icon: Core MCP protocol types and error handling Icon for tools, resources, prompts, and implementations. Icons are display hints — most implementations do not need icons. See MCP spec
Implementation: Core MCP protocol types and error handling Describes the name and version of an MCP implementation
InitializeRequest: Core MCP protocol types and error handling Parameters for initialize request
InitializeResult: Core MCP protocol types and error handling Result payload for initialize (per MCP spec)
InitializedNotification: Core MCP protocol types and error handling Method: “notifications/initialized”
JsonRpcDispatcher: JSON-RPC 2.0 dispatcher and handler trait for protocol operations JSON-RPC method dispatcher with specific error type
JsonRpcError: Core MCP protocol types and error handling JSON-RPC 2.0 error object
JsonRpcNotification: Core MCP protocol types and error handling A JSON-RPC 2.0 notification (no response expected)
JsonRpcRequest: Core MCP protocol types and error handling A standard JSON-RPC 2.0 request
JsonRpcResponse: Core MCP protocol types and error handling A standard JSON-RPC 2.0 response
ListPromptsRequest: Core MCP protocol types and error handling Complete prompts/list request (matches TypeScript ListPromptsRequest interface)
ListPromptsResult: Core MCP protocol types and error handling Result for prompts/list (per MCP spec)
ListResourcesRequest: Core MCP protocol types and error handling Complete resources/list request (matches TypeScript ListResourcesRequest interface)
ListResourcesResult: Core MCP protocol types and error handling Result for resources/list (per MCP spec)
ListTasksParams: Core MCP protocol types and error handling Parameters for tasks/list request
ListTasksRequest: Core MCP protocol types and error handling Complete tasks/list request
ListTasksResult: Core MCP protocol types and error handling Result for tasks/list (extends PaginatedResult)
ListToolsRequest: Core MCP protocol types and error handling Complete tools/list request (matches TypeScript ListToolsRequest interface)
ListToolsResult: Core MCP protocol types and error handling Result for tools/list (per MCP spec) - extends PaginatedResult
LoggingMessageNotification: Core MCP protocol types and error handling Method: “notifications/message”
LoggingMessageNotificationParams: Core MCP protocol types and error handling
Meta: Core MCP protocol types and error handling Structured _meta field for MCP 2025-11-25
MetaCursor: Core MCP protocol types and error handling Cursor for pagination support
Notification: Core MCP protocol types and error handling Base notification structure following MCP TypeScript specification
NotificationParams: Core MCP protocol types and error handling Base notification parameters that can include _meta
PaginatedResponse: Core MCP protocol types and error handling Helper for pagination responses
PingRequest: Core MCP protocol types and error handling Request for ping (per MCP spec)
ProgressNotification: Core MCP protocol types and error handling Method: “notifications/progress”
ProgressNotificationParams: Core MCP protocol types and error handling
ProgressResponse: Core MCP protocol types and error handling Helper for progress responses
ProgressToken: Core MCP protocol types and error handling Progress token for tracking long-running operations
Prompt: Core MCP protocol types and error handling A prompt descriptor (matches TypeScript Prompt interface exactly)
PromptArgument: Core MCP protocol types and error handling Argument definition for prompts (extends BaseMetadata per MCP spec)
PromptListChangedNotification: Core MCP protocol types and error handling Method: “notifications/prompts/list_changed” (per MCP spec)
PromptMessage: Core MCP protocol types and error handling Message content for prompts (matches MCP PromptMessage interface exactly)
ReadResourceRequest: Core MCP protocol types and error handling Complete resources/read request (matches TypeScript ReadResourceRequest interface)
ReadResourceResult: Core MCP protocol types and error handling Result for resources/read (per MCP spec)
RequestParams: Core MCP protocol types and error handling JSON-RPC params object with optional _meta and method-specific arguments
Resource: Core MCP protocol types and error handling A resource descriptor (matches TypeScript Resource interface) Resource extends BaseMetadata, so it includes name and title fields
ResourceListChangedNotification: Core MCP protocol types and error handling Method: “notifications/resources/list_changed” (per MCP spec)
ResourceReference: Core MCP protocol types and error handling Resource reference for resource links (matches TypeScript Resource interface)
ResourceSubscription: Core MCP protocol types and error handling Resource subscription parameters
ResourceUpdatedNotification: Core MCP protocol types and error handling Method: “notifications/resources/updated”
ResourceUpdatedNotificationParams: Core MCP protocol types and error handling
ResultWithMeta: Core MCP protocol types and error handling A generic result wrapper that combines data with optional _meta information
RootsListChangedNotification: Core MCP protocol types and error handling Method: “notifications/roots/list_changed” (per MCP spec)
ServerCapabilities: Core MCP protocol types and error handling Capabilities that a server may support
SubscribeRequest: Core MCP protocol types and error handling Complete resources/subscribe request (per MCP spec)
Task: Core MCP protocol types and error handling Core task descriptor per MCP 2025-11-25. See MCP spec
TaskMetadata: Core MCP protocol types and error handling Task metadata for task-augmented requests. Added to CallToolParams, CreateMessageParams, ElicitCreateParams to indicate that the operation should create a task.
TaskStatusNotification: Core MCP protocol types and error handling Method: “notifications/tasks/status” (per MCP 2025-11-25)
TasksCancelCapabilities: Core MCP protocol types and error handling Signals support for tasks/cancel — presence means supported, extensible via extra
TasksCapabilities: Core MCP protocol types and error handling Capabilities for tasks (per MCP 2025-11-25)
TasksListCapabilities: Core MCP protocol types and error handling Signals support for tasks/list — presence means supported, extensible via extra
TasksRequestCapabilities: Core MCP protocol types and error handling Describes which request types support task augmentation
TasksToolCallCapabilities: Core MCP protocol types and error handling Signals support for task-augmented tools/call — presence means supported
TasksToolCapabilities: Core MCP protocol types and error handling Tool-level task capabilities
TextResourceContents: Core MCP protocol types and error handling Text resource contents (matches TypeScript TextResourceContents exactly)
Tool: Core MCP protocol types and error handling Tool definition
ToolExecution: Core MCP protocol types and error handling Execution configuration for a tool (per MCP 2025-11-25)
ToolListChangedNotification: Core MCP protocol types and error handling Method: “notifications/tools/list_changed” (per MCP spec)
ToolSchema: Core MCP protocol types and error handling JSON Schema definition for tool input/output (matches TypeScript spec exactly) Must be an object with type: “object”, properties, and required fields
UnsubscribeRequest: Core MCP protocol types and error handling Complete resources/unsubscribe request (per MCP spec)

Enums§

ContentBlock: Core MCP protocol types and error handling Content block union type matching MCP 2025-11-25 specification exactly
ElicitAction: Core MCP protocol types and error handling User action in response to elicitation
HttpMcpError: HTTP MCP specific errors
IconTheme: Core MCP protocol types and error handling Theme preference for an icon (light or dark mode). See MCP spec
JsonRpcMessage: Core MCP protocol types and error handling Unified JSON-RPC message type
JsonSchema: Core MCP protocol types and error handling A JSON Schema definition
LegacyRequestParams: Core MCP protocol types and error handling Parameters for a JSON-RPC request
McpError: Core MCP protocol types and error handling MCP-specific errors
McpVersion: Core MCP protocol types and error handling Supported MCP protocol versions
PrimitiveSchemaDefinition: Core MCP protocol types and error handling Restricted schema definitions that only allow primitive types without nested objects or arrays (per MCP spec).
ProgressTokenValue: Core MCP protocol types and error handling Progress token value — can be a string or a number per MCP 2025-11-25. See MCP spec
RequestId: Core MCP protocol types and error handling A uniquely identifying ID for a JSON-RPC request. Can be a string or a number, but never null.
ResourceContent: Core MCP protocol types and error handling Union type for resource contents (matches TypeScript union)
ResourceContents: Core MCP protocol types and error handling Resource contents union type (matches TypeScript TextResourceContents | BlobResourceContents)
ResponseResult: Core MCP protocol types and error handling Result data for a JSON-RPC response
StringFormat: Core MCP protocol types and error handling String format constraints
TaskStatus: Core MCP protocol types and error handling Task status enum per MCP 2025-11-25. See MCP spec
TaskSupport: Core MCP protocol types and error handling Whether a tool supports long-running task execution (per MCP 2025-11-25)

Constants§

CURRENT_VERSION: Core MCP protocol types and error handling The current MCP protocol version implemented by this crate
MCP_VERSION: Core MCP protocol types and error handling The MCP protocol version implemented by this crate

Traits§

HasData: Core MCP protocol types and error handling
HasDataParam: Core MCP protocol types and error handling
HasMeta: Core MCP protocol types and error handling
HasMetaParam: Core MCP protocol types and error handling
HasProgressTokenParam: Core MCP protocol types and error handling
JsonRpcHandler: JSON-RPC 2.0 dispatcher and handler trait for protocol operations Trait for handling JSON-RPC method calls
JsonRpcNotificationTrait: Core MCP protocol types and error handling
JsonRpcRequestTrait: Core MCP protocol types and error handling
JsonRpcResponseTrait: Core MCP protocol types and error handling
Params: Core MCP protocol types and error handling
RpcResult: Core MCP protocol types and error handling
WithMeta: Core MCP protocol types and error handling Trait for types that can include _meta fields

Type Aliases§

McpResult: Core MCP protocol types and error handling Common result type for MCP operations
Result: Result type for HTTP MCP operations
ToolResult: Core MCP protocol types and error handling Tool result type - an alias for ContentBlock to maintain backward compatibility while ensuring MCP 2025-11-25 specification compliance

Crate turul_http_mcp_server

Crate turul_http_mcp_server Copy item path

§HTTP MCP Server

§Installation

§Supported Transports

§Features

§Quick Start

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Type Aliases§

Crate turul_http_mcp_server