Struct RequestContext 

pub struct RequestContext {
    pub request_id: String,
    pub transport: TransportType,
    pub user_id: Option<String>,
    pub session_id: Option<String>,
    pub client_id: Option<String>,
    pub metadata: HashMap<String, Value>,
    pub principal: Option<Principal>,
    pub session: Option<Arc<dyn McpSession>>,
    pub headers: Option<HashMap<String, String>>,
    pub start_time: Option<Instant>,
    pub cancellation_token: Option<Arc<dyn Cancellable>>,
}

Canonical per-request context.

Carries request identity, transport information, authentication principal, arbitrary typed metadata, and — when the transport supports bidirectional communication — an McpSession handle that enables server-to-client operations such as sampling and elicitation.

Thread Safety

RequestContext is Send + Sync on native targets. On WASM targets the Send/Sync bounds are dropped (single-threaded runtime).

Fields

request_id: String

Unique request identifier (JSON-RPC id as string, or generated UUID).

transport: TransportType

Transport type that received this request.

user_id: Option<String>

Authenticated user identifier, if the request was authenticated.

session_id: Option<String>

Session identifier for stateful transports (HTTP + session cookie, WS, Streamable HTTP, etc.).

client_id: Option<String>

Client application identifier reported by the peer.

metadata: HashMap<String, Value>

Rich typed metadata (headers, trace IDs, custom per-request data).

principal: Option<Principal>

Authenticated principal, if auth is configured and succeeded.

session: Option<Arc<dyn McpSession>>

Bidirectional session handle for server-to-client requests.

Populated by the server dispatcher before routing; None on unidirectional transports (e.g., stateless HTTP) or when the request is being synthesized (tests, examples).

headers: Option<HashMap<String, String>>

HTTP-layer headers for HTTP/WebSocket transports.

Populated by the transport; None for non-HTTP transports. Uses hashbrown::HashMap so it stays available in no_std / WASM builds.

start_time: Option<Instant>

Available on crate feature std only.

Wall-clock moment at which the server began processing the request.

Used for elapsed() measurements and tracing spans.

cancellation_token: Option<Arc<dyn Cancellable>>

Available on crate feature std only.

Cooperative-cancellation handle.

Tool bodies should check ctx.is_cancelled() during long operations and abort early. The server wires a tokio_util::sync::CancellationToken in here (via the Cancellable blanket impl in turbomcp-server).

Implementations

impl RequestContext

pub fn new() -> RequestContext

Create a new request context with a freshly generated UUID and Stdio transport.

For WASM/no_std builds the request ID is empty; call Self::with_id explicitly to set one.

pub fn with_id_and_transport( request_id: impl Into<String>, transport: TransportType, ) -> RequestContext

Create a context with the given ID and transport.

pub fn with_id(request_id: impl Into<String>) -> RequestContext

Create a context with an explicit request ID (Stdio transport).

pub fn stdio() -> RequestContext

Create a context for STDIO transport with a fresh UUID.

pub fn http() -> RequestContext

Create a context for HTTP transport with a fresh UUID.

pub fn websocket() -> RequestContext

Create a context for WebSocket transport with a fresh UUID.

pub fn tcp() -> RequestContext

Create a context for TCP transport with a fresh UUID.

pub fn unix() -> RequestContext

Create a context for Unix domain socket transport with a fresh UUID.

pub fn wasm() -> RequestContext

Create a context for WASM transport with a fresh UUID.

pub fn channel() -> RequestContext

Create a context for in-process channel transport with a fresh UUID.

impl RequestContext

pub fn with_request_id(self, id: impl Into<String>) -> RequestContext

Set the request ID.

pub fn with_transport(self, transport: TransportType) -> RequestContext

Set the transport type.

pub fn with_user_id(self, user_id: impl Into<String>) -> RequestContext

Set the authenticated user ID.

pub fn with_session_id(self, session_id: impl Into<String>) -> RequestContext

Set the session ID.

pub fn with_client_id(self, client_id: impl Into<String>) -> RequestContext

Set the client ID.

pub fn with_principal(self, principal: Principal) -> RequestContext

Set the authenticated principal.

pub fn with_metadata( self, key: impl Into<String>, value: impl Into<Value>, ) -> RequestContext

Attach a metadata key/value pair.

Accepts any value convertible to serde_json::Value, so string literals, numbers, and structured data all work.

pub fn with_session(self, session: Arc<dyn McpSession>) -> RequestContext

Attach a bidirectional session handle.

pub fn with_headers(self, headers: HashMap<String, String>) -> RequestContext

Attach HTTP headers (case-sensitive keys; header does case-insensitive lookup).

pub fn with_start_time(self, start: Instant) -> RequestContext

Available on crate feature std only.

Mark the request start time.

pub fn with_cancellation_token( self, token: Arc<dyn Cancellable>, ) -> RequestContext

Available on crate feature std only.

Attach a cancellation handle.

impl RequestContext

pub fn insert_metadata( &mut self, key: impl Into<String>, value: impl Into<Value>, )

Mutable metadata insert.

pub fn set_principal(&mut self, principal: Principal)

Mutable principal setter.

pub fn clear_principal(&mut self)

Clear the authenticated principal.

pub fn set_session(&mut self, session: Arc<dyn McpSession>)

Mutable session setter.

impl RequestContext

pub fn request_id(&self) -> &str

Request ID.

pub fn has_request_id(&self) -> bool

Returns true when a non-empty request ID is set.

pub fn transport(&self) -> TransportType

Transport type.

pub fn user_id(&self) -> Option<&str>

Authenticated user ID, if present.

pub fn session_id(&self) -> Option<&str>

Session ID, if present.

pub fn client_id(&self) -> Option<&str>

Client ID, if present.

pub fn get_metadata(&self, key: &str) -> Option<&Value>

Rich metadata lookup.

pub fn get_metadata_str(&self, key: &str) -> Option<&str>

Rich metadata lookup, downcast to &str for string values.

pub fn has_metadata(&self, key: &str) -> bool

Returns true when a metadata key is set.

pub fn principal(&self) -> Option<&Principal>

Authenticated principal, if any.

pub fn is_authenticated(&self) -> bool

Returns true when the request is authenticated.

A request is considered authenticated when it has either a principal or a user_id. Callers with richer auth semantics should read the principal directly.

pub fn subject(&self) -> Option<&str>

Authenticated subject (principal subject, falling back to user_id).

pub fn session(&self) -> Option<&Arc<dyn McpSession>>

Session handle, if attached.

pub fn has_session(&self) -> bool

Returns true when a bidirectional session is attached.

pub fn headers(&self) -> Option<&HashMap<String, String>>

All HTTP headers, if the transport captured any.

pub fn header(&self, name: &str) -> Option<&str>

Case-insensitive HTTP header lookup.

pub fn elapsed(&self) -> Option<Duration>

Available on crate feature std only.

Elapsed time since the request started (if start_time was set).

pub fn is_cancelled(&self) -> bool

Available on crate feature std only.

Returns true when the request has been marked for cancellation.

pub fn roles(&self) -> Vec<String>

Authenticated roles, sourced from the principal or from metadata.

Looks at (in order): principal.roles, metadata["auth"].roles[].

pub fn has_any_role<S>(&self, required: &[S]) -> bool

where S: AsRef<str>,

Returns true when the principal has any of the specified roles. An empty required list always returns true.

impl RequestContext

pub async fn sample( &self, request: CreateMessageRequest, ) -> Result<CreateMessageResult, McpError>

Request LLM sampling from the connected client.

Requires a bidirectional session; returns McpError::capability_not_supported on unidirectional transports.

pub async fn elicit_form( &self, message: impl Into<String>, schema: Value, ) -> Result<ElicitResult, McpError>

Request form-based user input from the client.

pub async fn elicit_url( &self, message: impl Into<String>, url: impl Into<String>, elicitation_id: impl Into<String>, ) -> Result<ElicitResult, McpError>

Request URL-based user action from the client.

pub async fn notify_client( &self, method: impl AsRef<str>, params: Value, ) -> Result<(), McpError>

Send a JSON-RPC notification to the client.

Trait Implementations

impl Clone for RequestContext

fn clone(&self) -> RequestContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RequestContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for RequestContext

fn default() -> RequestContext

Returns the “default value” for a type.

impl RequestContextExt for RequestContext

fn with_enhanced_client_id(self, client_id: ClientId) -> Self

Set client_id from a structured super::client::ClientId and record the authentication method + authenticated flag in metadata.

fn extract_client_id( self, extractor: &ClientIdExtractor, headers: Option<&HashMap<String, String>>, query_params: Option<&HashMap<String, String>>, ) -> Self

Extract a client ID from headers/query params and apply it via Self::with_enhanced_client_id.

fn get_enhanced_client_id(&self) -> Option<ClientId>

Rehydrate the structured super::client::ClientId from the context.

impl RichContextExt for RequestContext

fn get_state<T: DeserializeOwned>(&self, key: &str) -> Option<T>

Get a value from session state.

fn try_get_state<T: DeserializeOwned>( &self, key: &str, ) -> Result<Option<T>, StateError>

Try to get a value from session state with detailed error information.

fn set_state<T: Serialize>(&self, key: &str, value: &T) -> bool

Set a value in session state.

fn try_set_state<T: Serialize>( &self, key: &str, value: &T, ) -> Result<(), StateError>

Try to set a value in session state with detailed error information.

fn remove_state(&self, key: &str) -> bool

Remove a value from session state.

fn clear_state(&self)

Clear all session state.

fn has_state(&self, key: &str) -> bool

Check if a state key exists.

async fn debug( &self, message: impl Into<String> + MaybeSend, ) -> Result<(), McpError>

Send a debug-level log message to the client.

async fn info( &self, message: impl Into<String> + MaybeSend, ) -> Result<(), McpError>

Send an info-level log message to the client.

async fn warning( &self, message: impl Into<String> + MaybeSend, ) -> Result<(), McpError>

Send a warning-level log message to the client.

async fn error( &self, message: impl Into<String> + MaybeSend, ) -> Result<(), McpError>

Send an error-level log message to the client.

async fn log( &self, level: LogLevel, message: impl Into<String> + MaybeSend, logger: Option<String>, ) -> Result<(), McpError>

Send a log message to the client with a specific level.

async fn report_progress( &self, current: f64, total: f64, message: Option<&str>, ) -> Result<(), McpError>

Report progress on a long-running operation.

async fn report_progress_with_token( &self, token: impl Into<ProgressToken> + MaybeSend, current: f64, total: Option<f64>, message: Option<&str>, ) -> Result<(), McpError>

Report progress with a custom ProgressToken.