Struct Context 

pub struct Context<'a> {
    pub request_id: &'a RequestId,
    pub progress_token: Option<&'a ProgressToken>,
    pub client_caps: &'a ClientCapabilities,
    pub server_caps: &'a ServerCapabilities,
    pub protocol_version: ProtocolVersion,
    /* private fields */
}

Request context passed to handler methods.

The context uses lifetime references to avoid 'static requirements and Arc overhead. This enables:

• Single-threaded async without Arc overhead
• !Send types in handlers (important for some runtimes)
• Users who need spawning can wrap in Arc themselves

Per the plan: “Request context - passed by reference, NO ’static requirement”

Fields

request_id: &'a RequestId

The request ID for this operation.

progress_token: Option<&'a ProgressToken>

Optional progress token for reporting progress.

client_caps: &'a ClientCapabilities

Client capabilities negotiated during initialization.

server_caps: &'a ServerCapabilities

Server capabilities advertised during initialization.

protocol_version: ProtocolVersion

The negotiated protocol version.

Use this to check version-specific feature availability via methods like supports_tasks(), supports_elicitation(), etc.

Implementations

impl<'a> Context<'a>

pub fn new( request_id: &'a RequestId, progress_token: Option<&'a ProgressToken>, client_caps: &'a ClientCapabilities, server_caps: &'a ServerCapabilities, protocol_version: ProtocolVersion, peer: &'a dyn Peer, ) -> Self

Create a new context with all required references.

pub fn with_cancellation( request_id: &'a RequestId, progress_token: Option<&'a ProgressToken>, client_caps: &'a ClientCapabilities, server_caps: &'a ServerCapabilities, protocol_version: ProtocolVersion, peer: &'a dyn Peer, cancel: CancellationToken, ) -> Self

Create a new context with a custom cancellation token.

pub fn for_notification( client_caps: &'a ClientCapabilities, server_caps: &'a ServerCapabilities, protocol_version: ProtocolVersion, peer: &'a dyn Peer, ) -> Self

Create a context for handling an inbound client notification.

Notifications carry no JSON-RPC request id, so request_id is a documented sentinel (__notification__) that must not be treated as a real id. The context is still outbound-capable: a hook may call list_roots or send notifications, and those server-to-client requests allocate their own ids via the peer.

pub fn with_related_task(self, task_id: TaskId) -> Self

Associate this context with a task.

Every outbound request made through it then carries _meta["io.modelcontextprotocol/related-task"] with task_id, which the spec requires of messages related to a task:

All requests, notifications, and responses related to a task MUST include the io.modelcontextprotocol/related-task key in their _meta field […] an elicitation that a task-augmented tool call depends on MUST share the same related task ID with that tool call’s task.

Applied automatically by the task-augmented tool path; call this only when driving a task yourself.

pub const fn related_task(&self) -> Option<&TaskId>

The task this request is part of, if any.

pub fn is_cancelled(&self) -> bool

Check if the request has been cancelled.

pub fn cancelled(&self) -> impl Future<Output = ()> + '_

Get a future that completes when the request is cancelled.

pub const fn cancellation_token(&self) -> &CancellationToken

Get the cancellation token for this context.

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

Send a notification to the client.

Arguments

• method - The notification method name
• params - Optional notification parameters

Errors

Returns an error if the notification could not be sent.

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

Report progress for this operation.

This sends a progress notification to the client if a progress token was provided with the request.

Arguments

• current - Current progress value
• total - Total progress value (if known)
• message - Optional progress message

Errors

Returns an error if the notification could not be sent.

pub async fn log( &self, level: LoggingLevel, logger: Option<&str>, data: Value, ) -> Result<(), McpError>

Emit a notifications/message log to the client at level, optionally tagged with a logger name and carrying arbitrary JSON data.

Errors

Returns an error if the notification could not be sent.

pub async fn request( &self, method: impl Into<Cow<'static, str>>, params: Option<Value>, ) -> Result<Value, McpError>

Send a request to the client and await its response.

This is the basis for server-initiated requests (e.g. elicitation, sampling). The peer assigns the request id and correlates the response; the request is aborted if this context is cancelled.

Errors

Returns an error if the request was cancelled, the peer does not support requests, the request timed out, or the response carried a JSON-RPC error.

pub async fn elicit( &self, request: ElicitRequest, ) -> Result<ElicitResult, McpError>

Request structured input from the user through the client (form-mode elicitation).

Sends an elicitation/create request and awaits the user’s response (accept with content, decline, or cancel). This requires the client to have declared the elicitation capability and the negotiated protocol version to support elicitation.

Errors

Returns an error if the client did not declare elicitation support, the negotiated protocol version predates elicitation, the request was cancelled or timed out, or the response could not be parsed.

pub async fn list_roots(&self) -> Result<Vec<Root>, McpError>

Request the roots this client exposes (roots/list).

Requires the client to have declared the roots capability.

Errors

Returns an error if the client did not declare roots support, or the request fails, times out, or the response could not be parsed.

pub async fn elicit_url( &self, request: UrlElicitRequest, ) -> Result<ElicitResult, McpError>

Request a URL-mode elicitation: ask the client to have the user navigate to a URL for an out-of-band interaction (e.g. authorization or payment).

Returns the client’s ElicitResult action once the user consents to open the URL. When the out-of-band interaction later finishes, notify the client with ServerNotifier::elicitation_complete(elicitation_id).

Gated on the client’s elicitation.url sub-capability (which is only declared on 2025-11-25+).

Security

Per the MCP spec, the caller MUST use an unguessable elicitation_id bound to a verified user identity and MUST NOT place credentials in the URL. mcpkit provides the mechanism; associating the id with a user is the application’s responsibility (see the session-binding helpers, #86).

Errors

Returns an error if the negotiated protocol version does not support elicitation, the client did not declare URL-mode elicitation, or the request fails.

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

Request the client to run an LLM completion (sampling).

Sends a sampling/createMessage request and awaits the generated message. This requires the client to have declared the sampling capability (sampling is available in every protocol version).

Errors

Returns an error if the client did not declare sampling support, the request was cancelled or timed out, or the response could not be parsed.

Trait Implementations

impl Debug for Context<'_>

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

Formats the value using the given formatter.