Struct RequestContext 

pub struct RequestContext { /* private fields */ }

Context for a request, providing progress, cancellation, and client request support

Implementations

impl RequestContext

pub fn supports_mcp_apps(&self) -> bool

Return whether both peers negotiated MCP Apps with the stable HTML MIME.

impl RequestContext

pub fn supports_tasks(&self) -> bool

Whether both peers negotiated the final Tasks extension.

Task dispatch keys off this rather than off the protocol version: a 2026-07-28 request from a client that did not declare the extension must not receive a task.

impl RequestContext

pub fn new(request_id: RequestId) -> Self

Create a new request context

pub fn with_progress_token(self, token: ProgressToken) -> Self

Set the progress token

pub fn with_notification_sender(self, tx: NotificationSender) -> Self

Set the notification sender

pub fn with_min_log_level(self, level: Arc<RwLock<LogLevel>>) -> Self

Set the minimum log level for filtering outgoing log notifications

This is shared with the router so that logging/setLevel updates are immediately visible to all request contexts.

pub fn with_client_requester(self, requester: ClientRequesterHandle) -> Self

Set the client requester for server-to-client requests

pub fn with_extensions(self, extensions: Arc<Extensions>) -> Self

Set the extensions for this request context.

Extensions allow router-level state and middleware data to flow to handlers.

pub fn extension<T: Send + Sync + 'static>(&self) -> Option<&T>

Get a reference to a value from the extensions map.

Returns None if no value of the given type has been inserted.

Example

#[derive(Clone)]
struct CurrentUser { id: String }

// In a handler:
if let Some(user) = ctx.extension::<CurrentUser>() {
    println!("User: {}", user.id);
}

pub fn negotiated_extensions(&self) -> Option<&NegotiatedExtensions>

Protocol extensions declared by both the client and server.

Unknown or one-sided declarations are not included. The returned view preserves each peer’s settings object for extension-specific policy.

pub fn extensions_mut(&mut self) -> &mut Extensions

Get a mutable reference to the extensions.

This allows middleware to insert data that handlers can access via the Extension<T> extractor.

pub fn extensions(&self) -> &Extensions

Get a reference to the extensions.

pub fn per_request_meta(&self) -> Option<&StatelessRequestMeta>

SEP-2575 per-request _meta (protocol version, client info, client capabilities, log level) if the transport extracted it.

Returns Some for 2026-07-28 clients on JSON-RPC transports when the request carried a _meta object with recognized fields. Returns None when:

• The request had no _meta field, or
• The transport does not use crate::jsonrpc::JsonRpcService, or
• The stateless feature is not compiled in.

Example

async fn my_tool(ctx: RequestContext, input: MyInput) -> Result<CallToolResult> {
    if let Some(meta) = ctx.per_request_meta() {
        // protocol_version, client_info, client_capabilities are all Option<_>
        if let Some(ref version) = meta.protocol_version {
            tracing::debug!(protocol_version = %version);
        }
        if let Some(ref info) = meta.client_info {
            tracing::info!(client = %info.name, version = %info.version);
        }
    }
    Ok(CallToolResult::text("ok"))
}

pub fn mrtr(&self) -> Option<&MrtrRequest>

SEP-2322 continuation values supplied by the client on this attempt.

pub fn input_responses(&self) -> Option<&InputResponses>

Client responses from the prior MRTR round, if any.

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

Opaque request state echoed by the client, if any.

pub fn request_state_codec(&self) -> Option<&RequestStateCodec>

Router-configured request-state codec shared by this handler.

pub fn request_id(&self) -> &RequestId

Get the request ID

pub fn progress_token(&self) -> Option<&ProgressToken>

Get the progress token (if any)

pub fn is_cancelled(&self) -> bool

Check if the request has been cancelled

pub fn cancel(&self)

Mark the request as cancelled

pub async fn cancelled(&self)

Wait until the request is cancelled.

Completes when cancel is called – by a notifications/cancelled message, or by the transport when the client disconnects before the response is delivered (HTTP stateless mode). Useful in tokio::select! to abandon work early:

tokio::select! {
    result = do_work() => { /* ... */ }
    _ = ctx.cancelled() => return Err(Error::tool("cancelled")),
}

pub fn cancellation_token(&self) -> CancellationToken

Get a cancellation token that can be shared

pub fn with_cancellation_token(self, token: CancellationToken) -> Self

Replace this context’s cancellation source with an existing token.

Used by transports to link a request’s lifetime to an external signal (e.g. client disconnect on the HTTP stateless path). After this call, is_cancelled(), cancelled(), and tokens returned by cancellation_token all observe the given token.

pub async fn report_progress( &self, progress: f64, total: Option<f64>, message: Option<&str>, )

Report progress to the client

This is a no-op if no progress token was provided or no notification sender is configured.

pub fn report_progress_sync( &self, progress: f64, total: Option<f64>, message: Option<&str>, )

Report progress synchronously (non-async version)

This is a no-op if no progress token was provided or no notification sender is configured.

pub fn notify_tools_list_changed(&self) -> bool

Notify subscribed clients that the tool list changed.

pub fn notify_prompts_list_changed(&self) -> bool

Notify subscribed clients that the prompt list changed.

pub fn notify_resources_list_changed(&self) -> bool

Notify subscribed clients that the resource list changed.

pub fn notify_resource_updated(&self, uri: impl Into<String>) -> bool

Notify subscribed clients that one resource changed.

pub fn send_log(&self, params: LoggingMessageParams)

Send a log message notification to the client

This is a no-op if no notification sender is configured.

Example

use tower_mcp::protocol::{LoggingMessageParams, LogLevel};

async fn my_tool(ctx: RequestContext) {
    ctx.send_log(
        LoggingMessageParams::new(LogLevel::Info, serde_json::json!("Processing..."))
            .with_logger("my-tool")
    );
}

pub fn can_sample(&self) -> bool

Check if sampling is available

Returns true if a client requester is configured and the transport supports bidirectional communication.

pub async fn sample( &self, params: CreateMessageParams, ) -> Result<CreateMessageResult>

Request an LLM completion from the client

This sends a sampling/createMessage request to the client and waits for the response. The client is expected to forward this to an LLM and return the result.

Returns an error if sampling is not available (no client requester configured).

Example

use tower_mcp::{CreateMessageParams, SamplingMessage};

async fn my_tool(ctx: RequestContext, input: MyInput) -> Result<CallToolResult> {
    let params = CreateMessageParams::new(
        vec![SamplingMessage::user("Summarize: ...")],
        500,
    );

    let result = ctx.sample(params).await?;
    Ok(CallToolResult::text(format!("{:?}", result.content)))
}

pub fn can_elicit(&self) -> bool

Check if elicitation is available

Returns true if a client requester is configured and the transport supports bidirectional communication. Note that this only checks if the mechanism is available, not whether the client supports elicitation.

pub async fn elicit_form( &self, params: ElicitFormParams, ) -> Result<ElicitResult>

Request user input via a form from the client

This sends an elicitation/create request to the client with a form schema. The client renders the form to the user and returns their response.

Returns an error if elicitation is not available (no client requester configured).

Example

use tower_mcp::{ElicitFormParams, ElicitFormSchema, ElicitMode, ElicitAction};

async fn my_tool(ctx: RequestContext, input: MyInput) -> Result<CallToolResult> {
    let params = ElicitFormParams {
        mode: Some(ElicitMode::Form),
        message: "Please enter your details".to_string(),
        requested_schema: ElicitFormSchema::new()
            .string_field("name", Some("Your name"), true),
        meta: None,
    };

    let result = ctx.elicit_form(params).await?;
    match result.action {
        ElicitAction::Accept => {
            // Use result.content
            Ok(CallToolResult::text("Got your input!"))
        }
        _ => Ok(CallToolResult::text("User declined"))
    }
}

pub async fn elicit_url(&self, params: ElicitUrlParams) -> Result<ElicitResult>

Request user input via URL redirect from the client

This sends an elicitation/create request to the client with a URL. The client directs the user to the URL for out-of-band input collection. The server receives the result via a callback notification.

Returns an error if elicitation is not available (no client requester configured).

Protocol note: ElicitUrlParams::elicitation_id and the callback notification it correlates with are a 2025-11-25-and-earlier pattern. The final 2026-07-28 schema removes both in favor of MRTR (SEP-2322). Use an MRTR-capable tool, prompt, or resource handler there; the client learns the outcome by retrying the original request instead of receiving a completion notification.

Example

use tower_mcp::{ElicitUrlParams, ElicitMode, ElicitAction};

async fn my_tool(ctx: RequestContext, input: MyInput) -> Result<CallToolResult> {
    let params = ElicitUrlParams {
        mode: Some(ElicitMode::Url),
        elicitation_id: "unique-id-123".to_string(),
        message: "Please authorize via the link".to_string(),
        url: "https://example.com/auth?id=unique-id-123".to_string(),
        meta: None,
    };

    let result = ctx.elicit_url(params).await?;
    match result.action {
        ElicitAction::Accept => Ok(CallToolResult::text("Authorization complete!")),
        _ => Ok(CallToolResult::text("Authorization cancelled"))
    }
}

pub async fn confirm(&self, message: impl Into<String>) -> Result<bool>

Request simple confirmation from the user.

This is a convenience method for simple yes/no confirmation dialogs. It creates an elicitation form with a single boolean “confirm” field and returns true if the user accepts, false otherwise.

Returns an error if elicitation is not available (no client requester configured).

Example

use tower_mcp::{RequestContext, CallToolResult};

async fn delete_item(ctx: RequestContext) -> Result<CallToolResult> {
    let confirmed = ctx.confirm("Are you sure you want to delete this item?").await?;
    if confirmed {
        // Perform deletion
        Ok(CallToolResult::text("Item deleted"))
    } else {
        Ok(CallToolResult::text("Deletion cancelled"))
    }
}

pub async fn list_tasks( &self, status: Option<TaskStatus>, ) -> Result<ListTasksResult>

👎Deprecated since 0.13.0:

final SEP-2663 removes tasks/list; a conforming peer answers MethodNotFound (-32601). Only useful against legacy SEP-1686 clients.

List tasks tracked by the connected client (legacy SEP-1686).

Sends a tasks/list request to the client and returns the result. Pass Some(status) to filter to a single status, or None for all tasks. Pagination is exposed via ListTasksResult::next_cursor; use request_raw for cursor-driven calls.

Returns an error if no client requester is configured or the client does not advertise task support.

pub async fn get_task_info( &self, task_id: impl Into<String>, ) -> Result<TaskObject>

Fetch metadata for a single task tracked by the client (SEP-1686).

Sends a tasks/get request and returns the task object, including the current status, timestamps, and TTL.

pub async fn get_task_result( &self, task_id: impl Into<String>, ) -> Result<CallToolResult>

👎Deprecated since 0.13.0:

final SEP-2663 removes tasks/result (results are inlined in the tasks/get DetailedTask); a conforming peer answers MethodNotFound (-32601). Only useful against legacy SEP-1686 clients.

Fetch the terminal result for a task tracked by the client (legacy SEP-1686).

Sends a tasks/result request. The client is expected to block until the task reaches a terminal state and then return the underlying CallToolResult. For long-running tasks, prefer polling with get_task_info and only call this once the status is terminal.

pub async fn cancel_task( &self, task_id: impl Into<String>, reason: Option<String>, ) -> Result<()>

Cancel a task tracked by the client.

Sends a tasks/cancel request. Per final SEP-2663 the acknowledgment is an empty result and the observable task status is polled via get_task_info; the ack body is discarded, so this also tolerates legacy SEP-1686 peers that return the task object.

pub async fn request_raw(&self, method: &str, params: Value) -> Result<Value>

Send an arbitrary JSON-RPC request to the client.

Escape hatch for methods not covered by the typed helpers (e.g. when a tasks/list cursor needs to be passed). Most callers should prefer the typed methods.

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

Formats the value using the given formatter.