Interface IMcpTaskStore

Namespace

ModelContextProtocol

Assembly

ModelContextProtocol.Core.dll

Provides an interface for pluggable task storage implementations in MCP servers.

[Experimental("MCPEXP001", UrlFormat = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp001")]
public interface IMcpTaskStore

Remarks

The task store is responsible for managing the lifecycle of tasks, including creation, status updates, result storage, and retrieval. Implementations must be thread-safe and may support session-based isolation for multi-session scenarios.

TTL (Time To Live) Management: Implementations may override the requested TTL value in TimeToLive to enforce resource limits. The actual TTL used is returned in the TimeToLive property. A null TTL indicates unlimited lifetime. Tasks may be deleted after their TTL expires, regardless of status.

Methods

CancelTaskAsync(string, string?, CancellationToken)

Attempts to cancel a task, transitioning it to Cancelled status.

Task<McpTask> CancelTaskAsync(string taskId, string? sessionId = null, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task to cancel.

sessionId string

Optional session identifier for access control.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<McpTask>

The updated McpTask. If the task is already in a terminal state (Completed, Failed, or Cancelled), the task is returned unchanged.

Remarks

This method must be idempotent. If called on a task that is already in a terminal state, it returns the current task without error. This behavior differs from the MCP specification but ensures idempotency and avoids race conditions between cancellation and task completion.

For tasks not in a terminal state, the implementation should attempt to stop the underlying operation and transition the task to Cancelled status before returning.

CreateTaskAsync(McpTaskMetadata, RequestId, JsonRpcRequest, string?, CancellationToken)

Creates a new task for tracking an asynchronous operation.

Task<McpTask> CreateTaskAsync(McpTaskMetadata taskParams, RequestId requestId, JsonRpcRequest request, string? sessionId = null, CancellationToken cancellationToken = default)

Parameters

taskParams McpTaskMetadata

Metadata for the task, including requested TTL.

requestId RequestId

The JSON-RPC request ID that initiated this task.

request JsonRpcRequest

The original JSON-RPC request that triggered task creation.

sessionId string

Optional session identifier for multi-session isolation.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<McpTask>

A new McpTask with a unique task ID, initial status of Working, and the actual TTL that will be used (which may differ from the requested TTL).

Remarks

Implementations must generate a unique task ID and set the CreatedAt and LastUpdatedAt timestamps. The implementation may override the requested TTL to enforce storage limits.

GetTaskAsync(string, string?, CancellationToken)

Retrieves a task by its unique identifier.

Task<McpTask?> GetTaskAsync(string taskId, string? sessionId = null, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task to retrieve.

sessionId string

Optional session identifier for access control.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<McpTask>

The McpTask if found and accessible, otherwise null.

Remarks

Returns null if the task does not exist or if session-based access control denies access.

GetTaskResultAsync(string, string?, CancellationToken)

Retrieves the stored result of a completed or failed task.

Task<JsonElement> GetTaskResultAsync(string taskId, string? sessionId = null, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task.

sessionId string

Optional session identifier for access control.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<JsonElement>

The stored operation result as a JSON element.

Remarks

This method should only be called on tasks in terminal states (Completed or Failed). The result contains the JSON representation of the original operation result (e.g., CallToolResult for tools/call).

ListTasksAsync(string?, string?, CancellationToken)

Lists tasks with pagination support.

Task<ListTasksResult> ListTasksAsync(string? cursor = null, string? sessionId = null, CancellationToken cancellationToken = default)

Parameters

cursor string

Optional cursor for pagination, from a previous call's nextCursor value.

sessionId string

Optional session identifier for filtering tasks by session.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<ListTasksResult>

A ListTasksResult containing the tasks and an optional cursor for the next page.

Remarks

When sessionId is provided, implementations should filter to only return tasks associated with that session. The cursor format is implementation-specific.

StoreTaskResultAsync(string, McpTaskStatus, JsonElement, string?, CancellationToken)

Stores the final result of a task that has reached a terminal status.

Task<McpTask> StoreTaskResultAsync(string taskId, McpTaskStatus status, JsonElement result, string? sessionId = null, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task.

status McpTaskStatus

The terminal status: Completed or Failed.

result JsonElement

The operation result to store as a JSON element.

sessionId string

Optional session identifier for access control.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<McpTask>

A task representing the asynchronous operation.

Remarks

The status must be either Completed or Failed. This method updates the task status and stores the result for later retrieval via GetTaskResultAsync(string, string?, CancellationToken).

Implementations should throw InvalidOperationException if called on a task that is already in a terminal state, to prevent result overwrites.

UpdateTaskStatusAsync(string, McpTaskStatus, string?, string?, CancellationToken)

Updates the status and optional status message of a task.

Task<McpTask> UpdateTaskStatusAsync(string taskId, McpTaskStatus status, string? statusMessage, string? sessionId = null, CancellationToken cancellationToken = default)

Parameters

taskId string

The unique identifier of the task.

status McpTaskStatus

The new status to set.

statusMessage string

Optional diagnostic message describing the status change.

sessionId string

Optional session identifier for access control.

cancellationToken CancellationToken

Cancellation token for the operation.

Returns

Task<McpTask>

A task representing the asynchronous operation.

Remarks

This method updates the task's Status, StatusMessage, and LastUpdatedAt properties. Common uses include transitioning to Cancelled, InputRequired, or updating progress messages while in Working status.