Interface IMcpTaskStore

Namespace

ModelContextProtocol.Server

Assembly

ModelContextProtocol.Core.dll

Provides an interface for storing and managing the lifecycle of MCP tasks.

public interface IMcpTaskStore

Remarks

The task store manages the state of tasks created by the server's request handling pipeline. When a client signals support for the io.modelcontextprotocol/tasks extension on a request, the server creates a task in the store, executes the work in the background, and stores the result upon completion.

Implementations must be thread-safe. The store also provides the backing implementation for tasks/get, tasks/update, and tasks/cancel protocol methods.

Lifetime under stateless HTTP: when the server is configured for stateless HTTP (each request creates a fresh server instance), the same IMcpTaskStore instance MUST be shared across requests — either by registering the store as a singleton in the DI container, or by backing it with external storage (database, distributed cache, etc.) that every server instance can reach. Otherwise tasks/get polls issued on subsequent requests will see an empty in-memory store and never find the task they are polling for.

See the SEP-2663 specification for details on the tasks extension.

Methods

CreateTaskAsync(CancellationToken)

Creates a new task for tracking an asynchronous execution.

Task<McpTaskInfo> CreateTaskAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<McpTaskInfo>

A McpTaskInfo with a unique task ID, initial status of Working, and timing metadata (TTL, poll interval).

Remarks

Implementations must generate a unique task ID and set appropriate timestamps. The server infrastructure maps the returned McpTaskInfo to the appropriate protocol response type when communicating with clients.

Per the MCP specification (SEP-2663 §306), the returned task MUST be durably created before this method completes: a subsequent GetTaskAsync(string, CancellationToken) with the returned TaskId MUST resolve, even if it runs on a different process or node. Implementations backed by eventually-consistent storage must therefore wait for the write to be visible (e.g., quorum acknowledgement, write-through, or an equivalent barrier) before returning.

GetTaskAsync(string, CancellationToken)

Retrieves the current state of a task.

Task<McpTaskInfo?> GetTaskAsync(string taskId, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task to retrieve.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<McpTaskInfo>

A McpTaskInfo representing the current task state, or null if the task does not exist.

ResolveInputRequestsAsync(string, IDictionary<string, InputResponse>, CancellationToken)

Removes input requests that have been satisfied by the provided responses and raises InputResponseReceived for each resolved entry.

Task ResolveInputRequestsAsync(string taskId, IDictionary<string, InputResponse> inputResponses, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task.

inputResponses IDictionary<string, InputResponse>

The input responses keyed by the original request identifier. Matched input requests are removed from the task's pending set.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task

Remarks

After removing the satisfied requests, if no pending input requests remain the task transitions back to Working. Otherwise it remains in InputRequired.

Implementations must raise InputResponseReceived for each entry in inputResponses after updating the store state. In distributed deployments, this event enables the originating server to be notified even if a different server instance processes the tasks/update request.

SetCancelledAsync(string, CancellationToken)

Transitions the task to Cancelled.

Task<bool> SetCancelledAsync(string taskId, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task to cancel.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<bool>

true if the task was successfully cancelled; false if the task does not exist or was already in a terminal state.

SetCompletedAsync(string, JsonElement, CancellationToken)

Stores the result of a completed execution, transitioning the task to Completed.

Task SetCompletedAsync(string taskId, JsonElement result, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task.

result JsonElement

The serialized result payload.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task

A task representing the asynchronous operation.

SetFailedAsync(string, JsonElement, CancellationToken)

Marks a task as failed, transitioning it to Failed.

Task SetFailedAsync(string taskId, JsonElement error, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task.

error JsonElement

The serialized error information.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task

A task representing the asynchronous operation.

SetInputRequestsAsync(string, IDictionary<string, InputRequest>, CancellationToken)

Adds input requests to a task, transitioning it to InputRequired.

Task SetInputRequestsAsync(string taskId, IDictionary<string, InputRequest> inputRequests, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task.

inputRequests IDictionary<string, InputRequest>

The input requests to add. Keys are arbitrary identifiers for matching requests to responses. Each value is an InputRequest wrapping the server-to-client request payload. New requests are merged with any existing pending requests.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task

A task representing the asynchronous operation.

Events

InputResponseReceived

Occurs when an input response is resolved for a task.

event Action<InputResponseReceivedEventArgs>? InputResponseReceived

Event Type

Action<InputResponseReceivedEventArgs>

Remarks

Implementations must raise this event for each input response resolved in ResolveInputRequestsAsync(string, IDictionary<string, InputResponse>, CancellationToken). Subscribers use this to complete pending input request waiters (e.g., elicitation or sampling calls that are awaiting a client response).