MCP Tasks no Claude Code: tarefas em segundo plano e Elicitation

Para usar MCP Tasks no Claude Code, conecte um servidor MCP compatível com Tasks e invoque sua ferramenta na conversa principal da CLI no terminal, na versão v2.1.304 ou posterior. O servidor aceita o trabalho, Claude continua trabalhando e o resultado chega quando a tarefa termina. Antes de alterar o servidor, confira os requisitos: uma chamada comum transferida automaticamente para segundo plano após dois minutos usa outro mecanismo.

Em 2026-10-24, a documentação do Claude Code apresenta MCP Tasks como uma funcionalidade em beta público. Este guia aborda a revisão 2026-07-28 do protocolo e as condições que determinam se uma chamada pode se tornar uma tarefa.

Para que servem Tasks e Elicitation

Use Tasks para operações demoradas que o servidor consegue aceitar e acompanhar de forma independente, como builds, testes, exportações ou pesquisas. Use Elicitation quando o servidor precisa de uma decisão ou de informações suas para continuar.

Três comportamentos podem parecer semelhantes:

Mecanismo	O que acontece	O que o servidor precisa implementar
Chamada MCP comum	Claude aguarda o resultado da ferramenta.	Uma implementação normal da ferramenta.
Transferência automática para segundo plano	Uma chamada da conversa principal que ainda está em execução após dois minutos passa para segundo plano. O resultado chega depois, mas essa chamada não é preservada ao sair da sessão.	Não exige suporte a Tasks.
MCP Task	Ao aceitar o trabalho, o servidor retorna um handle: um objeto com o identificador e o estado da tarefa. O Claude Code acompanha essa referência e obtém o resultado. Trabalhos em servidores remotos podem continuar após a saída da CLI.	A extensão Tasks e o armazenamento persistente das tarefas.

Elicitation é uma funcionalidade separada. Uma ferramenta de relatórios pode perguntar qual ambiente consultar e, depois, executar a exportação como uma Task. Uma ferramenta rápida pode pedir o mesmo esclarecimento sem criar uma tarefa.

Elicitation também é anterior a este lançamento: a versão v2.1.76 do Claude Code introduziu os diálogos de solicitação de dados e os hooks Elicitation e ElicitationResult. A novidade aqui são as Tasks gerenciadas pelo servidor.

Confira se sua chamada pode se tornar uma MCP Task

Todas as condições da lista oficial de requisitos precisam ser atendidas. Instalar uma CLI mais recente resolve apenas a primeira linha.

Verificação	Condição necessária
Versão do Claude Code	v2.1.304 ou posterior.
Implementação do servidor	O servidor oferece suporte à extensão Tasks. Uma conexão MCP, por si só, não comprova esse suporte.
Transporte e protocolo	Um servidor HTTP, stdio ou de um conector claude.ai conectado pela revisão 2026-07-28 do protocolo.
Configurações de compatibilidade antiga	Nem MCP_SDK_GENERATION=v1 nem MCP_PROTOCOL_NEGOTIATION=legacy podem estar forçando a conexão a usar o protocolo antigo.
Disponibilidade do recurso	A sessão busca feature flags, que controlam a disponibilidade dos recursos, e a Anthropic habilita Tasks para esse tipo de sessão.
Ambiente compatível	CLI no terminal, Agent SDK ou GitHub Actions. A extensão do VS Code e o aplicativo desktop ainda não oferecem suporte a MCP Tasks.
Origem da chamada	A chamada parte da conversa principal. Chamadas feitas por subagentes não se tornam MCP Tasks.
Modo de entrada	Uma sessão interativa ou uma sessão do Agent SDK ou com entrada em streaming que atenda aos requisitos abaixo.

Para uso não interativo, uma sessão do Agent SDK ou uma execução de claude -p com --input-format stream-json também exige:

• CLAUDE_AUTO_BACKGROUND_TASKS=1
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND diferente de 1
• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS diferente de 0

Mantenha o fluxo de entrada aberto: a execução não espera pelas MCP Tasks depois que a entrada é fechada. Uma invocação única de claude -p "..." não recebe Tasks. O suporte ao GitHub Actions não elimina esses requisitos do modo de entrada.

A referência de variáveis de ambiente identifica configurações que bloqueiam a busca de flags:

• DISABLE_GROWTHBOOK=1 ou true
• DO_NOT_TRACK=1
• Qualquer valor não vazio em DISABLE_TELEMETRY
• Qualquer valor não vazio em CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

Nas duas últimas variáveis, até 0 ou false ativa o bloqueio correspondente. Sessões comuns com provedores terceiros, incluindo Amazon Bedrock, também não buscam flags. A referência documenta uma exceção para integrações incorporadas nas quais o aplicativo hospedeiro gerencia o provedor.

Inspecione o ambiente de inicialização e as configurações efetivamente aplicadas. Os arquivos habituais são ~/.claude/settings.json, .claude/settings.json e .claude/settings.local.json; configurações gerenciadas também podem se aplicar. A referência de configurações explica o escopo de cada uma.

Remover uma configuração de compatibilidade antiga não atualiza um servidor que não implementa o novo protocolo. Da mesma forma, compatibilidade de API por um gateway não comprova a capacidade de buscar feature flags. Se sua implantação precisa manter uma configuração que bloqueia Tasks, use chamadas comuns de ferramentas.

Em sessões interativas, CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0 faz Claude esperar. CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1 também o faz aguardar Tasks, embora a transferência automática comum possa mover uma chamada demorada para segundo plano depois. Apenas CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 não obriga MCP Tasks a permanecerem em primeiro plano.

Execute uma tarefa e confira o resultado

Comece com um servidor cuja autenticação já esteja concluída e cuja documentação ou implementação confirme o suporte a Tasks. Em seguida, experimente uma operação não destrutiva. No Bash, confira a instalação e os servidores configurados antes de abrir a CLI interativa:

claude --version
claude mcp list
claude

Se sua instalação tiver atualização integrada e estiver abaixo da versão mínima, execute claude update e confira novamente. Esses comandos estão descritos na referência da CLI.

Dentro do Claude Code, use /mcp para confirmar a conexão com o servidor e concluir qualquer autenticação necessária. Se houver uma ferramenta de execução de testes conectada, um pedido útil é:

Execute a suíte de testes deste repositório pela ferramenta MCP, a partir da conversa principal. Enquanto os testes rodam, explique a organização deles com base no README. Ao terminar, informe o resultado e as falhas encontradas.

Verifique o comportamento em dois níveis:

1. No Claude Code: procure o contador de tarefas MCP e inspecione /tasks. Uma entrada em /tasks, por si só, não basta: chamadas comuns em segundo plano também aparecem ali.
2. Nos registros de rastreamento do servidor: confirme que tools/call retornou resultType: "task" e que as solicitações seguintes de tasks/get usam o mesmo taskId.

Ao concluir a tarefa, o Claude Code recebe o resultado; peça a Claude que o apresente. Se Claude estiver ocioso, poderá processá-lo automaticamente. Se a chamada continuar sendo comum, confira as capacidades declaradas na solicitação real e a lista de requisitos antes de reescrever a ferramenta.

Para autores de servidores: retorne o handle e entregue o resultado

Implemente a extensão Tasks atual, em vez de copiar um exemplo experimental antigo. As mudanças do MCP 2026-07-28 substituíram tasks/result por consultas periódicas com tasks/get, adicionaram tasks/update e removeram tasks/list.

Retorne uma tarefa somente quando a solicitação permitir

Confira a capacidade em cada solicitação, no caminho:

params._meta["io.modelcontextprotocol/clientCapabilities"].extensions["io.modelcontextprotocol/tasks"]

O valor é {}. Seu servidor anuncia a extensão correspondente em capabilities.extensions, na resposta a server/discover. A visão geral da extensão Tasks documenta os dois locais.

Quando o cliente declara suporte, o servidor decide se aquela operação específica deve se tornar uma Task. Sem essa capacidade, retorne um resultado comum quando possível. Se a operação exigir Tasks, a extensão define o erro de capacidade ausente -32021; não retorne um handle de tarefa a um cliente que não declarou suporte.

Persista a tarefa antes de responder, para que seu identificador já possa ser consultado por tasks/get. Mantenha a tarefa acessível entre conexões e verifique a autenticação e o acesso a ela nas solicitações seguintes.

Esta resposta JSON-RPC ilustrativa aceita um build. O identificador, os horários e o resultado final são exemplos, não um registro de execução:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "task",
    "taskId": "6f17bfa2-4c5e-4d21-b563-2f7e83a902bc",
    "status": "working",
    "createdAt": "2026-10-24T08:00:00Z",
    "lastUpdatedAt": "2026-10-24T08:00:00Z",
    "ttlMs": 3600000,
    "pollIntervalMs": 5000
  }
}

Os campos da tarefa ficam diretamente dentro de result no JSON-RPC. Não há um objeto task adicional envolvendo esses campos, e o handle inicial não precisa de um array content.

Campo	Requisito
resultType	"task" na resposta inicial da tarefa.
taskId	Obrigatório, gerado pelo servidor e difícil de adivinhar. O Claude Code também limita o valor a 128 caracteres ASCII imprimíveis, sem espaços.
status	Obrigatório: working, input_required, completed, failed ou cancelled.
createdAt, lastUpdatedAt	Strings obrigatórias com data e hora no formato ISO 8601.
ttlMs	Número inteiro obrigatório de milissegundos contados desde a criação, ou null para retenção sem limite. Não é uma estimativa da duração do trabalho.
pollIntervalMs	Intervalo opcional de consulta, em milissegundos inteiros; não envie null.
statusMessage	Texto opcional de progresso ou estado.

O schema publicado da extensão define a estrutura. A validação específica do Claude Code está documentada na referência para autores de servidores.

Se Claude informar Unsupported result type 'task' for tools/call, confira se a solicitação recebida incluía a extensão. Depois, verifique se nenhum dos campos taskId, status, createdAt, lastUpdatedAt ou ttlMs está ausente. Um valor de status não aceito produz o mesmo erro. Já um identificador de tarefa inválido produz um erro de handle malformado.

Coloque o resultado final da ferramenta em tasks/get

Responda a cada consulta com o estado atual da tarefa. Uma resposta bem-sucedida de tasks/get usa resultType: "complete" mesmo quando o status do trabalho continua sendo working: a solicitação de consulta terminou, mas o trabalho não necessariamente.

Para o build ilustrativo acima, a resposta de conclusão é:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "taskId": "6f17bfa2-4c5e-4d21-b563-2f7e83a902bc",
    "status": "completed",
    "createdAt": "2026-10-24T08:00:00Z",
    "lastUpdatedAt": "2026-10-24T08:03:00Z",
    "ttlMs": 3600000,
    "result": {
      "resultType": "complete",
      "content": [
        {
          "type": "text",
          "text": "Build completed successfully."
        }
      ]
    }
  }
}

O result aninhado contém o resultado normal da ferramenta. Um erro da ferramenta com isError: true ainda pertence a uma tarefa completed; failed é reservado a um erro de execução JSON-RPC, informado em error.

Implemente também tasks/cancel, mas trate a operação como uma solicitação de cancelamento que depende da cooperação do servidor. A especificação da extensão não garante a interrupção de um trabalho já iniciado. O Claude Code atualmente obtém os resultados por consultas periódicas; portanto, não dependa de notifications/tasks para entregar o resultado.

Use Elicitation para decisões que a ferramenta não pode tomar

Peça o ambiente, o destino ou a aprovação que faltam antes de executar a ação dependente dessa resposta. Elicitation em modo de formulário coleta campos estruturados. O modo URL oferece um fluxo no navegador, como o login em um serviço externo.

Durante uma Task, apresente a pergunta por tasks/get, com status: "input_required" e um mapa inputRequests. Cada entrada usa uma chave única e contém o method solicitado, como elicitation/create, além de seus params. O Claude Code envia a resposta por tasks/update, usando as chaves correspondentes em inputResponses.

Na CLI interativa, feche /tasks se a pergunta estiver escondida atrás dessa tela. Recusar ou pressionar Esc responde à solicitação de dados; o servidor decide se o trabalho continua.

Se uma Task solicitar dados do usuário em uma sessão não interativa, o Claude Code pedirá ao servidor que a cancele, sem executar hooks Elicitation nem chamar o callback onElicitation do Agent SDK. Forneça as escolhas necessárias antes de iniciar uma execução sem supervisão ou use uma sessão interativa. Essa restrição é específica às solicitações de dados feitas por MCP Tasks.

Audite também os hooks antes de considerar uma resposta de Elicitation como aprovação humana. A referência de hooks documenta que:

• Elicitation pode responder automaticamente e impedir a exibição do diálogo.
• ElicitationResult pode alterar a resposta do usuário e, se implementado incorretamente, até substituir uma recusa por aceitação.
• ElicitationResult não é executado quando um hook Elicitation já respondeu.

Revise os hooks efetivamente aplicados pelas configurações do usuário, do projeto, locais, gerenciadas e de plugins. Conferir apenas o arquivo de configurações do repositório pode deixar de fora o hook que fornece a resposta.

O que acontece ao parar, sair, limpar ou retomar a sessão?

Pare uma Task remota explicitamente se quiser solicitar seu cancelamento; sair da CLI não faz isso. O ciclo de vida documentado distingue a execução no servidor do acompanhamento feito pelo Claude Code.

Ação	Resultado e próximo passo
Selecionar a Task em /tasks e pressionar x, ou pedir a Claude que a pare	O Claude Code deixa de acompanhá-la e solicita o cancelamento. O servidor ainda pode concluir o trabalho.
Pressionar Esc durante uma interação comum	Isso não interrompe uma Task em segundo plano.
Sair enquanto uma Task remota está em execução	O trabalho continua no servidor. Retome a sessão original para acompanhá-lo novamente.
Sair com uma Task em um servidor stdio	O processo local do servidor para. Não presuma que o trabalho continuará, a menos que o servidor ofereça explicitamente execução independente desse processo.
Usar /clear, /branch ou trocar de sessão com /resume mantendo o Claude Code aberto	O resultado pode chegar à conversa atual. Depois de sair, retome a sessão na qual a Task foi iniciada.
Retomar a sessão original de forma interativa	O acompanhamento volta após a reconexão do servidor, desde que ele ainda reconheça a Task. Mantenha o nome e as configurações de conexão do servidor.
Iniciar outra sessão ou usar --fork-session	A nova sessão não herda o acompanhamento da Task.
Retomar por uma invocação única de claude -p	Essa execução não acompanha a Task; use a retomada interativa ou uma entrada em streaming que cumpra os requisitos.

Se o servidor estiver desconectado, reconecte-o por /mcp antes de parar a Task. Caso contrário, nenhuma solicitação de cancelamento chegará ao servidor, e o Claude Code esquecerá a tarefa.

Use claude --resume para selecionar a conversa original. A política de retenção do servidor continua sendo relevante: retomar uma sessão não recupera um resultado que o servidor já descartou.

Um prompt para auditar sua configuração MCP

Faça uma auditoria somente de leitura para identificar a menor alteração útil antes de modificar servidores ou configurações. Este prompt adapta a sugestão de auditoria MCP de @Voxyz_ai, acrescentando verificações do formato atual das respostas e do comportamento de sessões com entrada em streaming.

Goal: Audit my Claude Code MCP setup for Tasks and Elicitation.

Read the current official documentation:
https://code.claude.com/docs/en/mcp
https://code.claude.com/docs/en/env-vars
https://code.claude.com/docs/en/hooks
https://modelcontextprotocol.io/extensions/tasks/overview

Scope: Inspect connected MCP servers, their configuration, effective settings, and any MCP server implementation in this repository. Say explicitly if no server implementation is present. Keep credential values out of the report.

Check:
1. Long-running tools: identify builds, test runs, exports, or research that could benefit from Tasks. For my server code, recommend the smallest change to return a valid task handle, persist it across connections, and deliver the final result through tasks/get. For third-party servers, cite evidence for the deployed version's support; otherwise mark support unknown.
2. Eligibility: check the CLI version, transport, actual protocol revision, per-request Tasks capability, feature-flag fetching, provider, supported surface, main conversation versus subagents, and input mode. Include MCP_SDK_GENERATION, MCP_PROTOCOL_NEGOTIATION, privacy/flag-fetching variables, CLAUDE_AUTO_BACKGROUND_TASKS, CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND, and CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS. Distinguish one-shot claude -p from stream-json input.
3. Elicitation: find tools that guess missing parameters or perform irreversible actions without obtaining the necessary decision. Inspect Elicitation and ElicitationResult hooks for automatic acceptance or changes to a user's refusal, including hooks outside this repository.
4. Lifecycle: check cancellation, remote versus stdio execution, retention, and resume. Identify unattended Tasks that might request user input.

Output: For each finding, name the tool or setting, cite the evidence, describe current behavior, recommend the smallest change, and give one verification step. Mark conditions you cannot observe as unknown.

Do not edit files, change settings, or invoke operational jobs during this audit. Show recommendations first.