Extensão Tasks do MCP para Tools de Longa Duração
Objective
Uma tool que leva 6 segundos, ou 6 minutos, não cabe numa única resposta HTTP:
qualquer timeout, proxy ou conexão derrubada perde o trabalho, e a spec 2026-07-28
removeu a resumabilidade SSE que antes amenizava isso. A resposta é a extensão Tasks
(io.modelcontextprotocol/tasks, SEP-2663): o servidor devolve na hora um handle
durável e o cliente faz polling em tasks/get, manda input com tasks/update e
cancela com tasks/cancel. Esta lição mede tudo num servidor Streamable HTTP de
verdade: o fio, os três modos de execução, o que um cliente sem a extensão enxerga,
cancelamento, erros, TTL, reinício do servidor e idempotência.
Versões: ModelContextProtocol.AspNetCore 2.4.0 e
ModelContextProtocol.Extensions.Tasks 2.4.0 (resolvidas com dotnet list package), spec 2026-07-28, TFM net10.0, SDK 10.0.100. O pacote de tasks é estável
(sem aviso MCPEXP ao compilar; as notas da 2.0.0 listam "Stabilize official
Extensions, Tasks, and MRTR APIs"). Nenhum modelo é usado.
Use Cases
- Uma tool que embrulha relatório, exportação, build ou job em lote que passa de um timeout HTTP normal.
- Uma tool que precisa pausar para uma aprovação humana no meio do trabalho.
- Um cliente que sobrevive ao próprio reinício retomando de um id de task guardado, e o que fazer com um cliente que não fala a extensão.
Deep Dive
O problema: uma resposta é um lugar ruim para 6 segundos
A tool build_report dorme 6 segundos e registra o início e o fim. Um cliente cujo
HttpClient.Timeout é de 3 segundos a chama de forma simples e depois como task:
textplain call, 3 s HTTP timeout: TaskCanceledException after 3026 ms task call, same 3 s timeout: report T ready (run #6) after 6049 ms
O log do servidor mostra run #5 started, nunca finished, e uma
TaskCanceledException: quando o stream da resposta quebra, o trabalho para junto.
A spec diz isso: "A broken response stream loses the in-flight request; clients MUST
re-issue it as a new request with a new request ID", porque os ids de evento SSE e o
Last-Event-ID foram removidos. A chamada como task sobrevive ao mesmo timeout
porque nenhuma request isolada dura mais que alguns milissegundos. O básico de
cliente e servidor está no concept "MCP Servers and Clients with the C# SDK".
Servidor: uma linha e um store
csharp// one store for the whole process: stateless HTTP builds a server per request
var store = new InMemoryMcpTaskStore { DefaultPollIntervalMs = 1000 };
builder.Services.AddMcpServer()
.WithHttpTransport()
.WithTools<LabTools>()
.WithTasks(store); // package ModelContextProtocol.Extensions.Tasks
app.MapMcp("/mcp");
[McpServerTool(Name = "build_report"), Description("Builds a report. Takes 6 seconds.")]
public static async Task<string> BuildReport(string name, CancellationToken ct)
{
await Task.Delay(TimeSpan.FromSeconds(6), ct); // ct fires on tasks/cancel
return $"report {name} ready";
}WithTasks registra os handlers de tasks/get, tasks/update e tasks/cancel,
anuncia a extensão (o server/discover passa a listar
"extensions":{"io.modelcontextprotocol/tasks":{}}) e embrulha cada
[McpServerTool]: o corpo roda em segundo plano e a chamada devolve um handle. O
código da tool não muda. O store precisa ser compartilhado entre requests (singleton
ou armazenamento externo), senão um poll num servidor novo o encontra vazio.
No fio: o handle e depois o polling
O cliente declara a extensão no _meta de cada request (abreviado aqui). O servidor
decide se responde com uma task; o cliente nunca pede uma.
text--> POST Mcp-Method=tools/call Mcp-Name=build_report {"method":"tools/call","params":{"name":"build_report","arguments":{"name":"Q3"},"_meta":{"io.modelcontextprotocol/clientCapabilities":{"extensions":{"io.modelcontextprotocol/tasks":{}}},...}},"id":2,...} <-- 200 (after 15 ms) {"result":{"taskId":"ba0dbdbb574f46f9965f17a5dee762ff","status":"working","createdAt":"2026-11-19T00:11:09.53+00:00","lastUpdatedAt":"...","pollIntervalMs":1000,"resultType":"task",...},"id":2} --> POST Mcp-Method=tasks/get Mcp-Name=ba0dbdbb574f46f9965f17a5dee762ff (every 1000 ms) <-- {"result":{"resultType":"complete","taskId":"a12a...","status":"working",...,"pollIntervalMs":1000},...} <-- (6 s later) {"result":{"resultType":"complete","taskId":"a12a...","status":"completed","lastUpdatedAt":"...","result":{"content":[{"type":"text","text":"report Q3 ready (run #2)"}]}},...}
resultType: "task" avisa que isto é um handle, não um CallToolResult, e o
Mcp-Name leva o id da task em toda chamada de task, para um load balancer rotear
por task. O lado do cliente tem dois helpers:
csharpvar raw = await client.CallToolAsTaskAsync(new() { Name = "build_report", Arguments = args });
if (raw.IsTask) // ResultOrCreatedTask<CallToolResult>
while (await client.GetTaskAsync(raw.TaskCreated!.TaskId) is WorkingTaskResult)
await Task.Delay((int)(raw.TaskCreated.PollIntervalMs ?? 1000));
// or, to hide the lifecycle:
CallToolResult r = await client.CallToolWithPollingAsync(new() { Name = "build_report", Arguments = args });GetTaskResult é uma hierarquia (WorkingTaskResult, InputRequiredTaskResult,
CompletedTaskResult com Result, FailedTaskResult com Error,
CancelledTaskResult). CallToolWithPollingAsync levou 6042 ms para o mesmo texto.
Modos de execução e o cliente sem a extensão
Desde a 2.0.0-rc.2 o servidor escolhe um modo por chamada com McpTasksOptions.ExecutionModeSelector:
csharp.WithTasks(store, o => o.ExecutionModeSelector = ctx => ctx.Params?.Name switch
{
"quick_lookup" => McpTaskExecutionMode.Synchronous, // never a task
"nightly_export" => McpTaskExecutionMode.Required, // only for clients with the extension
_ => McpTaskExecutionMode.Optional, // the default: task if the client opted in
});| Chamada | Resultado medido |
|---|---|
CallToolAsync("build_report") simples (Optional, sem extensão) |
bloqueou 6023 ms, CallToolResult normal, IsError nulo |
CallToolAsync("nightly_export") simples (Required, sem extensão) |
HTTP 400, JSON-RPC -32021 "requires the 'io.modelcontextprotocol/tasks' client extension capability", data.requiredCapabilities nomeia a extensão |
CallToolAsTaskAsync("quick_lookup") (Synchronous, com extensão) |
IsTask=False, value-of-x inline |
CallToolWithPollingAsync("nightly_export") (Required, com extensão) |
uma task, termina com export done |
cliente fixado em ProtocolVersion = "2025-11-25" mais o helper |
IsTask=False, bloqueou 6024 ms (o helper só envia o opt-in na 2026-07-28 ou superior) |
GetTaskAsync nessa conexão 2025-11-25 |
o cliente lança InvalidOperationException: exige 2026-07-28 ou superior |
GetTaskAsync("no-such-id") |
McpProtocolException: Unknown task: 'no-such-id' |
Ou seja, um cliente sem a extensão vê a tool bloquear em Optional (com o problema
de timeout acima) e um -32021 claro em Required. Não executado: um McpClientTool
sob UseFunctionInvocation(); usa a chamada simples, então deve bloquear.
Input no meio: tasks/update
Quando a tool chama server.ElicitAsync dentro de uma task, o SDK transforma isso
numa entrada de inputRequests em vez de uma request iniciada pelo servidor. A tool:
csharp[McpServerTool(Name = "deploy")]
public static async Task<string> Deploy(McpServer server, string service, CancellationToken ct)
{
var ask = await server.ElicitAsync<Confirm>($"Deploy {service} to production?", cancellationToken: ct);
return ask.IsAccepted && ask.Content!.Approve ? $"{service} deployed" : $"{service} NOT deployed ({ask.Action})";
}Um poll manual vê a mudança, responde com tasks/update pela chave da request e
continua o polling (fio, abreviado):
text<-- tasks/get {"result":{"status":"input_required","inputRequests":{"808e235d74b140a89060319db0a5080a":{"method":"elicitation/create","params":{"mode":"form","message":"Deploy billing to production?","requestedSchema":{"type":"object","properties":{"approve":{"type":"boolean"}}}}}},...}} --> tasks/update {"params":{"taskId":"4012f347...","inputResponses":{"808e235d74b140a89060319db0a5080a":{"action":"accept","content":{"approve":true}}}},...} <-- {"result":{"resultType":"complete"},...} (empty acknowledgement) <-- tasks/get {"result":{"status":"completed","result":{"content":[{"type":"text","text":"billing deployed"}]}}}
CallToolWithPollingAsync faz isso quando o cliente registrou
McpClientOptions.Handlers.ElicitationHandler (medido: search deployed). A chave é
única na vida da task e o cliente a deduplica entre polls. Pela documentação do SDK
(não executado), sampling funciona igual e roots/list ainda não é despachado. A
elicitation em si está no concept "MCP Multi Round-Trip Requests and Elicitation".
Cancelamento é cooperativo
tasks/cancel devolve uma confirmação vazia e dispara o CancellationToken da tool.
Cancelando build_report depois de 1,5 s:
textafter cancel +500 ms: cancelled (same at +1000 and +1500 ms) cancel on an already cancelled task: ack ok, state: cancelled
O log do servidor tem run #7 started e nenhum finished: o Task.Delay(…, ct) foi
interrompido. Uma tool que ignora o ct continua rodando (não executado), e a spec
permite um status final diferente de cancelled. Não use notifications/cancelled.
Failed contra completed com isError
textexplode: completed result={"content":[{"type":"text","text":"An error occurred invoking 'explode'."}],"isError":true} explode_protocol: failed error={"code":-32602,"message":"bad request detected late"} CallToolWithPollingAsync threw McpException: Task '...' failed: {"code":-32602,...}
Uma exceção comum vira task completed com isError: true (mesma regra de texto do
caminho síncrono; o CallToolWithPollingAsync a devolve normalmente). Só um erro
JSON-RPC (McpProtocolException) deixa a task failed, e aí o helper lança.
TTL e reinício do servidor: o store em memória esquece
InMemoryMcpTaskStore.DefaultTimeToLive (nulo por padrão) aparece como ttlMs no
handle ("ttlMs":5000). O TTL conta a partir da criação, não da conclusão. Com TTL
de 5 s e polling uma vez por segundo:
textbuild_report (6 s): +1.0s..+4.0s working, +5.0s Unknown task (the tool still ran to "finished") nightly_export (2 s): +2.0s..+4.0s completed, +5.0s Unknown task
Sem TTL o store guarda toda task até o processo terminar, e um reinício perde todas ("not persisted across process restarts", segundo a documentação):
textstarted 70c364f934f74a268d809931434013df; process exits now (client process 1) resumed 70c364f9...: working (a brand new client process, same server) (server killed) HttpRequestException: Connection refused (127.0.0.1:5940) (server restarted) resumed 70c364f9...: McpProtocolException: Unknown task: '70c364f9...'
O handle sobrevive ao reinício do cliente (se ele guardou o id), mas não ao do
servidor. Em produção implemente IMcpTaskStore sobre banco ou cache
(CreateTaskAsync durável antes de retornar, transições terminais idempotentes,
ResolveInputRequestsAsync disparando InputResponseReceived; só documentação, sem
store próprio escrito aqui). O corpo de uma tool num processo morto se perde qualquer
que seja o store, então o trabalho precisa ser retomável ou seguro de repetir.
Idempotência continua sendo problema seu
O handle torna o resultado durável, não a chamada única. Mesmos argumentos duas vezes:
textsame arguments twice: ids differ = True, t1 ran as run #8, t2 as run #9
Dois ids, duas execuções. Um cliente que perdeu o CreateTaskResult (a única resposta
ainda numa request só) tenta de novo e começa um segundo job: ponha uma chave de
idempotência nos argumentos e deduplique na tool (veja o concept "Transactional
Outbox, Inbox and Idempotent Consumers").
Livro contra hoje e o que o SDK ainda não faz
As Tasks experimentais da spec 2025-11-25 (SDK 1.3 e 1.4) tinham tasks/list, um
tasks/result bloqueante e um taskSupport por tool; tudo saiu, e peers v1 e v2 não
interoperam (cada um vê um resultado comum). Pela documentação do SDK,
notifications/tasks não está implementado na 2.4.0, então só há polling, e uma tool
não pode começar inline e virar task no meio. A spec diz que a extensão deve entrar
no protocolo núcleo quando estabilizar.
Trade-offs
- Polling contra conexão presa. Polling custa uma request por intervalo e até um intervalo de latência, mas dispensa stream longo e atravessa proxies.
pollIntervalMsé uma dica que o servidor pode impor com rate limit. - Optional contra Required.
Optionaldegrada para bloqueio nos clientes antigos e esconde o problema de timeout;Requiredfalha rápido com-32021. Uma exportação de 20 minutos deve serRequired. - Store em memória contra o seu.
InMemoryMcpTaskStoreserve para desenvolvimento e testes; o que o cliente espera de verdade precisa de store durável e política de limpeza. - TTL. Curto demais e o resultado de um job lento é descartado antes de o cliente buscá-lo (o job de 6 s com TTL de 5 s); longo demais ou nulo e o store cresce.
- O id da task como capability. Sem
tasks/liste sem sessões, o id é o único handle (os do SDK são 32 dígitos hex aleatórios); amarre-o ao chamador num store próprio.