60 60
61## Instalando servidores MCP61## Instalando servidores MCP
62 62
63Os servidores MCP podem ser configurados de várias maneiras dependendo de suas necessidades:63Os servidores MCP podem ser configurados de várias maneiras, dependendo das suas necessidades:
64 64
65### Opção 1: Adicionar um servidor HTTP remoto65### Opção 1: Adicionar um servidor HTTP remoto
66 66
67Os servidores HTTP são a opção recomendada para conectar a servidores MCP remotos. Este é o transporte mais amplamente suportado para serviços baseados em nuvem.67Os servidores HTTP são a opção recomendada para se conectar a servidores MCP remotos. Este é o transporte com maior suporte para serviços baseados em nuvem.
68 68
69```bash theme={null}69```bash theme={null}
70# Sintaxe básica70# Basic syntax
71claude mcp add --transport http <name> <url>71claude mcp add --transport http <name> <url>
72 72
73# Exemplo real: Conectar ao Notion73# Real example: Connect to Notion
74claude mcp add --transport http notion https://mcp.notion.com/mcp74claude mcp add --transport http notion https://mcp.notion.com/mcp
75 75
76# Exemplo com token Bearer76# Example with Bearer token
77claude mcp add --transport http secure-api https://api.example.com/mcp \77claude mcp add --transport http secure-api https://api.example.com/mcp \
78 --header "Authorization: Bearer your-token"78 --header "Authorization: Bearer your-token"
79```79```
80 80
81Ao configurar servidores MCP via JSON em `.mcp.json`, `~/.claude.json`, ou `claude mcp add-json`, o campo `type` aceita `streamable-http` como um alias para `http`. A especificação MCP usa o nome `streamable-http` para este transporte, portanto as configurações copiadas da documentação do servidor funcionam sem modificação.81Ao configurar servidores MCP via JSON em `.mcp.json`, `~/.claude.json` ou `claude mcp add-json`, o campo `type` aceita `streamable-http` como alias para `http`. A especificação MCP usa o nome `streamable-http` para este transporte, então configurações copiadas da documentação do servidor funcionam sem modificação.
82 82
83Uma entrada JSON que tem uma `url` mas nenhum `type` é um erro de configuração, porque Claude Code lê uma entrada sem `type` como um servidor stdio. Claude Code pula esse servidor e relata `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`.83Uma entrada JSON que tem um `url`, mas nenhum `type`, é um erro de configuração, porque o Claude Code lê uma entrada sem `type` como um servidor stdio. O Claude Code ignora esse servidor e informa `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`.
84 84
85Apenas um aplicativo host SDK, como um aplicativo [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/mcp.md) ou o [aplicativo de desktop](https://code.claude.com/docs/pt/desktop.md), pode registrar um servidor `"type": "sdk"` em processo. Claude Code pula uma entrada `"type": "sdk"` em `.mcp.json`, `~/.claude.json`, ou configurações e relata `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`.85Somente um aplicativo host do SDK, como um aplicativo do [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/mcp.md) ou o [aplicativo desktop](https://code.claude.com/docs/pt/desktop.md), pode registrar um servidor em processo `"type": "sdk"`. O Claude Code ignora uma entrada `"type": "sdk"` em `.mcp.json`, `~/.claude.json` ou nas configurações e informa `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`.
86 86
87> [!NOTE]87> [!NOTE]
88>88>
89> Em execuções com `--output-format stream-json`, o Claude Code também relata uma entrada `--mcp-config` ignorada no [campo `mcp_server_errors`](https://code.claude.com/docs/pt/headless#stream-responses) do evento `system/init`, para que scripts possam detectar que o servidor nunca foi carregado.89> Em execuções com `--output-format stream-json`, o Claude Code também informa uma entrada `--mcp-config` ignorada no [campo `mcp_server_errors`](https://code.claude.com/docs/pt/headless#stream-responses) do evento `system/init`, para que scripts possam detectar que o servidor nunca foi carregado.
90 90
91### Opção 2: Adicionar um servidor SSE remoto91### Opção 2: Adicionar um servidor SSE remoto
92 92
93> [!WARNING]93> [!WARNING]
94>94>
95> O transporte SSE (Server-Sent Events) está descontinuado. Use servidores HTTP em vez disso, quando disponível.95> O transporte SSE (Server-Sent Events) está descontinuado. Use servidores HTTP, quando disponíveis.
96 96
97Alguns serviços ainda expõem apenas um endpoint SSE. Adicione-os com o mesmo comando `claude mcp add --transport http <name> <url>` que um [servidor HTTP](#option-1-add-a-remote-http-server). Claude Code tenta o transporte HTTP primeiro e muda para SSE quando o servidor não o aceita. A mudança automática requer Claude Code v2.1.265 ou posterior.97Alguns serviços ainda expõem apenas um endpoint SSE. Adicione-os com o mesmo comando `claude mcp add --transport http <name> <url>` usado para [um servidor HTTP](#option-1-add-a-remote-http-server). O Claude Code tenta primeiro o transporte HTTP e muda para SSE quando o servidor não o aceita. A mudança automática requer o Claude Code v2.1.265 ou posterior.
98 98
99Em uma versão anterior, ou para conectar sobre SSE diretamente, passe `--transport sse` em vez disso:99Em uma versão anterior, ou para se conectar diretamente via SSE, passe `--transport sse`:
100 100
101```bash theme={null}101```bash theme={null}
102# Sintaxe básica102# Basic syntax
103claude mcp add --transport sse <name> <url>103claude mcp add --transport sse <name> <url>
104 104
105# Exemplo real: Conectar ao Asana105# Real example: Connect to Asana
106claude mcp add --transport sse asana https://mcp.asana.com/sse106claude mcp add --transport sse asana https://mcp.asana.com/sse
107 107
108# Exemplo com cabeçalho de autenticação108# Example with authentication header
109claude mcp add --transport sse private-api https://api.company.com/sse \109claude mcp add --transport sse private-api https://api.company.com/sse \
110 --header "X-API-Key: your-key-here"110 --header "X-API-Key: your-key-here"
111```111```
112 112
113### Opção 3: Adicionar um servidor stdio local113### Opção 3: Adicionar um servidor stdio local
114 114
115Os servidores Stdio são executados como processos locais em sua máquina. Eles são ideais para ferramentas que precisam de acesso direto ao sistema ou scripts personalizados.115Os servidores stdio são executados como processos locais na sua máquina. Eles são ideais para ferramentas que precisam de acesso direto ao sistema ou scripts personalizados.
116 116
117Claude Code define `CLAUDE_PROJECT_DIR` no ambiente do servidor gerado para a raiz do projeto, para que seu servidor possa resolver caminhos relativos ao projeto sem depender do diretório de trabalho. Este é o mesmo diretório que hooks recebem em sua variável `CLAUDE_PROJECT_DIR`. Leia-o de dentro do seu processo de servidor, por exemplo `process.env.CLAUDE_PROJECT_DIR` em Node ou `os.environ["CLAUDE_PROJECT_DIR"]` em Python.117O Claude Code define `CLAUDE_PROJECT_DIR` no ambiente do servidor iniciado como a raiz do projeto, para que seu servidor possa resolver caminhos relativos ao projeto sem depender do diretório de trabalho. Este é o mesmo diretório que os hooks recebem em sua variável `CLAUDE_PROJECT_DIR`. Leia-o de dentro do processo do seu servidor, por exemplo `process.env.CLAUDE_PROJECT_DIR` em Node ou `os.environ["CLAUDE_PROJECT_DIR"]` em Python.
118 118
119`CLAUDE_PROJECT_DIR` é a raiz do projeto estável e não muda quando você adiciona ou remove diretórios de trabalho no meio da sessão. Um servidor que limita seu próprio acesso ao sistema de arquivos a um conjunto de diretórios permitidos deve implementar a solicitação MCP `roots/list` em vez disso. Claude Code responde a `roots/list` com o diretório de inicialização da sessão mais cada [diretório de trabalho adicional](https://code.claude.com/docs/pt/permissions.md#working-directories) que você concedeu com `--add-dir`, `/add-dir`, ou a configuração `additionalDirectories`. Claude Code envia `notifications/roots/list_changed` quando esse conjunto muda.119`CLAUDE_PROJECT_DIR` é a raiz estável do projeto e não muda quando você adiciona ou remove diretórios de trabalho no meio da sessão. Um servidor que limita seu próprio acesso ao sistema de arquivos a um conjunto de diretórios permitidos deve implementar a requisição MCP `roots/list`. O Claude Code responde a `roots/list` com o diretório de inicialização da sessão mais cada [diretório de trabalho adicional](https://code.claude.com/docs/pt/permissions.md#working-directories) que você concedeu com `--add-dir`, `/add-dir` ou a configuração `additionalDirectories`. O Claude Code envia `notifications/roots/list_changed` quando esse conjunto muda.
120 120
121Esta variável é definida no ambiente do servidor, não no ambiente do próprio Claude Code, portanto fazer referência a ela via expansão `${VAR}` no `command` ou `args` de uma entrada `.mcp.json` com escopo de projeto ou uma entrada de servidor com escopo local ou de usuário em `~/.claude.json` requer um padrão como `${CLAUDE_PROJECT_DIR:-.}`. As configurações MCP fornecidas por plugins substituem `${CLAUDE_PROJECT_DIR}` diretamente e não precisam do padrão.121Essa variável é definida no ambiente do servidor, não no ambiente do próprio Claude Code, portanto referenciá-la via expansão `${VAR}` no `command` ou `args` de uma entrada `.mcp.json` com escopo de projeto, ou de uma entrada de servidor com escopo local ou de usuário em `~/.claude.json`, requer um valor padrão como `${CLAUDE_PROJECT_DIR:-.}`. As configurações MCP fornecidas por plugins substituem `${CLAUDE_PROJECT_DIR}` diretamente e não precisam do valor padrão.
122 122
123```bash theme={null}123```bash theme={null}
124# Sintaxe básica124# Basic syntax
125claude mcp add [options] <name> -- <command> [args...]125claude mcp add [options] <name> -- <command> [args...]
126 126
127# Exemplo real: Adicionar servidor Airtable127# Real example: Add Airtable server
128claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \128claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
129 -- npx -y airtable-mcp-server129 -- npx -y airtable-mcp-server
130```130```
131 131
132> [!NOTE]132> [!NOTE]
133>133>
134> Para servidores stdio, o `--` (duplo travessão) separa as próprias opções do Claude, como `--transport`, `--env`, e `--scope`, do comando e argumentos que executam o servidor. Tudo após `--` é passado para o servidor intocado.134> Para servidores stdio, o `--` (traço duplo) separa as opções do próprio Claude, como `--transport`, `--env` e `--scope`, do comando e dos argumentos que executam o servidor. Tudo após `--` é passado ao servidor sem alterações.
135>135>
136> Por exemplo:136> Por exemplo:
137>137>
138> * `claude mcp add --transport stdio myserver -- npx server` → executa `npx server`138> * `claude mcp add --transport stdio myserver -- npx server` → executa `npx server`
139> * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → executa `python server.py --port 8080` com `KEY=value` no ambiente139> * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → executa `python server.py --port 8080` com `KEY=value` no ambiente
140>140>
141> Sem `--`, Claude Code tentaria analisar os sinalizadores do servidor, como `--port` acima, como suas próprias opções.141> Sem `--`, o Claude Code tentaria interpretar as flags do servidor, como `--port` acima, como suas próprias opções.
142>142>
143> `--env` aceita múltiplos pares `KEY=value`. Se o nome do servidor vem imediatamente após `--env`, a CLI lê o nome como outro par e o rejeita, portanto coloque pelo menos uma outra opção, como `--transport stdio`, entre `--env` e o nome do servidor.143> `--env` aceita vários pares `KEY=value`. Se o nome do servidor vier diretamente após `--env`, a CLI lê o nome como outro par e o rejeita, então coloque pelo menos uma outra opção, como `--transport stdio`, entre `--env` e o nome do servidor.
144 144
145#### Como Claude Code para um servidor stdio145#### Como o Claude Code encerra um servidor stdio
146 146
147Quando Claude Code desconecta um servidor stdio, por exemplo quando sua sessão termina, ele sinaliza o processo do servidor e aguarda brevemente que ele saia antes de forçá-lo a parar. Se seu servidor salva estado ou remove arquivos de bloqueio no desligamento, trate o sinal da sua plataforma e termine dentro desse tempo:147Quando o Claude Code desconecta um servidor stdio, por exemplo quando sua sessão termina, ele envia um sinal ao processo do servidor e aguarda brevemente que ele saia antes de forçá-lo a parar. Se o seu servidor salva estado ou remove arquivos de bloqueio no encerramento, trate o sinal da sua plataforma e conclua dentro desse tempo:
148 148
149* **No macOS e Linux**: Claude Code envia `SIGINT`, depois `SIGTERM` se o processo ainda estiver em execução 100 milissegundos depois, depois `SIGKILL` após mais 400 milissegundos.149* **No macOS e Linux**: o Claude Code envia `SIGINT`, depois `SIGTERM` se o processo ainda estiver em execução 100 milissegundos depois, e então `SIGKILL` após mais 400 milissegundos.
150* **No Windows**: Claude Code fecha o stdin do servidor, depois encerra a árvore de processos do servidor se o processo ainda estiver em execução 300 milissegundos depois.150* **No Windows**: o Claude Code fecha o stdin do servidor e depois encerra a árvore de processos do servidor se o processo ainda estiver em execução 300 milissegundos depois.
151 151
152Antes da v2.1.296, Claude Code no Windows encerrava a árvore de processos do servidor de imediato, sem fechar o stdin primeiro nem aguardar.152Antes da v2.1.296, o Claude Code no Windows encerrava a árvore de processos do servidor imediatamente, sem fechar o stdin primeiro nem aguardar.
153 153
154### Opção 4: Adicionar um servidor WebSocket remoto154### Opção 4: Adicionar um servidor WebSocket remoto
155 155
156Os servidores WebSocket mantêm uma conexão bidirecional persistente, o que é adequado para servidores MCP remotos que enviam eventos para Claude sem solicitação. Use HTTP em vez disso quando seu servidor apenas responde a solicitações, já que HTTP suporta OAuth e o sinalizador `claude mcp add --transport`, enquanto WebSocket não suporta nenhum dos dois.156Os servidores WebSocket mantêm uma conexão bidirecional persistente, o que é adequado para servidores MCP remotos que enviam eventos ao Claude sem solicitação. Use HTTP quando o seu servidor apenas responde a requisições, já que o HTTP oferece suporte a OAuth e à flag `claude mcp add --transport`, enquanto o WebSocket não oferece suporte a nenhum dos dois.
157 157
158Configure servidores WebSocket em `.mcp.json` ou com `claude mcp add-json`:158Configure servidores WebSocket em `.mcp.json` ou com `claude mcp add-json`:
159 159
162 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'162 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
163```163```
164 164
165A entrada `type: "ws"` aceita os mesmos campos `url`, `headers`, `headersHelper`, `timeout`, e `alwaysLoad` que `http`. A autenticação é apenas por cabeçalho, portanto passe um token estático em `headers` ou gere um no momento da conexão com [`headersHelper`](#use-dynamic-headers-for-custom-authentication). O sinalizador `claude mcp add --transport` não aceita `ws`.165A entrada `type: "ws"` aceita os mesmos campos `url`, `headers`, `headersHelper`, `timeout` e `alwaysLoad` que `http`. A autenticação é feita apenas por cabeçalho, então passe um token estático em `headers` ou gere um no momento da conexão com [`headersHelper`](#use-dynamic-headers-for-custom-authentication). A flag `claude mcp add --transport` não aceita `ws`.
166 166
167### Adicionar um servidor a partir de instruções de configuração escritas para outro cliente167### Adicionar um servidor a partir de instruções de configuração escritas para outro cliente
168 168
169Os servidores MCP não são específicos do Claude Code, portanto as instruções de configuração de um servidor podem ser escritas para Claude Desktop, Cursor, ou outro cliente MCP e não fornecer nenhum comando `claude mcp add`. Para adicionar o servidor mesmo assim, procure nessas instruções por uma URL, um comando de inicialização ou um bloco JSON:169Os servidores MCP não são específicos do Claude Code, então as instruções de configuração de um servidor podem ter sido escritas para o Claude Desktop, o Cursor ou outro cliente MCP e não fornecer nenhum comando `claude mcp add`. Para adicionar o servidor mesmo assim, procure nessas instruções uma URL, um comando de inicialização ou um bloco JSON:
170 170
171* **Uma URL** como `https://mcp.example.com/mcp`: o servidor é remoto.171* **Uma URL** como `https://mcp.example.com/mcp`: o servidor é remoto.
172* **Um comando de inicialização** como `npx -y @example/mcp-server`: o servidor é executado em sua máquina.172* **Um comando de inicialização** como `npx -y @example/mcp-server`: o servidor é executado na sua máquina.
173* **Um bloco JSON `mcpServers`**: configuração escrita para o arquivo de configurações de outro cliente.173* **Um bloco JSON `mcpServers`**: configuração escrita para o arquivo de configuração de outro cliente.
174 174
175Cada um é uma das entradas que as quatro opções em [Instalando servidores MCP](#installing-mcp-servers) usam. Encontre a forma que você tem abaixo para transformá-la no comando que Claude Code aceita. Cada comando escreve no [escopo local](#local-scope) a menos que você adicione `--scope project` ou `--scope user`.175Cada um deles é uma das entradas que as quatro opções em [Instalando servidores MCP](#installing-mcp-servers) recebem. Encontre abaixo o formato que você tem para transformá-lo no comando que o Claude Code aceita. Cada comando grava no [escopo local](#local-scope), a menos que você adicione `--scope project` ou `--scope user`.
176 176
177#### Adicionar um servidor a partir de uma URL177#### Adicionar um servidor a partir de uma URL
178 178
179Uma URL significa que o servidor é remoto. Para um endpoint `https://`, adicione-o com `--transport http`, ou siga a [Opção 2](#option-2-add-a-remote-sse-server) quando as instruções disserem que o endpoint usa SSE. Para um endpoint `wss://`, use a [Opção 4](#option-4-add-a-remote-websocket-server) em vez disso, já que `--transport` não aceita `ws`:179Uma URL significa que o servidor é remoto. Para um endpoint `https://`, adicione-o com `--transport http`, ou siga a [Opção 2](#option-2-add-a-remote-sse-server) quando as instruções disserem que o endpoint usa SSE. Para um endpoint `wss://`, use a [Opção 4](#option-4-add-a-remote-websocket-server), já que `--transport` não aceita `ws`:
180 180
181```bash theme={null}181```bash theme={null}
182claude mcp add --transport http example https://mcp.example.com/mcp182claude mcp add --transport http example https://mcp.example.com/mcp
183```183```
184 184
185Se as instruções também fornecerem uma chave de API ou cabeçalho de token, passe-o com `--header` como mostrado na [Opção 1](#option-1-add-a-remote-http-server).185Se as instruções também fornecerem uma chave de API ou um cabeçalho de token, passe-o com `--header`, conforme mostrado na [Opção 1](#option-1-add-a-remote-http-server).
186 186
187#### Adicionar um servidor a partir de um comando `npx`, `uvx`, ou binário187#### Adicionar um servidor a partir de um comando `npx`, `uvx` ou binário
188 188
189Um comando de inicialização significa que o servidor é executado como um processo stdio local. Coloque o comando inteiro após `--`, para que Claude Code passe sinalizadores como `-y` para o comando que inicia o servidor em vez de lê-los como suas próprias opções. Passe quaisquer variáveis de ambiente que as instruções peçam com `--env`, após o nome do servidor e antes de `--`:189Um comando de inicialização significa que o servidor é executado como um processo stdio local. Coloque o comando inteiro após `--`, para que o Claude Code passe flags como `-y` ao comando que inicia o servidor em vez de lê-las como suas próprias opções. Passe quaisquer variáveis de ambiente que as instruções pedirem com `--env`, após o nome do servidor e antes de `--`:
190 190
191```bash theme={null}191```bash theme={null}
192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server
193```193```
194 194
195A [Opção 3](#option-3-add-a-local-stdio-server) cobre o separador `--` completamente.195A [Opção 3](#option-3-add-a-local-stdio-server) aborda o separador `--` em detalhes.
196 196
197#### Adicionar um servidor a partir de um bloco JSON `mcpServers`197#### Adicionar um servidor a partir de um bloco JSON `mcpServers`
198 198
199Um bloco `mcpServers` escrito para outro cliente MCP, como Claude Desktop, usa a chave wrapper e a forma de entrada que Claude Code lê. Passe `claude mcp add-json` o objeto dentro de `mcpServers`, não o wrapper. Duas entradas precisam de um reparo primeiro:199Um bloco `mcpServers` escrito para outro cliente MCP, como o Claude Desktop, usa a chave envolvente e o formato de entrada que o Claude Code lê. Passe para `claude mcp add-json` o objeto dentro de `mcpServers`, não o envoltório. Duas entradas precisam de um ajuste antes:
200 200
201* **Uma `url` sem `type`**: adicione `"type": "http"`, `"type": "sse"`, ou `"type": "ws"` para corresponder ao endpoint. Claude Code lê uma entrada sem `type` como um servidor stdio, portanto uma entrada `url` sem `type` falha.201* **Um `url` sem `type`**: adicione `"type": "http"`, `"type": "sse"` ou `"type": "ws"` de acordo com o endpoint. O Claude Code lê uma entrada sem `type` como um servidor stdio, então uma entrada `url` sem `type` falha.
202* **Uma chave com caracteres diferentes de letras, números, hífens e sublinhados**: escolha um nome de servidor que use apenas esses caracteres. Caso contrário, a chave é o nome do servidor.202* **Uma chave com caracteres diferentes de letras, números, hifens e sublinhados**: escolha um nome de servidor que use apenas esses caracteres. Caso contrário, a chave é o nome do servidor.
203 203
204Por exemplo, este bloco:204Por exemplo, este bloco:
205 205
220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
221```221```
222 222
223[Adicionar servidores MCP a partir de configuração JSON](#add-mcp-servers-from-json-configuration) cobre escape de shell e o sinalizador `--scope` para `add-json`. Para compartilhar o servidor com sua equipe em vez disso, adicione `--scope project`, ou adicione a entrada sob `mcpServers` em `.mcp.json` na raiz do seu projeto e faça commit. [Escopo de projeto](#project-scope) cobre como Claude Code carrega e aprova esse arquivo.223[Adicionar servidores MCP a partir de configuração JSON](#add-mcp-servers-from-json-configuration) aborda o escape no shell e a flag `--scope` para `add-json`. Para compartilhar o servidor com sua equipe, adicione `--scope project`, ou adicione a entrada em `mcpServers` no `.mcp.json` na raiz do seu projeto e faça commit dela. [Escopo de projeto](#project-scope) explica como o Claude Code carrega e aprova esse arquivo.
224 224
225Cada comando `claude mcp add` e `claude mcp add-json` imprime uma linha `Added ...` em caso de sucesso. Para verificar que Claude Code se conectou, execute `claude mcp get <name>`; [Status do servidor](#server-status) cobre os status que ele mostra e a etapa de aprovação para servidores `.mcp.json`.225Cada comando `claude mcp add` e `claude mcp add-json` imprime uma linha `Added ...` em caso de sucesso. Para verificar se o Claude Code se conectou, execute `claude mcp get <name>`; [Status do servidor](#server-status) aborda os status exibidos e a etapa de aprovação para servidores do `.mcp.json`.
226 226
227### Gerenciando seus servidores227### Gerenciando seus servidores
228 228
229Uma vez configurados, você pode gerenciar seus servidores MCP com estes comandos:229Depois de configurados, você pode gerenciar seus servidores MCP com estes comandos:
230 230
231```bash theme={null}231```bash theme={null}
232# Listar todos os servidores configurados232# List all configured servers
233claude mcp list233claude mcp list
234 234
235# Obter detalhes para um servidor específico235# Get details for a specific server
236claude mcp get notion236claude mcp get notion
237 237
238# Remover um servidor238# Remove a server
239claude mcp remove notion239claude mcp remove notion
240 240
241# (dentro do Claude Code) Verificar status do servidor241# (within Claude Code) Check server status
242/mcp242/mcp
243```243```
244 244
245Quando você remove um servidor remoto, o Claude Code também exclui os tokens OAuth e o registro de cliente que armazenou para esse servidor. O Claude Code não revoga os tokens no servidor de autorização que os emitiu. Para revogar os tokens quando o servidor de autorização oferece suporte à revogação, execute [`claude mcp logout <name>`](#authenticate-from-the-command-line) no seu shell antes de `claude mcp remove <name>`.245Quando você remove um servidor remoto, o Claude Code também exclui os tokens OAuth e o registro de cliente que armazenou para esse servidor. O Claude Code não revoga os tokens no servidor de autorização que os emitiu. Para revogar os tokens onde o servidor de autorização oferece suporte à revogação, execute [`claude mcp logout <name>`](#authenticate-from-the-command-line) no seu shell antes de `claude mcp remove <name>`.
246 246
247#### Status do servidor247#### Status do servidor
248 248
249`claude mcp add` confirma uma adição bem-sucedida imprimindo uma linha `Added ...`, o que significa que a configuração foi escrita. Se o comando imprimir uma mensagem `was not saved` em vez disso, veja [MCP server was not saved or removed](https://code.claude.com/docs/pt/errors.md#mcp-server-was-not-saved-or-removed); para uma mensagem `may not have been saved`, veja [MCP server may not have been saved or removed](https://code.claude.com/docs/pt/errors.md#mcp-server-may-not-have-been-saved-or-removed).249`claude mcp add` confirma uma adição bem-sucedida imprimindo uma linha `Added ...`, o que significa que a configuração foi gravada. Se o comando imprimir uma mensagem `was not saved`, consulte [O servidor MCP não foi salvo ou removido](https://code.claude.com/docs/pt/errors.md#mcp-server-was-not-saved-or-removed); para uma mensagem `may not have been saved`, consulte [O servidor MCP pode não ter sido salvo ou removido](https://code.claude.com/docs/pt/errors.md#mcp-server-may-not-have-been-saved-or-removed).
250 250
251`claude mcp list` mostra um status de saúde ao lado de cada servidor que lista, como `✔ Connected`, `! Needs authentication`, ou `✘ Failed to connect`. Um status de falha significa que Claude Code não conseguiu se conectar a esse servidor, não que o comando list falhou.251`claude mcp list` mostra um status de integridade ao lado de cada servidor listado, como `✔ Connected`, `! Needs authentication` ou `✘ Failed to connect`. Um status de falha significa que o Claude Code não conseguiu se conectar a esse servidor, não que o comando de listagem falhou.
252 252
253Os status nesta lista relatam uma decisão de configuração em vez de uma tentativa de conexão, portanto Claude Code os imprime sem se conectar ao servidor:253Os status nesta lista informam uma decisão de configuração em vez de uma tentativa de conexão, então o Claude Code os imprime sem se conectar ao servidor:
254 254
255* ``⏸ Pending approval (run `claude` to approve)``: um servidor com escopo de projeto do `.mcp.json` que você ainda não aprovou. O Claude Code o mostra tanto em `claude mcp list` quanto em `claude mcp get <name>`. Execute `claude` interativamente para revisá-lo e aprová-lo.255* ``⏸ Pending approval (run `claude` to approve)``: um servidor com escopo de projeto do `.mcp.json` que você ainda não aprovou. O Claude Code o mostra tanto em `claude mcp list` quanto em `claude mcp get <name>`. Execute `claude` interativamente para revisá-lo e aprová-lo.
256* `✘ Rejected (see disabledMcpjsonServers in settings)`: um servidor `.mcp.json` que uma entrada [`disabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#disabledmcpjsonservers) rejeita. Claude Code o mostra apenas em `claude mcp get <name>`.256* `✘ Rejected (see disabledMcpjsonServers in settings)`: um servidor do `.mcp.json` que uma entrada [`disabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#disabledmcpjsonservers) rejeita. O Claude Code o mostra apenas em `claude mcp get <name>`.
257* `⊘ Disabled for this project (re-enable via /mcp)`: um servidor que a lista [`disabledMcpServers`](#disable-a-server-without-removing-it) do projeto nomeia. Claude Code o mostra em `claude mcp list` e `claude mcp get <name>`. Ative o servidor novamente no painel `/mcp`.257* `⊘ Disabled for this project (re-enable via /mcp)`: um servidor que a lista [`disabledMcpServers`](#disable-a-server-without-removing-it) do projeto nomeia. O Claude Code o mostra tanto em `claude mcp list` quanto em `claude mcp get <name>`. Reative o servidor no painel `/mcp`.
258* `✘ Blocked by enterprise managed policy`: um servidor que uma das políticas da sua organização recusa. O Claude Code o mostra tanto em `claude mcp list` quanto em `claude mcp get <name>`. Um servidor bloqueado por uma allowlist, uma denylist ou outra restrição na [configuração MCP gerenciada](https://code.claude.com/docs/pt/managed-mcp.md#how-restrictions-appear-to-users) fica oculto em ambos os comandos em vez de ser mostrado com esse status. Pergunte ao seu administrador qual política bloqueia o servidor.258* `✘ Blocked by enterprise managed policy`: um servidor que uma das políticas da sua organização recusa. O Claude Code o mostra tanto em `claude mcp list` quanto em `claude mcp get <name>`. Um servidor bloqueado por uma allowlist, uma denylist ou outra restrição na [configuração MCP gerenciada](https://code.claude.com/docs/pt/managed-mcp.md#how-restrictions-appear-to-users) fica oculto em ambos os comandos em vez de ser mostrado com esse status. Pergunte ao seu administrador qual política bloqueia o servidor.
259 259
260#### Aprovações de servidor de projeto e confiança do workspace260#### Aprovações de servidores do projeto e confiança no workspace
261 261
262`claude mcp list` e `claude mcp get` leem aprovações `.mcp.json` apenas de arquivos de configurações que não estão no repositório até que você confie no workspace executando `claude` nele e aceitando o diálogo de confiança do workspace. Um repositório clonado não pode aprovar seus próprios servidores: [`enableAllProjectMcpServers`](https://code.claude.com/docs/pt/settings-reference#enableallprojectmcpservers) ou [`enabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#enabledmcpjsonservers) incluído via commit no `.claude/settings.json` do projeto é ignorado em uma pasta não confiável, e o servidor permanece em `⏸ Pending approval` em vez de ser conectado e verificado quanto à saúde.262`claude mcp list` e `claude mcp get` leem aprovações do `.mcp.json` apenas de arquivos de configuração que não estão no repositório até que você confie no workspace executando `claude` nele e aceitando a caixa de diálogo de confiança do workspace. Um repositório clonado não pode aprovar seus próprios servidores: [`enableAllProjectMcpServers`](https://code.claude.com/docs/pt/settings-reference#enableallprojectmcpservers) ou [`enabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#enabledmcpjsonservers) com commit no `.claude/settings.json` do projeto são ignorados em uma pasta não confiável, e o servidor permanece em `⏸ Pending approval` em vez de ser conectado e ter sua integridade verificada.
263 263
264As aprovações dessas fontes ainda se aplicam em uma pasta não confiável:264As aprovações destas fontes ainda se aplicam em uma pasta não confiável:
265 265
266* seu `~/.claude/settings.json` de usuário266* seu `~/.claude/settings.json` de usuário
267* configurações gerenciadas267* configurações gerenciadas
268* configurações passadas com `--settings`268* configurações passadas com `--settings`
269 269
270Claude Code também aplica aprovações de um `.claude/settings.local.json` não rastreado, mas executa git para verificar se o arquivo é rastreado, e executa essa verificação apenas em uma [pasta confiável](https://code.claude.com/docs/pt/permissions.md#project-allow-rules-and-workspace-trust). Em uma pasta que você nunca confiou, Claude Code aguarda o diálogo de confiança antes de aplicar as aprovações do arquivo, a menos que a pasta seja seu próprio diretório de configuração: seu diretório pessoal, ou um diretório cujo `.claude` você definiu como [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/pt/env-vars). Antes da v2.1.207, Claude Code aplicava aprovações de um `.claude/settings.local.json` não rastreado mesmo em uma pasta que você nunca tinha confiado.270O Claude Code também aplica aprovações de um `.claude/settings.local.json` não rastreado, mas executa o git para verificar se o arquivo é rastreado e executa essa verificação apenas em uma [pasta confiável](https://code.claude.com/docs/pt/permissions.md#project-allow-rules-and-workspace-trust). Em uma pasta em que você nunca confiou, o Claude Code aguarda a caixa de diálogo de confiança antes de aplicar as aprovações do arquivo, a menos que a pasta seja sua própria base de configuração: seu diretório pessoal, ou um diretório cujo `.claude` você definiu como [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/pt/env-vars). Antes da v2.1.207, o Claude Code aplicava aprovações de um `.claude/settings.local.json` não rastreado mesmo em uma pasta em que você nunca havia confiado.
271 271
272Uma entrada `disabledMcpjsonServers` em qualquer arquivo de configurações ainda rejeita o servidor.272Uma entrada `disabledMcpjsonServers` em qualquer arquivo de configuração ainda rejeita o servidor.
273 273
274#### Detalhe do status do servidor274#### Detalhes do status do servidor
275 275
276Em `/mcp`, incluindo o menu de um servidor lá, e no [gerenciador `/plugin`](https://code.claude.com/docs/pt/plugins/install), um servidor HTTP ou SSE remoto que você usou antes pode mostrar um status `cached` como `cached 2h ago · connects on first use · 5 tools`. Claude Code carregou a lista de ferramentas do servidor de seu cache de descoberta, salvo em uma sessão anterior, em vez de se conectar na inicialização, e Claude Code conecta o servidor na primeira vez que Claude chama uma das ferramentas do servidor. As ferramentas estão disponíveis a partir de sua primeira mensagem, portanto você não precisa fazer nada. O cache de descoberta e seu status `cached` requerem Claude Code v2.1.221 ou posterior.276Em `/mcp`, incluindo o menu de um servidor ali, e no gerenciador [`/plugin`](https://code.claude.com/docs/pt/plugins/install), um servidor HTTP ou SSE remoto que você já usou pode mostrar um status `cached` como `cached 2h ago · connects on first use · 5 tools`. O Claude Code carregou a lista de ferramentas do servidor a partir do seu cache de descoberta, salvo em uma sessão anterior, em vez de se conectar na inicialização, e o Claude Code conecta o servidor na primeira vez que o Claude chama uma das ferramentas do servidor. As ferramentas ficam disponíveis desde a sua primeira mensagem, então você não precisa fazer nada. O cache de descoberta e seu status `cached` requerem o Claude Code v2.1.221 ou posterior.
277 277
278O cache de descoberta está desativado por padrão a menos que um lançamento gradual o tenha ativado para sua conta. Defina [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/pt/env-vars) para ativá-lo, ou `0` para mantê-lo desativado mesmo quando o lançamento o tiver ativado. Antes da v2.1.238, o cache estava ativado por padrão.278O cache de descoberta fica desativado por padrão, a menos que uma implantação gradual o tenha ativado para sua conta. Defina [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/pt/env-vars) para ativá-lo, ou `0` para mantê-lo desativado mesmo quando a implantação o tiver ativado. Antes da v2.1.238, o cache ficava ativado por padrão.
279 279
280Quando você seleciona **Disable** ou **Clear authentication** no menu de um servidor em `/mcp`, Claude Code também descarta a entrada de cache desse servidor. **Reconnect** também a descarta em um servidor conectado ou com falha; em um servidor `cached`, **Reconnect** conecta o servidor agora e mantém a entrada. Na próxima vez que Claude Code se conectar ao servidor após descartar a entrada, ele busca a lista de ferramentas do servidor em vez de do cache.280Quando você seleciona **Disable** ou **Clear authentication** no menu de um servidor em `/mcp`, o Claude Code também descarta a entrada de cache desse servidor. **Reconnect** também a descarta em um servidor conectado ou com falha; em um servidor `cached`, **Reconnect** conecta o servidor agora e mantém a entrada. Na próxima vez que o Claude Code se conectar ao servidor após descartar a entrada, ele busca a lista de ferramentas no servidor em vez de no cache.
281 281
282##### Falhas de conexão e servidores não configurados282##### Falhas de conexão e servidores não configurados
283 283
284Quando o status de um servidor é `✘ Failed to connect`, `claude mcp list` acrescenta o detalhe da falha a essa linha de status, e `claude mcp get <name>` o mostra em uma linha `Issue:`. O detalhe é o status HTTP ou código de erro, mais qualquer texto de erro que o servidor retornou. A visualização de detalhes do servidor em `/mcp` inclui o mesmo texto relatado pelo servidor em sua linha `Issue:`.284Quando o status de um servidor é `✘ Failed to connect`, `claude mcp list` acrescenta o detalhe da falha a essa linha de status, e `claude mcp get <name>` o mostra em uma linha `Issue:`. O detalhe é o status HTTP ou o código de erro, mais qualquer texto de erro que o servidor retornou. A visualização de detalhes do servidor em `/mcp` inclui o mesmo texto informado pelo servidor em sua linha `Issue:`.
285 285
286O Claude Code oculta texto semelhante a credenciais desse detalhe e nunca inclui a URL expandida do servidor, que pode conter segredos. O Claude Code não acrescenta nenhum detalhe a um status `✘ Connection error`, porque o texto da exceção que ele imprimiria ali pode incluir essa URL.286O Claude Code oculta textos semelhantes a credenciais nesse detalhe e nunca inclui a URL expandida do servidor, que pode conter segredos. O Claude Code não acrescenta nenhum detalhe a um status `✘ Connection error`, porque o texto da exceção que ele imprimiria ali pode incorporar essa URL.
287 287
288Quando você completa a autenticação de `/mcp` e a conexão ainda falha com um status HTTP ou um código de erro de transporte, Claude Code adiciona esse código e a origem da URL do servidor à mensagem que imprime após a tentativa. A origem é o esquema e host, mais a porta quando a URL nomeia uma, como `https://mcp.example.com`.288Quando você conclui a autenticação em `/mcp` e a conexão ainda falha com um status HTTP ou um código de erro de transporte, o Claude Code adiciona esse código e a origem da URL do servidor à mensagem que imprime após a tentativa. A origem é o esquema e o host, mais a porta quando a URL especifica uma, como `https://mcp.example.com`.
289 289
290* O caminho e a consulta nunca aparecem nessa mensagem.290* O caminho e a query nunca aparecem nessa mensagem.
291* Para um servidor no [escopo](#mcp-installation-scopes) local, de projeto, ou de usuário ou em configuração MCP gerenciada, a origem mostra o host como escrito nessa configuração, portanto uma referência `${VAR}` no host não é expandida na mensagem.291* Para um servidor no [escopo](#mcp-installation-scopes) local, de projeto ou de usuário, ou na configuração MCP gerenciada, a origem mostra o host conforme escrito nessa configuração, então uma referência `${VAR}` no host não é expandida na mensagem.
292* Para uma falha sem status ou código de erro, Claude Code mostra o texto de erro sem a origem.292* Para uma falha sem status ou código de erro, o Claude Code mostra o texto do erro sem a origem.
293 293
294Um servidor remoto cuja configuração tem uma `url` vazia mostra como `not configured` em `/mcp`, em `claude mcp list`, e no [gerenciador `/plugin`](https://code.claude.com/docs/pt/plugins/install), e Claude Code não tenta se conectar a ele. Um plugin pode incluir uma entrada de espaço reservado como esta para um conector que você configura depois, portanto Claude Code não a relata como um erro ou um problema de configuração. A visualização de detalhe do servidor em `/mcp` lê `No URL configured for this server`; defina a `url` da entrada para conectá-lo.294Um servidor remoto cuja configuração tem um `url` vazio aparece como `not configured` em `/mcp`, em `claude mcp list` e no gerenciador [`/plugin`](https://code.claude.com/docs/pt/plugins/install), e o Claude Code não tenta se conectar a ele. Um plugin pode incluir uma entrada de espaço reservado como esta para um conector que você configura depois, então o Claude Code não a informa como erro ou problema de configuração. A visualização de detalhes do servidor em `/mcp` exibe `No URL configured for this server`; defina o `url` da entrada para conectá-lo.
295 295
296#### Avisos de configuração296#### Avisos de configuração
297 297
298Claude Code avisa sobre os problemas de configuração abaixo. Cada entrada diz o que Claude Code verifica e como limpar o aviso:298O Claude Code emite avisos sobre os problemas de configuração abaixo. Cada item diz o que o Claude Code verifica e como eliminar o aviso:
299 299
300* **Espaço em branco oculto**: Claude Code avisa quando um valor de configuração MCP carrega espaço em branco oculto à esquerda ou à direita, que frequentemente vem de colar um token com uma quebra de linha à direita. Claude Code verifica `command`, `url`, cada entrada `args`, e os valores e nomes de chave sob `env` e `headers`. Claude Code mostra o aviso na saída de `claude mcp list` e em `/mcp`, nomeando os campos afetados sem ecoar seus valores, por exemplo `Leading or trailing whitespace in: headers.Authorization`. Claude Code não remove o espaço em branco e usa os valores exatamente como escritos, portanto edite a configuração para removê-lo.300* **Espaços em branco ocultos**: o Claude Code emite um aviso quando um valor de configuração MCP contém espaços em branco ocultos no início ou no fim, o que costuma vir de colar um token com uma quebra de linha no final. O Claude Code verifica `command`, `url`, cada entrada de `args` e os valores e nomes de chaves em `env` e `headers`. O Claude Code mostra o aviso na saída de `claude mcp list` e em `/mcp`, nomeando os campos afetados sem repetir seus valores, por exemplo `Leading or trailing whitespace in: headers.Authorization`. O Claude Code não remove os espaços em branco e usa os valores exatamente como escritos, então edite a configuração para removê-los.
301* **Mesmo nome em mais de um escopo**: se você definir o mesmo nome de servidor em mais de um [escopo](#mcp-installation-scopes) com endpoints diferentes, Claude Code avisa sobre o conflito na saída de `claude mcp list` e em `/mcp`. Claude Code armazena logins OAuth por endpoint, portanto quando você autentica a definição que carrega em um projeto, você ainda precisa fazer login separadamente em um projeto onde uma definição diferente carrega. Mantenha o endpoint que você quer e remova os outros com `claude mcp remove <name> --scope <scope>`. No aviso, Claude Code cita o endpoint de cada escopo como escrito em sua configuração, com referências [`${VAR}`](#environment-variable-expansion-in-mcp-json) não expandidas, portanto nunca mostra um valor resolvido como uma chave de API.301* **Mesmo nome em mais de um escopo**: se você definir o mesmo nome de servidor em mais de um [escopo](#mcp-installation-scopes) com endpoints diferentes, o Claude Code emite um aviso sobre o conflito na saída de `claude mcp list` e em `/mcp`. O Claude Code armazena logins OAuth por endpoint, então, quando você autentica a definição carregada em um projeto, ainda precisa fazer login separadamente em um projeto onde outra definição é carregada. Mantenha o endpoint que você deseja e remova os outros com `claude mcp remove <name> --scope <scope>`. No aviso, o Claude Code cita o endpoint de cada escopo conforme escrito na sua configuração, com [referências `${VAR}`](#environment-variable-expansion-in-mcp-json) não expandidas, então nunca mostra um valor resolvido como uma chave de API.
302* **Nomes reservados**: Claude Code reserva os nomes de seus servidores integrados, incluindo `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview`, e `Claude Browser`. Se sua configuração definir um servidor com um nome reservado, Claude Code o pula no tempo de carregamento e mostra um aviso pedindo que você o renomeie. `claude mcp add` rejeita um nome reservado com um erro. `Claude Preview` e `Claude Browser` ambos nomeiam o servidor integrado que o [painel de visualização do aplicativo de desktop Claude Code](https://code.claude.com/docs/pt/desktop.md#preview-your-app) usa.302* **Nomes reservados**: o Claude Code reserva os nomes de seus servidores integrados, incluindo `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview` e `Claude Browser`. Se sua configuração definir um servidor com um nome reservado, o Claude Code o ignora no carregamento e mostra um aviso pedindo que você o renomeie. `claude mcp add` rejeita um nome reservado com um erro. `Claude Preview` e `Claude Browser` nomeiam ambos o servidor integrado que o [painel de visualização do aplicativo desktop do Claude Code](https://code.claude.com/docs/pt/desktop.md#preview-your-app) usa.
303* **Variável de ambiente ausente**: se uma referência [`${VAR}`](#environment-variable-expansion-in-mcp-json) na configuração de um servidor nomeia uma variável que não está definida e não tem `:-default`, Claude Code avisa na saída de `claude mcp list` e em `/mcp`, nomeando a variável, e ainda carrega o servidor com o texto `${VAR}` não expandido. Defina a variável ou adicione um fallback `${VAR:-default}`. Na `url` e nos `headers` de um servidor remoto, algumas variáveis de credenciais [leem como vazias](#credential-variables-that-read-as-empty) em vez disso, sem aviso.303* **Variável de ambiente ausente**: se uma [referência `${VAR}`](#environment-variable-expansion-in-mcp-json) na configuração de um servidor nomear uma variável que não está definida e não tem `:-default`, o Claude Code emite um aviso na saída de `claude mcp list` e em `/mcp`, nomeando a variável, e ainda carrega o servidor com o texto `${VAR}` não expandido. Defina a variável ou adicione um fallback `${VAR:-default}`. No `url` e nos `headers` de um servidor remoto, algumas variáveis de credenciais [são lidas como vazias](#credential-variables-that-read-as-empty), sem aviso.
304 304
305#### Disponibilidade de ferramentas305#### Disponibilidade de ferramentas
306 306
307O painel `/mcp` mostra a contagem de ferramentas ao lado de cada servidor conectado e sinaliza servidores que anunciam a capacidade de ferramentas mas não expõem ferramentas.307O painel `/mcp` mostra a contagem de ferramentas ao lado de cada servidor conectado e sinaliza servidores que anunciam a capacidade de ferramentas, mas não expõem nenhuma ferramenta.
308 308
309##### Contagens de ferramentas em uma sessão na nuvem309##### Contagens de ferramentas em uma sessão na nuvem
310 310
311Em uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), uma contagem como `3 of 13 tools available` significa que o Claude não pode usar as outras 10. Verifique estas causas, entre outras:311Em uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), uma contagem como `3 of 13 tools available` significa que o Claude não pode usar as outras 10. Verifique estas causas, entre outras:
312 312
313* **Uma regra de negação no `.claude/settings.json` do seu repositório nomeia a ferramenta ou todo o seu servidor**: remova a [regra](https://code.claude.com/docs/pt/permissions.md#mcp), se [sua sessão lê esse arquivo](https://code.claude.com/docs/pt/settings.md#settings-in-cloud-sessions)313* **Uma regra de negação no `.claude/settings.json` do seu repositório nomeia a ferramenta ou todo o seu servidor**: remova a [regra](https://code.claude.com/docs/pt/permissions.md#mcp), se [sua sessão ler esse arquivo](https://code.claude.com/docs/pt/settings.md#settings-in-cloud-sessions)
314* **O nome completo da ferramenta tem mais de 128 caracteres**: siga [as etapas para um nome longo demais](https://code.claude.com/docs/pt/errors.md#mcp-tool-name-over-128-characters)314* **O nome completo da ferramenta tem mais de 128 caracteres**: siga [as etapas para um nome longo demais](https://code.claude.com/docs/pt/errors.md#mcp-tool-name-over-128-characters)
315* **O servidor lista a ferramenta para sua própria interface e não para o Claude**: se você mantém o servidor, adicione `model` ao `_meta.ui.visibility` da ferramenta para dar a ferramenta ao Claude. Caso contrário, não há nada a corrigir.315* **O servidor lista a ferramenta para sua própria interface e não para o Claude**: se você mantém o servidor, adicione `model` ao `_meta.ui.visibility` da ferramenta para dar a ferramenta ao Claude. Caso contrário, não há nada a corrigir.
316 316
317##### Ferramentas de um servidor que ainda está se conectando317##### Ferramentas de um servidor que ainda está se conectando
318 318
319Se sua solicitação precisa de ferramentas de um servidor que ainda está se conectando em segundo plano, Claude aguarda esse servidor antes de continuar. Como a espera acontece depende de sua configuração:319Se sua solicitação precisar de ferramentas de um servidor que ainda está se conectando em segundo plano, o Claude aguarda esse servidor antes de continuar. Como a espera acontece depende da sua configuração:
320 320
321* **Com [busca de ferramentas](#scale-with-mcp-tool-search), o padrão**: a espera acontece dentro da chamada `ToolSearch`.321* **Com a [pesquisa de ferramentas](#scale-with-mcp-tool-search), o padrão**: a espera acontece dentro da chamada `ToolSearch`.
322* **Sem busca de ferramentas**: Claude usa a ferramenta `WaitForMcpServers` em vez disso. As configurações sem busca de ferramentas incluem `ENABLE_TOOL_SEARCH=false` e um modelo anterior a Claude Opus 4.5, Claude Sonnet 4.5 e Claude Haiku 4.5 na Agent Platform do Google Cloud. Para um gateway `ANTHROPIC_BASE_URL`, veja [Busca de ferramentas através de um gateway de LLM](#tool-search-through-a-gateway).322* **Sem a pesquisa de ferramentas**: o Claude usa a ferramenta `WaitForMcpServers`. Configurações sem pesquisa de ferramentas incluem `ENABLE_TOOL_SEARCH=false` e um modelo anterior ao Claude Opus 4.5, Claude Sonnet 4.5 e Claude Haiku 4.5 no Agent Platform do Google Cloud. Para um gateway `ANTHROPIC_BASE_URL`, consulte [Pesquisa de ferramentas por meio de um gateway de LLM](#tool-search-through-a-gateway).
323* **Em uma implantação Microsoft Foundry [hospedada no Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**: Claude começa no caminho de busca de ferramentas em vez de com `WaitForMcpServers`, já que Claude Code descobre a rejeição do lado do servidor apenas da API. Depois que Claude Code muda essa implantação para [carregamento antecipado](#scale-with-mcp-tool-search), as ferramentas de um servidor que termina de se conectar ficam disponíveis na próxima solicitação do Claude.323* **Em uma [implantação do Microsoft Foundry hospedada no Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**: o Claude começa pelo caminho da pesquisa de ferramentas em vez de usar `WaitForMcpServers`, já que o Claude Code só descobre a rejeição do lado do servidor da implantação a partir da API. Depois que o Claude Code muda essa implantação para [carregamento antecipado](#scale-with-mcp-tool-search), as ferramentas de um servidor que termina de se conectar ficam disponíveis na próxima requisição do Claude.
324 324
325Com busca de ferramentas ativada, quando um servidor termina de se conectar enquanto Claude está trabalhando, Claude Code lista os nomes de ferramentas do servidor para Claude em sua próxima solicitação no mesmo turno. Claude pode então procurar e chamar essas ferramentas sem aguardar sua próxima mensagem.325Com a pesquisa de ferramentas ativada, quando um servidor termina de se conectar enquanto o Claude está trabalhando, o Claude Code lista os nomes das ferramentas do servidor para o Claude em sua próxima requisição no mesmo turno. O Claude pode então pesquisar e chamar essas ferramentas sem esperar pela sua próxima mensagem.
326 326
327Depois que você retoma uma sessão, Claude pode chamar uma ferramenta da conversa salva enquanto o servidor MCP da ferramenta ainda está se conectando. Enquanto o servidor está em sua primeira tentativa de conexão, Claude Code retém a chamada por até 10 segundos e a executa assim que a ferramenta estiver disponível. Se o servidor não se conectar a tempo, ou se já estiver [tentando novamente após uma tentativa com falha](#automatic-reconnection), a chamada falha com o [erro de ferramenta](https://code.claude.com/docs/pt/errors.md#no-such-tool-available) `No such tool available`.327Depois que você retoma uma sessão, o Claude pode chamar uma ferramenta da conversa salva enquanto o servidor MCP da ferramenta ainda está se conectando. Enquanto o servidor está em sua primeira tentativa de conexão, o Claude Code retém a chamada por até 10 segundos e a executa assim que a ferramenta estiver disponível. Se o servidor não se conectar a tempo, ou já estiver [tentando novamente após uma tentativa com falha](#automatic-reconnection), a chamada falha com o [erro de ferramenta](https://code.claude.com/docs/pt/errors.md#no-such-tool-available) `No such tool available`.
328 328
329### Desabilitar um servidor sem removê-lo329### Desativar um servidor sem removê-lo
330 330
331Alterne um servidor no painel `/mcp` para impedir que Claude Code se conecte a ele sem perder sua configuração. Claude Code ainda lista o servidor em `/mcp`, marcado como desabilitado.331Desative um servidor no painel `/mcp` para impedir que o Claude Code se conecte a ele sem perder sua configuração. O Claude Code continua listando o servidor em `/mcp`, marcado como desativado.
332 332
333Quando você alterna um servidor, Claude Code registra sua escolha por projeto em `~/.claude.json`, em uma de duas listas que cobrem conjuntos disjuntos de servidores:333Quando você alterna um servidor, o Claude Code registra sua escolha por projeto em `~/.claude.json`, em uma de duas listas que cobrem conjuntos disjuntos de servidores:
334 334
335* `disabledMcpServers`: uma lista de exclusão para servidores configurados pelo usuário, servidores de plugin, servidores que sua organização [fornece através de configurações gerenciadas](https://code.claude.com/docs/pt/managed-mcp.md#provide-servers-through-managed-settings), os conectores claude.ai que Claude Code [busca a si mesmo](#how-connectors-reach-claude-code), e servidores integrados que padrão para ativado. Claude Code não se conecta a um servidor que você lista aqui. Quando você desabilita um conector claude.ai com o alternador `/mcp` por projeto descrito em [Desabilitar conectores claude.ai](#disable-claude-ai-connectors), Claude Code o escreve nesta lista sob seu nome de exibição, por exemplo `claude.ai Slack`.335* `disabledMcpServers`: uma lista de exclusão para servidores configurados pelo usuário, servidores de plugins, servidores que sua organização [fornece por meio de configurações gerenciadas](https://code.claude.com/docs/pt/managed-mcp.md#provide-servers-through-managed-settings), os conectores do claude.ai que o Claude Code [busca por conta própria](#how-connectors-reach-claude-code) e servidores integrados que são ativados por padrão. O Claude Code não se conecta a um servidor que você lista aqui. Quando você desativa um conector do claude.ai com a alternância por projeto em `/mcp` descrita em [Desativar conectores do claude.ai](#disable-claude-ai-connectors), o Claude Code o grava nesta lista com seu nome de exibição, por exemplo `claude.ai Slack`.
336* `enabledMcpServers`: uma lista de inclusão para servidores integrados que padrão para desabilitado, como `computer-use`. Claude Code se conecta a um servidor padrão-desabilitado apenas quando você o lista aqui.336* `enabledMcpServers`: uma lista de inclusão para servidores integrados que são desativados por padrão, como `computer-use`. O Claude Code se conecta a um servidor desativado por padrão apenas quando você o lista aqui.
337 337
338Claude Code consulta exatamente uma das duas listas para cada servidor, portanto nenhuma lista sobrescreve a outra. Se você adicionar um servidor regular a `enabledMcpServers`, ou um servidor integrado padrão-desabilitado a `disabledMcpServers`, Claude Code ignora a entrada.338O Claude Code consulta exatamente uma das duas listas para cada servidor, então nenhuma lista sobrescreve a outra. Se você adicionar um servidor comum a `enabledMcpServers`, ou um servidor integrado desativado por padrão a `disabledMcpServers`, o Claude Code ignora a entrada.
339 339
340`disabledMcpServers` e `enabledMcpServers` não estão relacionados a [`enabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#enabledmcpjsonservers) e [`disabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#disabledmcpjsonservers), que controlam a aprovação de servidores definidos no arquivo `.mcp.json` de um projeto.340`disabledMcpServers` e `enabledMcpServers` não têm relação com [`enabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#enabledmcpjsonservers) e [`disabledMcpjsonServers`](https://code.claude.com/docs/pt/settings-reference#disabledmcpjsonservers), que controlam a aprovação de servidores definidos no arquivo `.mcp.json` de um projeto.
341 341
342### Tempos de execução do cliente MCP342### Runtimes de cliente MCP
343 343
344Claude Code se conecta a servidores MCP através de um de dois tempos de execução do cliente. O tempo de execução v1 é construído no MCP TypeScript SDK 1.x. O tempo de execução v2 é o mesmo código no [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/), que adiciona revisão de protocolo MCP 2026-07-28. O resto desta página se aplica a ambos os tempos de execução, exceto onde uma seção nomeia o tempo de execução v2.344O Claude Code se conecta a servidores MCP por meio de um de dois runtimes de cliente. O runtime v1 é construído sobre o MCP TypeScript SDK 1.x. O runtime v2 é o mesmo código sobre o [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/), que adiciona a revisão 2026-07-28 do protocolo MCP. O restante desta página se aplica a ambos os runtimes, exceto onde uma seção menciona o runtime v2.
345 345
346Claude Code escolhe um tempo de execução cada vez que você o inicia e o mantém até você sair. Em sessões onde ele [busca sinalizadores de recurso](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching), ele usa o tempo de execução v2 no Claude Code v2.1.232 ou posterior.346O Claude Code escolhe um runtime cada vez que você o inicia e o mantém até você sair. Em sessões em que ele [busca feature flags](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching), ele usa o runtime v2 no Claude Code v2.1.232 ou posterior.
347 347
348Nas sessões onde ele não busca sinalizadores de recurso, Claude Code usa o tempo de execução v2 por padrão no Claude Code v2.1.274 ou posterior:348Nas sessões em que não busca feature flags, o Claude Code usa o runtime v2 por padrão no Claude Code v2.1.274 ou posterior:
349 349
350* Sessões no Amazon Bedrock, Claude Platform no AWS, Agent Platform do Google Cloud, ou Microsoft Foundry, a menos que uma plataforma host que incorpora Claude Code defina [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/pt/env-vars)350* Sessões no Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud ou Microsoft Foundry, a menos que uma plataforma host que incorpora o Claude Code defina [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/pt/env-vars)
351* Sessões conectadas através de um [gateway de aplicativos Claude](https://code.claude.com/docs/pt/claude-apps-gateway)351* Sessões conectadas por meio de um [Claude apps gateway](https://code.claude.com/docs/pt/claude-apps-gateway)
352* Sessões onde você desativa telemetria ou busca de sinalizador de recurso, por exemplo com `DISABLE_TELEMETRY`352* Sessões em que você desativa a telemetria ou a busca de feature flags, por exemplo com `DISABLE_TELEMETRY`
353 353
354No v2, Claude Code também:354No v2, o Claude Code também:
355 355
356* Pergunta aos servidores HTTP, stdio e conectores claude.ai se eles suportam a revisão mais recente, e a usa com aqueles que suportam. Isso inclui os conectores de sessões na nuvem e de [Remote Control](https://code.claude.com/docs/pt/remote-control.md). Claude Code se conecta a todos os outros servidores como v1 faz.356* Pergunta aos servidores HTTP, stdio e de conectores do claude.ai se eles oferecem suporte à revisão mais recente e a usa com aqueles que oferecem. Isso inclui os conectores de sessões na nuvem e de [Remote Control](https://code.claude.com/docs/pt/remote-control.md). O Claude Code se conecta a todos os outros servidores como o v1 faz.
357* Recebe notificações `list_changed` de servidores na revisão mais recente sobre um [stream que mantém aberto](#notification-streams-on-the-v2-runtime).357* Recebe notificações `list_changed` de servidores na revisão mais recente por meio de um [stream que mantém aberto](#notification-streams-on-the-v2-runtime).
358* Não registra um servidor de [canal](#push-messages-with-channels) que se conecta na revisão mais recente, porque essa revisão não pode carregar mensagens de canal.358* Não registra um servidor de [canal](#push-messages-with-channels) que se conecta na revisão mais recente, porque essa revisão não pode transportar mensagens de canal.
359* Falha em um [login OAuth MCP](#authenticate-with-remote-mcp-servers) cuja resposta de autorização nomeia um emissor inesperado.359* Faz falhar um [login OAuth MCP](#authenticate-with-remote-mcp-servers) cuja resposta de autorização indica um emissor inesperado.
360* Envia [credenciais OAuth MCP](#authenticate-with-remote-mcp-servers) apenas para um endpoint de token servido sobre HTTPS ou em `localhost`, `127.0.0.1`, ou `::1`. O login falha para um servidor cujo endpoint de token é `http://` simples em qualquer outro lugar, como um dispositivo em sua rede local. Veja [Refusing to send credentials to non-https token endpoint](https://code.claude.com/docs/pt/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint).360* Envia credenciais [OAuth MCP](#authenticate-with-remote-mcp-servers) apenas para um endpoint de token servido via HTTPS ou em `localhost`, `127.0.0.1` ou `::1`. O login falha para um servidor cujo endpoint de token é `http://` simples em qualquer outro lugar, como um dispositivo na sua rede local. Consulte [Refusing to send credentials to non-https token endpoint](https://code.claude.com/docs/pt/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint).
361 361
362A Anthropic pode manter um servidor específico no protocolo anterior, ou fora desse stream, com uma feature flag que o Claude Code busca. Para escolher o runtime você mesmo, defina [`MCP_SDK_GENERATION`](https://code.claude.com/docs/pt/env-vars) como `v1` ou `v2`.362A Anthropic pode manter um servidor específico no protocolo anterior, ou fora desse stream, com uma feature flag que o Claude Code busca. Para escolher o runtime você mesmo, defina [`MCP_SDK_GENERATION`](https://code.claude.com/docs/pt/env-vars) como `v1` ou `v2`.
363 363
364Para decidir se o Claude Code pergunta aos servidores sobre a revisão mais recente, defina [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/pt/env-vars) como `auto` ou `legacy`. Com essa variável não definida, o Claude Code pode deixar de perguntar a um servidor stdio por 7 dias, por exemplo depois que o servidor sai quando perguntado. Para que um servidor atualizado seja perguntado mais cedo, defina `auto`.364Para decidir se o Claude Code pergunta aos servidores sobre a revisão mais recente, defina [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/pt/env-vars) como `auto` ou `legacy`. Com essa variável não definida, o Claude Code pode deixar de perguntar a um servidor stdio por 7 dias, por exemplo depois que o servidor encerra ao ser perguntado. Para que um servidor atualizado seja perguntado mais cedo, defina `auto`.
365 365
366### Atualizações dinâmicas de ferramentas366### Atualizações dinâmicas de ferramentas
367 367
368Um servidor MCP pode alterar as ferramentas, prompts ou recursos que oferece enquanto está conectado e enviar uma notificação `list_changed`. Quando uma chega:368Um servidor MCP pode alterar as ferramentas, prompts ou recursos que oferece enquanto está conectado e enviar uma notificação `list_changed`. Quando uma chega:
369 369
370* **Em uma sessão interativa no terminal**, Claude Code busca a lista atualizada desse servidor, portanto você não precisa reconectá-lo.370* **Em uma sessão interativa no terminal**, o Claude Code busca a lista atualizada desse servidor, então você não precisa reconectá-lo.
371* **No [modo não interativo](https://code.claude.com/docs/pt/headless.md) com a flag `-p` e no [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md)**, Claude Code atualiza apenas a lista de ferramentas nessas notificações.371* **No [modo não interativo](https://code.claude.com/docs/pt/headless.md) com a flag `-p` e no [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md)**, o Claude Code atualiza apenas a lista de ferramentas nessas notificações.
372 372
373Se uma solicitação de atualização falhar, Claude Code mantém as ferramentas, prompts e recursos descobertos anteriormente do servidor até que uma atualização posterior tenha sucesso.373Se uma requisição de atualização falhar, o Claude Code mantém as ferramentas, prompts e recursos descobertos anteriormente no servidor até que uma atualização posterior seja bem-sucedida.
374 374
375#### Streams de notificação no tempo de execução v2375#### Streams de notificação no runtime v2
376 376
377No [tempo de execução v2](#mcp-client-runtimes), Claude Code recebe notificações `list_changed` de um servidor na revisão de protocolo mais recente sobre um stream que mantém aberto. Quando o stream fecha, Claude Code o reabre, com dois limites:377No [runtime v2](#mcp-client-runtimes), o Claude Code recebe notificações `list_changed` de um servidor na revisão mais recente do protocolo por meio de um stream que mantém aberto. Quando o stream fecha, o Claude Code o reabre, com dois limites:
378 378
379* **O stream fecha novamente dentro de 10 segundos**: Claude Code o reabre até três vezes, depois para para essa conexão.379* **O stream fecha novamente em até 10 segundos**: o Claude Code o reabre até três vezes e depois para para essa conexão.
380* **O stream permanece aberto por mais de 10 segundos, depois fecha**, como streams para hosts sem servidor comumente fazem: após cinco reabertas em uma hora, Claude Code aguarda cerca de seis horas antes da próxima.380* **O stream permanece aberto por mais de 10 segundos e depois fecha**, como costuma acontecer com streams para hosts serverless: após cinco reaberturas em uma hora, o Claude Code aguarda cerca de seis horas antes da próxima.
381 381
382Até o stream reabrir, você mantém as ferramentas, prompts e recursos buscados pela última vez do servidor. Para pegar suas mudanças mais cedo, reconecte o servidor de `/mcp`.382Até que o stream seja reaberto, você mantém as últimas ferramentas, prompts e recursos buscados do servidor. Para obter suas alterações mais cedo, reconecte o servidor em `/mcp`.
383 383
384### Reconexão automática384### Reconexão automática
385 385
386Claude Code reconecta um servidor remoto que cai no meio da sessão e tenta novamente a primeira conexão de um servidor HTTP ou SSE após um erro transitório. Para um servidor stdio, veja [Servidores stdio que saem ou falham ao iniciar](#stdio-servers-that-exit-or-fail-to-start).386O Claude Code reconecta um servidor remoto que cai no meio da sessão e tenta novamente a primeira conexão de um servidor HTTP ou SSE após um erro transitório. Para um servidor stdio, consulte [Servidores stdio que encerram ou não iniciam](#stdio-servers-that-exit-or-fail-to-start).
387 387
388#### Quedas de um servidor remoto no meio da sessão388#### Quedas de um servidor remoto no meio da sessão
389 389
390Claude Code primeiro tenta reconectar um servidor remoto caído até cinco vezes com backoff exponencial, começando com um atraso de um segundo e dobrando-o a cada vez:390O Claude Code primeiro tenta reconectar um servidor remoto que caiu até cinco vezes com backoff exponencial, começando com um atraso de um segundo e dobrando-o a cada vez:
391 391
392* **Em uma sessão interativa**: `/mcp` mostra o servidor como pendente enquanto Claude Code reconecta. Após cinco tentativas falhadas, Claude Code marca o servidor como com falha, ou como precisando de autenticação quando o servidor precisa ser autorizado novamente. Quando marca o servidor como com falha, você vê uma notificação `MCP server "<name>" disconnected · open /mcp to reconnect`. Você pode tentar novamente manualmente de `/mcp`.392* **Em uma sessão interativa**: `/mcp` mostra o servidor como pendente enquanto o Claude Code reconecta. Após cinco tentativas com falha, o Claude Code marca o servidor como com falha, ou como precisando de autenticação quando o servidor precisa ser autorizado novamente. Quando marca o servidor como com falha, você vê uma notificação `MCP server "<name>" disconnected · open /mcp to reconnect`. Você pode tentar novamente manualmente em `/mcp`.
393* **Em execuções [`claude -p`](https://code.claude.com/docs/pt/headless) e sessões [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md)**: Claude Code faz as mesmas cinco tentativas, sem painel `/mcp` para mostrá-las. Se todas as cinco falharem, a execução continua sem as ferramentas do servidor:393* **Em execuções [`claude -p`](https://code.claude.com/docs/pt/headless) e sessões do [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md)**: o Claude Code faz as mesmas cinco tentativas, sem um painel `/mcp` para exibi-las. Se todas as cinco falharem, a execução continua sem as ferramentas do servidor:
394 * **Após um erro transitório, como uma resposta 5xx ou um timeout**: Claude Code continua tentando novamente um servidor HTTP ou SSE em segundo plano. As novas tentativas duram até cerca de meia hora, e as ferramentas do servidor ficam disponíveis novamente quando uma delas se conecta. Até lá, uma sessão do Agent SDK relata o [status](https://code.claude.com/docs/pt/agent-sdk/mcp.md#error-handling) `failed`, e seu código pode [reconectar o servidor](https://code.claude.com/docs/pt/agent-sdk/mcp.md#error-handling). Para reconectá-lo em `claude -p`, inicie a execução novamente.394 * **Após um erro transitório, como uma resposta 5xx ou um timeout**: o Claude Code continua tentando novamente um servidor HTTP ou SSE em segundo plano. As novas tentativas duram até cerca de meia hora, e as ferramentas do servidor voltam a ficar disponíveis quando uma delas se conecta. Até lá, uma sessão do Agent SDK informa o [status](https://code.claude.com/docs/pt/agent-sdk/mcp.md#error-handling) `failed`, e seu código pode [reconectar o servidor](https://code.claude.com/docs/pt/agent-sdk/mcp.md#error-handling). Para reconectá-lo em `claude -p`, inicie a execução novamente.
395 * **Quando o servidor [precisa que você faça login novamente](#authenticate-with-remote-mcp-servers)**: Claude Code para de tentar novamente, e uma sessão do Agent SDK relata o status do servidor como `needs-auth`. Faça login com [`claude mcp login <name>`](#authenticate-from-the-command-line) no seu shell. Em seguida, inicie a execução novamente ou, em uma sessão do Agent SDK, [reconecte o servidor](https://code.claude.com/docs/pt/agent-sdk/mcp.md#error-handling) em vez disso.395 * **Quando o servidor [precisa que você faça login novamente](#authenticate-with-remote-mcp-servers)**: o Claude Code para de tentar novamente, e uma sessão do Agent SDK informa o status do servidor como `needs-auth`. Faça login com [`claude mcp login <name>`](#authenticate-from-the-command-line) no seu shell. Em seguida, inicie a execução novamente ou, em uma sessão do Agent SDK, [reconecte o servidor](https://code.claude.com/docs/pt/agent-sdk/mcp.md#error-handling).
396 396
397#### Primeiras conexões com falha397#### Primeiras conexões com falha
398 398
399Quando a primeira conexão de um servidor HTTP ou SSE falha com um erro transitório, como uma resposta 5xx, uma conexão recusada, ou um tempo limite, Claude Code tenta novamente até três vezes. Se a conexão ainda falhar, Claude Code marca o servidor como com falha.399Quando a primeira conexão de um servidor HTTP ou SSE falha com um erro transitório, como uma resposta 5xx, uma conexão recusada ou um timeout, o Claude Code tenta novamente até três vezes. Se a conexão ainda falhar, o Claude Code marca o servidor como com falha.
400 400
401Essas novas tentativas não se aplicam nestes casos:401Essas novas tentativas não se aplicam nestes casos:
402 402
403* A primeira conexão de um servidor stdio. Para tentá-la novamente, veja [Servidores stdio que saem ou falham ao iniciar](#stdio-servers-that-exit-or-fail-to-start)403* A primeira conexão de um servidor stdio. Para tentar novamente, consulte [Servidores stdio que encerram ou não iniciam](#stdio-servers-that-exit-or-fail-to-start)
404* A primeira conexão de um servidor WebSocket. Para tentar novamente em uma sessão interativa no terminal, selecione **Reconnect** no menu do servidor em `/mcp`404* A primeira conexão de um servidor WebSocket. Para tentar novamente em uma sessão interativa no terminal, selecione **Reconnect** no menu do servidor em `/mcp`
405* Um erro de autenticação ou não encontrado, porque requer uma mudança de configuração para resolver. Quando um [`headersHelper`](#use-dynamic-headers-for-custom-authentication) é a única fonte do servidor do cabeçalho `Authorization`, Claude Code tenta novamente um erro de autenticação mesmo assim, porque re-executa o helper em cada tentativa e pode pegar uma credencial fresca405* Um erro de autenticação ou de não encontrado, porque requer uma alteração de configuração para ser resolvido. Quando um [`headersHelper`](#use-dynamic-headers-for-custom-authentication) é a única fonte do cabeçalho `Authorization` do servidor, o Claude Code tenta novamente mesmo assim após um erro de autenticação, porque executa o helper novamente a cada tentativa e pode obter uma credencial nova
406 406
407#### Servidores stdio que saem ou falham ao iniciar407#### Servidores stdio que encerram ou não iniciam
408 408
409Para iniciar um servidor stdio novamente, leia a coluna que corresponde ao que aconteceu com ele. Encontre sua linha pela forma como você executa o Claude Code: uma sessão interativa, uma execução `claude -p` ou uma sessão do Agent SDK.409Para iniciar um servidor stdio novamente, leia a coluna que corresponde ao que aconteceu com ele. Encontre sua linha pela forma como você executa o Claude Code: uma sessão interativa, uma execução `claude -p` ou uma sessão do Agent SDK.
410 410
411| Como você executa o Claude Code | O processo do servidor sai no meio da sessão | A primeira conexão do servidor falha |411| Como você executa o Claude Code | O processo do servidor encerra no meio da sessão | A primeira conexão do servidor falha |
412| - | - | - |412| - | - | - |
413| Sessão interativa | Claude Code marca o servidor como com falha. Para iniciá-lo novamente, selecione **Reconnect** no menu do servidor em `/mcp` | Claude Code marca o servidor como com falha. Para iniciá-lo novamente, selecione **Reconnect** no menu do servidor em `/mcp` |413| Sessão interativa | O Claude Code marca o servidor como com falha. Para iniciá-lo novamente, selecione **Reconnect** no menu do servidor em `/mcp` | O Claude Code marca o servidor como com falha. Para iniciá-lo novamente, selecione **Reconnect** no menu do servidor em `/mcp` |
414| Execução `claude -p` | Claude Code inicia o servidor novamente na próxima vez que Claude chamar uma das ferramentas do servidor, e a chamada é executada assim que o servidor se conecta | A execução continua sem as ferramentas do servidor. Para que Claude Code tente a conexão novamente, inicie a execução novamente. Quando um plugin fornece o servidor, novas execuções pulam a conexão por 15 minutos após uma falha, portanto aguarde esse tempo primeiro ou [tente novamente mais cedo](https://code.claude.com/docs/pt/errors.md#skipping-connection-recent-failure-cached) |414| Execução `claude -p` | O Claude Code inicia o servidor novamente na próxima vez que o Claude chama uma das ferramentas do servidor, e a chamada é executada assim que o servidor se conecta | A execução continua sem as ferramentas do servidor. Para que o Claude Code tente a conexão novamente, inicie a execução novamente. Quando um plugin fornece o servidor, novas execuções ignoram a conexão por 15 minutos após uma falha, então aguarde esse tempo antes ou [tente novamente mais cedo](https://code.claude.com/docs/pt/errors.md#skipping-connection-recent-failure-cached) |
415| Sessão do Agent SDK | Claude Code inicia o servidor novamente na próxima vez que Claude chamar uma das ferramentas do servidor, e a chamada é executada assim que o servidor se conecta | A sessão continua sem as ferramentas do servidor. Seu código pode [reconectar o servidor](https://code.claude.com/docs/pt/agent-sdk/mcp.md#error-handling) |415| Sessão do Agent SDK | O Claude Code inicia o servidor novamente na próxima vez que o Claude chama uma das ferramentas do servidor, e a chamada é executada assim que o servidor se conecta | A sessão continua sem as ferramentas do servidor. Seu código pode [reconectar o servidor](https://code.claude.com/docs/pt/agent-sdk/mcp.md#error-handling) |
416 416
417#### Solicitações de descoberta com falha417#### Requisições de descoberta com falha
418 418
419Depois que um servidor se conecta, Claude Code o envia solicitações de descoberta de capacidade como `tools/list`, `prompts/list`, e `resources/list`. Claude Code tenta novamente essas solicitações até três vezes com backoff curto após um erro de rede ou servidor transitório. Ele não tenta novamente erros de autenticação, respostas 4xx, ou tempos limite de solicitação.419Depois que um servidor se conecta, o Claude Code envia a ele requisições de descoberta de capacidades como `tools/list`, `prompts/list` e `resources/list`. O Claude Code tenta novamente essas requisições até três vezes com um backoff curto após um erro transitório de rede ou de servidor. Ele não tenta novamente após erros de autenticação, respostas 4xx ou timeouts de requisição.
420 420
421#### Tentar novamente servidores com falha você mesmo421#### Tentar novamente servidores com falha por conta própria
422 422
423Para tentar novamente todos os servidores que falharam ou precisam de autenticação, execute `/mcp reconnect all` no prompt do Claude Code em uma sessão interativa no terminal. Isso requer o Claude Code v2.1.284 ou posterior. Versões anteriores imprimem `MCP server "all" not found`.423Para tentar novamente todos os servidores que falharam ou precisam de autenticação, execute `/mcp reconnect all` no prompt do Claude Code em uma sessão interativa no terminal. Isso requer o Claude Code v2.1.284 ou posterior. Versões anteriores imprimem `MCP server "all" not found`.
424 424
425#### Como Claude descobre que um servidor falhou425#### Como o Claude fica sabendo que um servidor falhou
426 426
427Se Claude Code diz a Claude sobre um servidor configurado que falhou em se conectar depende de [busca de ferramentas](#scale-with-mcp-tool-search), que está ativada por padrão:427Se o Claude Code informa o Claude sobre um servidor configurado que não conseguiu se conectar depende da [pesquisa de ferramentas](#scale-with-mcp-tool-search), que está ativada por padrão:
428 428
429* Com busca de ferramentas, Claude Code diz a Claude qual servidor falhou e seu erro de conexão, portanto Claude relata a falha de conexão em sua resposta. Claude Code inclui as mesmas informações nos resultados de `ToolSearch` que não encontram nenhuma ferramenta correspondente.429* Com a pesquisa de ferramentas, o Claude Code informa ao Claude qual servidor falhou e seu erro de conexão, para que o Claude relate a falha de conexão em sua resposta. O Claude Code inclui as mesmas informações nos resultados de `ToolSearch` que não encontram nenhuma ferramenta correspondente.
430* Em qualquer [configuração sem busca de ferramentas](#configure-tool-search), Claude Code não relata falhas de conexão de servidor a Claude.430* Em qualquer [configuração sem pesquisa de ferramentas](#configure-tool-search), o Claude Code não informa ao Claude sobre conexões de servidor com falha.
431 431
432### Enviar mensagens com canais432### Enviar mensagens com canais
433 433
434Um servidor MCP também pode enviar mensagens diretamente para sua sessão para que Claude possa reagir a eventos externos como resultados de CI, alertas de monitoramento, ou mensagens de chat. Para ativar isso, seu servidor declara a capacidade `claude/channel` e você o ativa com o sinalizador `--channels` na inicialização. Veja [Channels](https://code.claude.com/docs/pt/channels.md) para usar um canal oficialmente suportado, ou [Channels reference](https://code.claude.com/docs/pt/channels-reference.md) para construir o seu próprio.434Um servidor MCP também pode enviar mensagens diretamente para sua sessão para que o Claude possa reagir a eventos externos, como resultados de CI, alertas de monitoramento ou mensagens de chat. Para habilitar isso, seu servidor declara a capacidade `claude/channel` e você o habilita com a flag `--channels` na inicialização. Consulte [Channels](https://code.claude.com/docs/pt/channels.md) para usar um canal com suporte oficial, ou [Referência de Channels](https://code.claude.com/docs/pt/channels-reference.md) para criar o seu próprio.
435 435
436No [tempo de execução v2](#mcp-client-runtimes), um servidor de canal que negocia a revisão de protocolo MCP 2026-07-28 não pode entregar mensagens de canal, portanto Claude Code não o registra como um canal. Um servidor de canal que não suporta essa revisão se conecta no handshake anterior e se registra como antes.436No [runtime v2](#mcp-client-runtimes), um servidor de canal que negocia a revisão 2026-07-28 do protocolo MCP não pode entregar mensagens de canal, então o Claude Code não o registra como canal. Um servidor de canal que não oferece suporte a essa revisão se conecta no handshake anterior e se registra como antes.
437 437
438Claude Code pergunta aos servidores stdio por essa revisão por padrão. Para manter um servidor de canal stdio no handshake anterior, defina [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/pt/env-vars) como `legacy`, o que mantém todos os servidores nele.438O Claude Code pergunta aos servidores stdio sobre essa revisão por padrão. Para manter um servidor de canal stdio no handshake anterior, defina [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/pt/env-vars) como `legacy`, o que mantém todos os servidores nele.
439 439
440> [!TIP]440> [!TIP]
441>441>
442> Dicas:442> Dicas:
443>443>
444> * Use o sinalizador `-s` ou `--scope` para especificar onde a configuração é armazenada:444> * Use a flag `-s` ou `--scope` para especificar onde a configuração é armazenada:
445> * `local` (padrão): disponível apenas para você no projeto atual445> * `local` (padrão): disponível apenas para você no projeto atual
446> * `project`: compartilhado com todos no projeto via arquivo `.mcp.json`446> * `project`: compartilhado com todos no projeto por meio do arquivo `.mcp.json`
447> * `user`: disponível para você em todos os projetos447> * `user`: disponível para você em todos os projetos
448> * Defina variáveis de ambiente com sinalizadores `-e` ou `--env` (por exemplo, `-e KEY=value`)448> * Defina variáveis de ambiente com as flags `-e` ou `--env` (por exemplo, `-e KEY=value`)
449> * Os sinalizadores `--transport` e `--header` também aceitam formas curtas `-t` e `-H`449> * As flags `--transport` e `--header` também aceitam as formas curtas `-t` e `-H`
450> * Configure o tempo limite de inicialização do servidor MCP usando a variável de ambiente `MCP_TIMEOUT` (por exemplo, `MCP_TIMEOUT=10000 claude` define um tempo limite de 10 segundos)450> * Configure o timeout de inicialização do servidor MCP usando a variável de ambiente `MCP_TIMEOUT` (por exemplo, `MCP_TIMEOUT=10000 claude` define um timeout de 10 segundos)
451> * Defina um tempo limite de execução de ferramenta por servidor adicionando um campo `timeout` em milissegundos à entrada `.mcp.json` desse servidor, por exemplo `"timeout": 600000` para dez minutos. Isso sobrescreve a variável de ambiente `MCP_TOOL_TIMEOUT` apenas para esse servidor451> * Defina um timeout de execução de ferramentas por servidor adicionando um campo `timeout` em milissegundos à entrada desse servidor no `.mcp.json`, por exemplo `"timeout": 600000` para dez minutos. Isso sobrescreve a variável de ambiente `MCP_TOOL_TIMEOUT` apenas para esse servidor
452> * Claude Code exibe um aviso quando a saída da ferramenta MCP excede 10.000 tokens e limita a saída a 25.000 tokens por padrão. Para alterar o limite de tokens, defina a variável de ambiente `MAX_MCP_OUTPUT_TOKENS`, por exemplo `MAX_MCP_OUTPUT_TOKENS=50000`. O limite de aviso é fixo. A menos que o servidor aumente o limite próprio de uma ferramenta, resultados de texto bem-sucedidos com mais de 50.000 caracteres são salvos em um arquivo independentemente desta variável. Veja [MCP output limits and warnings](#mcp-output-limits-and-warnings)452> * O Claude Code exibe um aviso quando a saída de uma ferramenta MCP excede 10.000 tokens e limita a saída a 25.000 tokens por padrão. Para alterar o limite de tokens, defina a variável de ambiente `MAX_MCP_OUTPUT_TOKENS`, por exemplo `MAX_MCP_OUTPUT_TOKENS=50000`. O limite do aviso é fixo. A menos que o servidor aumente o limite próprio de uma ferramenta, resultados de texto bem-sucedidos com mais de 50.000 caracteres são salvos em um arquivo independentemente dessa variável. Consulte [Limites e avisos de saída MCP](#mcp-output-limits-and-warnings)
453> * Use `/mcp` para autenticar com servidores remotos que requerem autenticação OAuth 2.0453> * Use `/mcp` para se autenticar em servidores remotos que exigem autenticação OAuth 2.0
454 454
455### Limites de tempo em chamadas de ferramentas MCP455### Limites de tempo em chamadas de ferramentas MCP
456 456
457Para limitar por quanto tempo uma chamada de ferramenta MCP pode ser executada:457Para limitar por quanto tempo uma chamada de ferramenta MCP pode ser executada:
458 458
459* **Por servidor**: adicione um campo `timeout` em milissegundos à entrada de configuração desse servidor459* **Por servidor**: adicione um campo `timeout` em milissegundos à entrada de configuração desse servidor
460* **Em todos os servidores**: defina [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/pt/env-vars)460* **Para todos os servidores**: defina [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/pt/env-vars)
461 461
462O `timeout` por servidor é um limite rígido de tempo real por chamada de ferramenta, e notificações de progresso do servidor não o estendem. Valores abaixo de 1000 são ignorados e caem para `MCP_TOOL_TIMEOUT`, ou para seu padrão de cerca de 28 horas quando essa variável não está definida. Para um servidor HTTP, SSE, ou [conector claude.ai](https://code.claude.com/docs/pt/mcp.md#use-mcp-servers-from-claude-ai) há também um segundo temporizador por solicitação que cobre cada solicitação até o primeiro byte de resposta do servidor. Claude Code define esse temporizador para o maior de três valores: 60 segundos, o tempo limite de ferramenta que se aplica ao servidor, e `MCP_TIMEOUT`. O padrão de 28 horas de um `MCP_TOOL_TIMEOUT` não definido não entra nessa comparação, e um valor abaixo de 60 segundos não encurta o temporizador. Os servidores Stdio e WebSocket não têm temporizador por solicitação.462O `timeout` por servidor é um limite rígido de tempo real por chamada de ferramenta, e notificações de progresso do servidor não o estendem. Valores abaixo de 1000 são ignorados e recorrem a `MCP_TOOL_TIMEOUT`, ou ao seu padrão de cerca de 28 horas quando essa variável não está definida. Para um servidor HTTP, SSE ou de [conector do claude.ai](https://code.claude.com/docs/pt/mcp.md#use-mcp-servers-from-claude-ai), também existe um segundo temporizador, por requisição, que cobre cada requisição até o primeiro byte da resposta do servidor. O Claude Code define esse temporizador como o maior de três valores: 60 segundos, o timeout de ferramenta que se aplica ao servidor e `MCP_TIMEOUT`. O padrão de 28 horas de um `MCP_TOOL_TIMEOUT` não definido não entra nessa comparação, e um valor abaixo de 60 segundos não encurta o temporizador. Servidores stdio e WebSocket não têm temporizador por requisição.
463 463
464Um `timeout` por servidor de pelo menos 1000 também atua como um piso no tempo limite de inatividade descrito abaixo: Claude Code nunca aborta as chamadas de ferramenta desse servidor por inatividade mais cedo do que o `timeout` por servidor.464Um `timeout` por servidor de pelo menos 1000 também atua como piso para o timeout de inatividade descrito abaixo: o Claude Code nunca interrompe as chamadas de ferramenta desse servidor por inatividade antes do `timeout` por servidor.
465 465
466Uma chamada de ferramenta para um servidor MCP que não envia resposta e nenhuma notificação de progresso para a janela de inatividade aborta com um erro em vez de aguardar o limite de tempo real. O tempo limite de inatividade se aplica a todos os tipos de servidor exceto servidores IDE e SDK em processo. A janela de inatividade padrão é de cinco minutos para servidores HTTP, SSE, WebSocket, e [conector claude.ai](#use-mcp-servers-from-claude-ai), e de 30 minutos para servidores stdio.466Uma chamada de ferramenta para um servidor MCP que não envia nenhuma resposta nem notificação de progresso durante a janela de inatividade é interrompida com um erro em vez de aguardar o limite de tempo real. O timeout de inatividade se aplica a todos os tipos de servidor, exceto servidores de IDE e servidores SDK em processo. A janela de inatividade tem como padrão cinco minutos para servidores HTTP, SSE, WebSocket e de [conector do claude.ai](#use-mcp-servers-from-claude-ai), e 30 minutos para servidores stdio.
467 467
468Defina a variável de ambiente [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/pt/env-vars) em milissegundos para alterar a janela de inatividade, ou defina-a como `0` para desabilitar a verificação.468Defina a variável de ambiente [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/pt/env-vars) em milissegundos para alterar a janela de inatividade, ou defina-a como `0` para desativar a verificação.
469 469
470Esses tempos limite limitam quanto tempo uma chamada pode ser executada, nem sempre quanto tempo bloqueia a sessão: uma chamada de conversa principal que é executada por mais de dois minutos se move para uma tarefa em segundo plano primeiro. Veja [Automatic backgrounding of long tool calls](#automatic-backgrounding-of-long-tool-calls).470Esses timeouts limitam por quanto tempo uma chamada pode ser executada, nem sempre por quanto tempo ela bloqueia a sessão: uma chamada da conversa principal que passa de dois minutos é movida primeiro para uma tarefa em segundo plano. Consulte [Envio automático de chamadas de ferramentas longas para segundo plano](#automatic-backgrounding-of-long-tool-calls).
471 471
472### Execução automática em segundo plano de chamadas de ferramenta longas472### Envio automático de chamadas de ferramentas longas para segundo plano
473 473
474Se a visualização de detalhes de uma chamada em segundo plano em [`/tasks`](https://code.claude.com/docs/pt/commands#all-commands) mostrar `runs on the server; survives exiting this session`, consulte [Tarefas MCP executadas no servidor](#mcp-tasks-that-run-on-the-server).474Se a visualização de detalhes de uma chamada em segundo plano em [`/tasks`](https://code.claude.com/docs/pt/commands#all-commands) mostrar `runs on the server; survives exiting this session`, consulte [Tarefas MCP executadas no servidor](#mcp-tasks-that-run-on-the-server).
475 475
476Uma chamada de ferramenta MCP na conversa principal que ainda está em execução após dois minutos se move para uma tarefa em segundo plano em vez de bloquear a sessão. Claude recebe o ID da tarefa imediatamente e continua trabalhando, e o resultado chega como uma notificação de tarefa quando a chamada se resolve.476Uma chamada de ferramenta MCP na conversa principal que ainda está em execução após dois minutos é movida para uma tarefa em segundo plano em vez de bloquear a sessão. O Claude recebe o ID da tarefa imediatamente e continua trabalhando, e o resultado chega como uma notificação de tarefa quando a chamada é concluída.
477 477
478A tarefa aparece em [`/tasks`](https://code.claude.com/docs/pt/commands#all-commands), onde você também pode pará-la, e não sobrevive ao sair da sessão. A entrada da tarefa mostra o progresso mais recente que o servidor relatou. Se você parar a tarefa, Claude Code cancela a chamada e informa a Claude que nenhum resultado virá. Parar não garante que o servidor pare: ele pode já ter feito parte do trabalho, ou ainda pode concluí-lo.478A tarefa aparece em [`/tasks`](https://code.claude.com/docs/pt/commands#all-commands), onde você também pode interrompê-la, e ela não sobrevive ao encerramento da sessão. A entrada da tarefa mostra o progresso mais recente informado pelo servidor. Se você interromper a tarefa, o Claude Code cancela a chamada e informa ao Claude que nenhum resultado virá. Interromper não garante que o servidor pare: ele pode já ter feito parte do trabalho, ou ainda pode concluí-lo.
479 479
480Os limites por chamada ainda se aplicam enquanto a chamada é executada em segundo plano: o limite de tempo real definido pelo `timeout` por servidor ou [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/pt/env-vars), e o tempo limite de inatividade definido por [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/pt/env-vars).480Os limites por chamada continuam se aplicando enquanto a chamada é executada em segundo plano: o limite de tempo real definido pelo `timeout` por servidor ou por [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/pt/env-vars), e o timeout de inatividade definido por [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/pt/env-vars).
481 481
482Para alterar ou desativar a execução automática em segundo plano:482Para alterar ou desativar o envio automático para segundo plano:
483 483
484* Defina a variável de ambiente [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/pt/env-vars) em milissegundos para alterar o limite, ou defina-a como `0` para desativar a execução automática em segundo plano. Com `0`, o Claude também [aguarda tarefas MCP](#make-claude-wait-for-the-result-of-an-mcp-task) em uma sessão interativa484* Defina a variável de ambiente [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/pt/env-vars) em milissegundos para alterar o limite, ou defina-a como `0` para desativar o envio automático para segundo plano. Com `0`, o Claude também [aguarda tarefas MCP](#make-claude-wait-for-the-result-of-an-mcp-task) em uma sessão interativa
485* Defina [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/pt/env-vars) como `1` para desativar o envio automático para segundo plano e os [comandos em segundo plano](https://code.claude.com/docs/pt/tools-reference.md#background-commands)485* Defina [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/pt/env-vars) como `1` para desativar o envio automático para segundo plano e os [comandos em segundo plano](https://code.claude.com/docs/pt/tools-reference.md#background-commands)
486 486
487Algumas chamadas nunca se movem para o segundo plano:487Algumas chamadas nunca são movidas para segundo plano:
488 488
489* Chamadas de [subagentes](https://code.claude.com/docs/pt/sub-agents.md); Claude Code coloca em segundo plano apenas chamadas de conversa principal489* Chamadas de [subagentes](https://code.claude.com/docs/pt/sub-agents.md); o Claude Code envia para segundo plano apenas chamadas da conversa principal
490* Chamadas para servidores IDE490* Chamadas para servidores de IDE
491* Chamadas em [modo não interativo](https://code.claude.com/docs/pt/headless.md), a menos que `CLAUDE_AUTO_BACKGROUND_TASKS` esteja definido como `1`, já que uma execução única pode terminar antes do resultado chegar491* Chamadas no [modo não interativo](https://code.claude.com/docs/pt/headless.md), a menos que `CLAUDE_AUTO_BACKGROUND_TASKS` esteja definida como `1`, já que uma execução única pode terminar antes de o resultado chegar
492 492
493Uma chamada aguardando um [diálogo de elicitação](#respond-to-mcp-elicitation-requests) aberto não é colocada em segundo plano enquanto o diálogo está aberto; o servidor está bloqueado em sua entrada, não lento, portanto Claude Code adia a mudança até o diálogo fechar.493Uma chamada que aguarda uma [caixa de diálogo de elicitação](#respond-to-mcp-elicitation-requests) aberta não é enviada para segundo plano enquanto a caixa de diálogo estiver aberta; o servidor está bloqueado aguardando sua entrada, não lento, então o Claude Code adia a mudança até que a caixa de diálogo seja fechada.
494 494
495### Tarefas MCP executadas no servidor495### Tarefas MCP executadas no servidor
496 496
497Uma tarefa MCP é um trabalho longo, como uma exportação de relatório ou um build, que um servidor MCP executa por conta própria usando a [extensão de tarefas do MCP](https://modelcontextprotocol.io/extensions/tasks/overview). A chamada de ferramenta do Claude retorna assim que o servidor aceita o trabalho, então o Claude continua trabalhando, a menos que você [faça o Claude aguardar](#make-claude-wait-for-the-result-of-an-mcp-task). Quando o trabalho termina, a transcrição informa isso e o Claude recebe o resultado. Peça-o ao Claude.497Uma tarefa MCP é um trabalho longo, como uma exportação de relatório ou um build, que um servidor MCP executa por conta própria usando a [extensão de tarefas MCP](https://modelcontextprotocol.io/extensions/tasks/overview). A chamada de ferramenta do Claude retorna assim que o servidor aceita o trabalho, então o Claude continua trabalhando, a menos que você [faça o Claude aguardar](#make-claude-wait-for-the-result-of-an-mcp-task). Quando o trabalho termina, a transcrição informa isso e o Claude recebe o resultado. Peça-o ao Claude.
498 498
499Enquanto isso, o rodapé mostra uma contagem como `1 MCP task`, e o Claude Code acompanha a tarefa verificando seu status com o servidor. Uma tarefa em um servidor remoto continua em execução depois que você sai. Para acompanhá-la novamente, [retome a mesma sessão](#exit-clear-or-resume-while-an-mcp-task-runs).499Enquanto isso, o rodapé mostra uma contagem como `1 MCP task`, e o Claude Code acompanha a tarefa verificando seu status com o servidor. Uma tarefa em um servidor remoto continua em execução depois que você sai. Para acompanhá-la novamente, [retome a mesma sessão](#exit-clear-or-resume-while-an-mcp-task-runs).
500 500
504 504
505#### Interromper uma tarefa MCP ou obter seu resultado505#### Interromper uma tarefa MCP ou obter seu resultado
506 506
507Para interromper uma tarefa em execução, selecione-a em [`/tasks`](https://code.claude.com/docs/pt/commands#all-commands) e pressione `x`, ou peça ao Claude que o faça. O Claude Code para de acompanhar a tarefa e pede ao servidor que a cancele, embora o servidor ainda possa concluí-la. Reconecte primeiro um servidor desconectado a partir de `/mcp`, caso contrário nenhuma requisição de cancelamento é enviada e o Claude Code esquece a tarefa e não consegue acompanhá-la novamente. Pressionar `Esc` não interrompe uma tarefa em segundo plano.507Para interromper uma tarefa em execução, selecione-a em [`/tasks`](https://code.claude.com/docs/pt/commands#all-commands) e pressione `x`, ou peça ao Claude que faça isso. O Claude Code para de acompanhar a tarefa e pede ao servidor que a cancele, embora o servidor ainda possa concluí-la. Reconecte primeiro um servidor desconectado em `/mcp`; caso contrário, nenhuma requisição de cancelamento é enviada e o Claude Code esquece a tarefa e não pode acompanhá-la novamente. Pressionar `Esc` não interrompe uma tarefa em segundo plano.
508 508
509Quando a tarefa termina, uma linha como esta aparece na transcrição:509Quando a tarefa termina, uma linha como esta aparece na transcrição:
510 510
512MCP task <server task id> (<server>/<tool>) completed.512MCP task <server task id> (<server>/<tool>) completed.
513```513```
514 514
515O resultado vai para o Claude, não para a transcrição, então peça-o ao Claude. Se o Claude estiver ocioso quando o resultado chegar, o Claude começa a trabalhar nele sem solicitação.515O resultado vai para o Claude, não para a transcrição, então peça-o ao Claude. Se o Claude estiver ocioso quando o resultado chegar, o Claude começa a trabalhar nele sem que você peça.
516 516
517#### Responder a uma pergunta de uma tarefa MCP517#### Responder a uma pergunta de uma tarefa MCP
518 518
522 522
523#### Sair, limpar ou retomar enquanto uma tarefa MCP é executada523#### Sair, limpar ou retomar enquanto uma tarefa MCP é executada
524 524
525Uma tarefa em um servidor remoto continua em execução depois que você sai. O processo de um servidor stdio é encerrado quando o Claude Code sai, embora suas tarefas mostrem `runs on the server; survives exiting this session` em `/tasks`. A menos que a documentação desse servidor diga que o trabalho sobrevive ao processo, deixe essas tarefas terminarem ou interrompa-as em `/tasks` primeiro.525Uma tarefa em um servidor remoto continua em execução depois que você sai. O processo de um servidor stdio para quando o Claude Code sai, embora suas tarefas mostrem `runs on the server; survives exiting this session` em `/tasks`. A menos que a documentação desse servidor diga que o trabalho sobrevive ao processo, deixe essas tarefas terminarem ou interrompa-as em `/tasks` antes.
526 526
527| Situação | O que acontece com a tarefa | O que você pode fazer |527| Situação | O que acontece com a tarefa | O que você pode fazer |
528| - | - | - |528| - | - | - |
529| Você executa `/clear` ou `/branch`, ou usa `/resume` para outra sessão | Enquanto o Claude Code permanece aberto, o resultado chega na sua conversa atual | Após sair, use `claude --resume` na sessão em que a tarefa começou |529| Você executa `/clear` ou `/branch`, ou usa `/resume` para outra sessão | Enquanto o Claude Code permanecer aberto, o resultado chega na sua conversa atual | Depois de sair, use `claude --resume` na sessão em que a tarefa começou |
530| Você sai do Claude Code | Nenhuma opção de saída cancela a tarefa de um servidor remoto, mesmo quando a caixa de diálogo de saída a lista em `The following will stop when you exit:` | Interrompa-a em `/tasks` primeiro, ou retome a mesma sessão mais tarde |530| Você sai do Claude Code | Nenhuma opção de saída cancela a tarefa de um servidor remoto, mesmo quando a caixa de diálogo de saída a lista em `The following will stop when you exit:` | Interrompa-a em `/tasks` antes, ou retome a mesma sessão depois |
531| Você retorna à sessão da tarefa interativamente: `claude --resume`, `claude --continue` ou `/resume` | Assim que o servidor se conecta, o Claude Code acompanha a tarefa novamente, e o Claude recebe o resultado se ela tiver terminado nesse meio-tempo e o servidor ainda a conhecer | Mantenha o nome e as configurações de conexão do servidor inalterados |531| Você volta à sessão da tarefa interativamente: `claude --resume`, `claude --continue` ou `/resume` | Assim que o servidor se conecta, o Claude Code volta a acompanhar a tarefa, e o Claude recebe o resultado se ela tiver terminado nesse meio-tempo e o servidor ainda a conhecer | Mantenha o nome e as configurações de conexão do servidor inalterados |
532| Você retoma a sessão da tarefa com `--resume` ou `--continue` em uma execução única `claude -p "<prompt>"` | Essa execução não acompanha a tarefa | Retome interativamente, ou com `--input-format stream-json` |532| Você retoma a sessão da tarefa com `--resume` ou `--continue` em uma execução única `claude -p "<prompt>"` | Essa execução não acompanha a tarefa | Retome interativamente, ou com `--input-format stream-json` |
533| Você inicia uma nova sessão ou usa `--fork-session` | A nova sessão não acompanha a tarefa | Retome a sessão que a iniciou |533| Você inicia uma nova sessão ou usa `--fork-session` | A nova sessão não acompanha a tarefa | Retome a sessão que a iniciou |
534 534
535#### O que uma chamada precisa para se tornar uma tarefa MCP535#### O que uma chamada precisa para se tornar uma tarefa MCP
536 536
537Uma chamada de ferramenta se torna uma tarefa MCP apenas quando todas estas condições são atendidas:537Uma chamada de ferramenta se torna uma tarefa MCP somente quando todas estas condições são atendidas:
538 538
539* O servidor oferece suporte a tarefas539* O servidor oferece suporte a tarefas
540* O servidor é um servidor HTTP, stdio ou de conector do claude.ai conectado na [revisão 2026-07-28 do protocolo](#mcp-client-runtimes). Definir [`MCP_SDK_GENERATION=v1` ou `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/pt/env-vars) exclui essa possibilidade540* O servidor é um servidor HTTP, stdio ou de conector do claude.ai conectado na [revisão de protocolo 2026-07-28](#mcp-client-runtimes). Definir [`MCP_SDK_GENERATION=v1` ou `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/pt/env-vars) exclui isso
541* A sessão [busca feature flags](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching), portanto não em um provedor terceirizado como o Amazon Bedrock, e não com a telemetria ou a busca de flags desativada541* A sessão [busca feature flags](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching), portanto não em um provedor terceiro como o Amazon Bedrock, nem com a telemetria ou a busca de flags desativada
542* A Anthropic ativou as tarefas MCP para o seu tipo de sessão. Na v2.1.304 ou posterior, isso abrange sessões da CLI no terminal, sessões do [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md) e execuções do [GitHub Actions](https://code.claude.com/docs/pt/github-actions.md). Outras superfícies, como a [extensão do VS Code](https://code.claude.com/docs/pt/vs-code.md) e o [aplicativo desktop](https://code.claude.com/docs/pt/desktop.md), não têm tarefas MCP542* A Anthropic ativou as tarefas MCP para o seu tipo de sessão. Na v2.1.304 ou posterior, isso abrange sessões da CLI no terminal, sessões do [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md) e execuções do [GitHub Actions](https://code.claude.com/docs/pt/github-actions.md). Outras superfícies, como a [extensão do VS Code](https://code.claude.com/docs/pt/vs-code.md) e o [aplicativo desktop](https://code.claude.com/docs/pt/desktop.md), não têm tarefas MCP
543* A chamada vem da conversa principal, não de um [subagente](https://code.claude.com/docs/pt/sub-agents.md)543* A chamada vem da conversa principal, não de um [subagente](https://code.claude.com/docs/pt/sub-agents.md)
544* Ou a sessão é interativa, ou uma sessão do [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md) ou uma execução `claude -p` lendo `--input-format stream-json` tem:544* Ou a sessão é interativa, ou uma sessão do [Agent SDK](https://code.claude.com/docs/pt/agent-sdk/overview.md) ou uma execução `claude -p` lendo `--input-format stream-json` tem:
546 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` diferente de `1`546 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` diferente de `1`
547 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` diferente de `0`547 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` diferente de `0`
548 548
549Qualquer outra chamada é uma chamada de ferramenta simples, e [Execução automática em segundo plano de chamadas de ferramenta longas](#automatic-backgrounding-of-long-tool-calls) informa quais delas são movidas para o segundo plano.549Qualquer outra chamada é uma chamada de ferramenta comum, e [Envio automático de chamadas de ferramentas longas para segundo plano](#automatic-backgrounding-of-long-tool-calls) indica quais delas são movidas para segundo plano.
550 550
551Mantenha aberta a entrada de uma sessão do Agent SDK ou stream-json, porque a execução [não aguarda tarefas MCP](https://code.claude.com/docs/pt/headless.md#mcp-work-when-a-non-interactive-run-ends) depois que a entrada é fechada. Uma execução única `claude -p "<prompt>"` não recebe tarefas MCP.551Mantenha a entrada de uma sessão do Agent SDK ou stream-json aberta, porque a execução [não aguarda tarefas MCP](https://code.claude.com/docs/pt/headless.md#mcp-work-when-a-non-interactive-run-ends) depois que a entrada é fechada. Uma execução única `claude -p "<prompt>"` não recebe tarefas MCP.
552 552
553#### Mensagens de status em uma tarefa MCP553#### Mensagens de status em uma tarefa MCP
554 554
555Estas mensagens, na entrada de uma tarefa em `/tasks` ou em sua linha de encerramento na transcrição, significam que o Claude Code não consegue alcançar o servidor ou a tarefa. Enquanto uma delas aparece em `/tasks`, o trabalho ainda pode estar em execução: o Claude Code o deixa em paz e continua verificando. As mensagens de `300s` e de configuração permanecem na entrada mesmo depois que o contato é restabelecido.555Estas mensagens, na entrada `/tasks` de uma tarefa ou em sua linha final na transcrição, significam que o Claude Code não consegue alcançar o servidor ou a tarefa. Enquanto uma delas aparece em `/tasks`, o trabalho ainda pode estar em execução: o Claude Code não interfere nele e continua verificando. A mensagem de `300s` e as de configuração permanecem na entrada mesmo depois que o contato é restabelecido.
556 556
557| Mensagem | O que está acontecendo | O que você pode fazer |557| Mensagem | O que está acontecendo | O que você pode fazer |
558| - | - | - |558| - | - | - |
559| `reconnecting…` | O servidor não respondeu desde uma retomada, ou as verificações de status não recebem resposta | Se persistir, reconecte a partir de `/mcp` |559| `reconnecting…` | O servidor não respondeu desde uma retomada, ou as verificações de status não recebem resposta | Se persistir, reconecte em `/mcp` |
560| `needs a sign-in to <server>` | O servidor recusou uma verificação de status | Faça login a partir de `/mcp` |560| `needs a sign-in to <server>` | O servidor recusou uma verificação de status | Faça login em `/mcp` |
561| `status requests come back with errors; retrying…` | O servidor, ou um proxy na frente dele, responde às verificações de status com erros | Aguarde enquanto o Claude Code tenta novamente |561| `status requests come back with errors; retrying…` | O servidor, ou um proxy na frente dele, responde às verificações de status com erros | Aguarde enquanto o Claude Code tenta novamente |
562| `server '<name>' did not reconnect within 300s` | Nenhuma verificação respondida por cinco minutos, por exemplo com a conexão inativa ou o servidor desativado | Reconecte a partir de `/mcp` |562| `server '<name>' did not reconnect within 300s` | Nenhuma verificação respondida por cinco minutos, por exemplo com a conexão caída ou o servidor desativado | Reconecte em `/mcp` |
563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | Após cinco minutos, o servidor ainda exige um login | Faça login a partir de `/mcp` |563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | Após cinco minutos, o servidor ainda quer um login | Faça login em `/mcp` |
564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | Cinco minutos de respostas de erro | Verifique a integridade ou os logs do próprio servidor |564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | Cinco minutos de respostas com erro | Verifique a integridade ou os logs do próprio servidor |
565| `server '<name>' is not configured in this session; the task may still be running on it` | A sessão não tem nenhum servidor com esse nome, por exemplo porque ele foi removido, renomeado ou deixado de fora de `--mcp-config`, ou um conector do claude.ai ainda está carregando | Restaure o servidor com o mesmo nome e retome a sessão novamente. Para um conector carregando, nada: o Claude Code acompanha a tarefa assim que ele aparecer |565| `server '<name>' is not configured in this session; the task may still be running on it` | A sessão não tem nenhum servidor com esse nome, por exemplo porque ele foi removido, renomeado ou deixado de fora de `--mcp-config`, ou um conector do claude.ai ainda está carregando | Restaure o servidor com o mesmo nome e retome a sessão novamente. Para um conector carregando, nada: o Claude Code acompanha a tarefa assim que ele aparecer |
566| Uma mensagem começando com `server '<name>' was reconfigured to a different transport since this task was created` | Existe um servidor com esse nome com configurações de conexão que mudaram desde o início da tarefa, como sua URL, comando, args, env, headers ou timeout | Restaure as configurações anteriores e retome a sessão novamente |566| Uma mensagem que começa com `server '<name>' was reconfigured to a different transport since this task was created` | Existe um servidor com esse nome cujas configurações de conexão mudaram desde que a tarefa começou, como sua URL, command, args, env, headers ou timeout | Restaure as configurações anteriores e retome a sessão novamente |
567| `the server rejected this task's id; asking again…` | O servidor diz que não conhece o ID da tarefa. O Claude Code continua perguntando por até cinco minutos | Aguarde: a mensagem desaparece se o servidor reconhecer o ID novamente, ou a linha `outcome unknown.` aparece em seguida |567| `the server rejected this task's id; asking again…` | O servidor diz que não conhece o ID da tarefa. O Claude Code continua perguntando por até cinco minutos | Aguarde: a mensagem desaparece se o servidor reconhecer o ID novamente, ou a linha `outcome unknown.` aparece em seguida |
568| Uma linha da transcrição terminando em `outcome unknown.`, em uma forma `expired on the server: outcome unknown.` | O servidor rejeitou o ID ou recusou com outro erro permanente, e o Claude Code parou de acompanhar a tarefa | Uma segunda chamada pode repetir o trabalho. Antes de chamar a ferramenta novamente, descubra com o servidor o que foi feito, por exemplo pedindo ao Claude que use as outras ferramentas do servidor |568| Uma linha da transcrição terminando em `outcome unknown.`, em uma das formas `expired on the server: outcome unknown.` | O servidor rejeitou o ID ou recusou com outro erro permanente, e o Claude Code parou de acompanhar a tarefa | Uma segunda chamada pode repetir o trabalho. Antes de chamar a ferramenta novamente, descubra com o servidor o que foi feito, por exemplo pedindo ao Claude que use as outras ferramentas do servidor |
569 569
570#### Limites de tempo em tarefas MCP570#### Limites de tempo em tarefas MCP
571 571
572Por padrão, uma tarefa em segundo plano não tem limite de tempo do Claude Code. Os [limites de tempo de chamadas de ferramenta](#time-limits-on-mcp-tool-calls), incluindo o limite de tempo de relógio e o timeout de inatividade, se aplicam até que o servidor responda à chamada com a tarefa. Se você [fizer o Claude aguardar](#make-claude-wait-for-the-result-of-an-mcp-task), eles se aplicam à tarefa inteira. Verificações de status respondidas contam como atividade para o timeout de inatividade.572Por padrão, uma tarefa em segundo plano não tem limite de tempo do Claude Code. Os [limites de tempo de chamadas de ferramenta](#time-limits-on-mcp-tool-calls), incluindo o limite de tempo real e o timeout de inatividade, se aplicam até que o servidor responda à chamada com a tarefa. Se você [fizer o Claude aguardar](#make-claude-wait-for-the-result-of-an-mcp-task), eles se aplicam à tarefa inteira. Verificações de status respondidas contam como atividade para o timeout de inatividade.
573 573
574#### Fazer o Claude aguardar o resultado de uma tarefa MCP574#### Fazer o Claude aguardar o resultado de uma tarefa MCP
575 575
576Para fazer o Claude aguardar o resultado de uma tarefa em uma sessão interativa, defina uma de duas variáveis de ambiente, por exemplo no bloco `env` do [`settings.json`](https://code.claude.com/docs/pt/settings):576Para fazer o Claude aguardar o resultado de uma tarefa em uma sessão interativa, defina uma de duas variáveis de ambiente, por exemplo no bloco `env` do [`settings.json`](https://code.claude.com/docs/pt/settings):
577 577
578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/pt/env-vars) definida como `0`**: o Claude aguarda toda chamada de ferramenta MCP até que a chamada termine578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/pt/env-vars) definida como `0`**: o Claude aguarda cada chamada de ferramenta MCP até que a chamada termine
579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/pt/env-vars) definida como `1`**: o Claude aguarda o resultado de uma tarefa. Enquanto a [execução automática em segundo plano](#automatic-backgrounding-of-long-tool-calls) está ativada, ela move a chamada após dois minutos por padrão, então tarefas curtas terminam no lugar e as longas não bloqueiam você. A chamada movida é uma chamada em segundo plano simples, em vez de uma tarefa MCP. Ela não sobrevive ao encerramento da sessão579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/pt/env-vars) definida como `1`**: o Claude aguarda o resultado de uma tarefa. Enquanto o [envio automático para segundo plano](#automatic-backgrounding-of-long-tool-calls) estiver ativado, ele move a chamada após dois minutos por padrão, então tarefas curtas terminam no lugar e as longas não bloqueiam você. A chamada movida é uma chamada em segundo plano comum, e não uma tarefa MCP. Ela não sobrevive ao encerramento da sessão
580 580
581Enquanto o Claude aguarda, pressionar `Esc` ou atingir o [limite de tempo de relógio ou o timeout de inatividade](#time-limits-on-mcp-tasks) encerra a chamada, e o Claude Code pede ao servidor que cancele a tarefa.581Enquanto o Claude aguarda, pressionar `Esc` ou atingir o [limite de tempo real ou o timeout de inatividade](#time-limits-on-mcp-tasks) encerra a chamada, e o Claude Code pede ao servidor que cancele a tarefa.
582 582
583Se você definir `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` como `1` ou iniciar no [modo bare](https://code.claude.com/docs/pt/headless.md#start-faster-with-bare-mode), isso por si só não faz o Claude aguardar tarefas MCP. Este exemplo define `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` como `0`, então o Claude aguarda toda chamada de ferramenta MCP:583Se você definir `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` como `1` ou iniciar no [modo bare](https://code.claude.com/docs/pt/headless.md#start-faster-with-bare-mode), isso por si só não faz o Claude aguardar tarefas MCP. Este exemplo define `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` como `0`, então o Claude aguarda cada chamada de ferramenta MCP:
584 584
585```json settings.json theme={null}585```json settings.json theme={null}
586{586{
592 592
593### Tarefas MCP para autores de servidores593### Tarefas MCP para autores de servidores
594 594
595Se você cria um servidor MCP, pode responder a um `tools/call` de longa duração com uma tarefa. A [extensão de tarefas do MCP](https://modelcontextprotocol.io/extensions/tasks/overview) define as mensagens que você envia. Em uma conexão na [revisão 2026-07-28 do protocolo](#mcp-client-runtimes), cada requisição carrega as capacidades de cliente do Claude Code em `params._meta["io.modelcontextprotocol/clientCapabilities"]`, com `"io.modelcontextprotocol/tasks": {}` em `extensions`. Uma requisição `tools/call` que [não pode se tornar uma tarefa](#requirements-for-mcp-tasks) omite essa extensão.595Se você cria um servidor MCP, pode responder a um `tools/call` de longa duração com uma tarefa. A [extensão de tarefas MCP](https://modelcontextprotocol.io/extensions/tasks/overview) define as mensagens que você envia. Em uma conexão na [revisão de protocolo 2026-07-28](#mcp-client-runtimes), cada requisição carrega as capacidades de cliente do Claude Code em `params._meta["io.modelcontextprotocol/clientCapabilities"]`, com `"io.modelcontextprotocol/tasks": {}` em `extensions`. Uma requisição `tools/call` que [não pode se tornar uma tarefa](#requirements-for-mcp-tasks) omite essa extensão.
596 596
597#### Responder à chamada com uma tarefa597#### Responder à chamada com uma tarefa
598 598
599Responda com uma tarefa somente quando a requisição carregar a extensão; caso contrário, a chamada falha com o erro de ferramenta `Unsupported result type 'task' for tools/call`. A chamada falha da mesma forma se sua resposta não tiver `taskId` ou um `status` válido. O objeto da tarefa é o `result` JSON-RPC da sua resposta `tools/call`, não precisa de um array `content` e aqui inclui os opcionais `statusMessage` e `pollIntervalMs`:599Responda com uma tarefa somente quando a requisição carregar a extensão; caso contrário, a chamada falha com o erro de ferramenta `Unsupported result type 'task' for tools/call`. A chamada falha da mesma forma se sua resposta não tiver `taskId` ou não tiver um `status` válido. O objeto da tarefa é o `result` JSON-RPC da sua resposta a `tools/call`, não precisa de um array `content` e aqui inclui os campos opcionais `statusMessage` e `pollIntervalMs`:
600 600
601```json theme={null}601```json theme={null}
602{602{
613 613
614| Campo | Como o Claude Code o trata |614| Campo | Como o Claude Code o trata |
615| - | - |615| - | - |
616| `resultType` | Defina-o como `"task"` para marcar a resposta como uma tarefa. Sem ele, o Claude Code lê a resposta como um resultado simples |616| `resultType` | Defina-o como `"task"` para marcar a resposta como uma tarefa. Sem ele, o Claude Code lê a resposta como um resultado comum |
617| `taskId` | Obrigatório. No máximo 128 caracteres ASCII imprimíveis sem espaços, caso contrário o Claude recebe um erro de ferramenta começando com `MCP server "<name>" returned a malformed task handle for tool "<tool>"`. Mantenha o ID respondível entre conexões, porque após uma retomada o Claude Code pergunta sobre ele em uma nova conexão |617| `taskId` | Obrigatório. No máximo 128 caracteres ASCII imprimíveis sem espaços; caso contrário, o Claude recebe um erro de ferramenta que começa com `MCP server "<name>" returned a malformed task handle for tool "<tool>"`. Mantenha o ID respondível entre conexões, porque após uma retomada o Claude Code pergunta sobre ele em uma nova conexão |
618| `status` | Obrigatório. Um de `working`, `input_required`, `completed`, `failed` ou `cancelled`. Outro valor resulta no erro `Unsupported result type` |618| `status` | Obrigatório. Um de `working`, `input_required`, `completed`, `failed` ou `cancelled`. Outro valor resulta no erro `Unsupported result type` |
619| `createdAt`, `lastUpdatedAt`, `ttlMs` | Exigidos pela extensão de tarefas, e `ttlMs` pode ser `null`. O Claude Code não descarta uma tarefa porque seu `ttlMs` passou |619| `createdAt`, `lastUpdatedAt`, `ttlMs` | Obrigatórios pela extensão de tarefas, e `ttlMs` pode ser `null`. O Claude Code não descarta uma tarefa porque seu `ttlMs` expirou |
620| `pollIntervalMs` | Opcional. Milissegundos entre requisições `tasks/get`, limitado entre 250 e 30000. O Claude Code usa 2000 quando o campo está ausente ou é `null`, e lê o valor novamente de cada resposta `tasks/get` |620| `pollIntervalMs` | Opcional. Milissegundos entre requisições `tasks/get`, limitado entre 250 e 30000. O Claude Code usa 2000 quando o campo está ausente ou é `null`, e lê o valor novamente em cada resposta de `tasks/get` |
621| `statusMessage` | Opcional. `/tasks` mostra o valor da sua resposta `tasks/get` mais recente, não desta primeira, e uma resposta que omite o campo o limpa. Uma [mensagem de status do Claude Code](#status-messages-on-an-mcp-task) pode ocupar seu lugar |621| `statusMessage` | Opcional. `/tasks` mostra o valor da sua resposta mais recente de `tasks/get`, não desta primeira, e uma resposta que omite o campo o limpa. Uma [mensagem de status do Claude Code](#status-messages-on-an-mcp-task) pode tomar seu lugar |
622 622
623O Claude Code aceita uma resposta de tarefa que omite `createdAt`, `lastUpdatedAt` ou `ttlMs`, ou que define `pollIntervalMs` como `null`. Antes da v2.1.317, a chamada falhava com o erro `Unsupported result type` em vez disso. Para funcionar também com essas versões, envie os três campos exigidos pela extensão de tarefas e envie `pollIntervalMs` como número ou não o envie.623O Claude Code aceita uma resposta de tarefa que omite `createdAt`, `lastUpdatedAt` ou `ttlMs`, ou que define `pollIntervalMs` como `null`. Antes da v2.1.317, a chamada falhava com o erro `Unsupported result type`. Para funcionar também com essas versões, envie os três campos que a extensão de tarefas exige e envie `pollIntervalMs` como um número ou não o envie.
624 624
625Em um servidor HTTP ou de conector do claude.ai, a resposta com a tarefa precisa começar dentro do [temporizador por requisição](#time-limits-on-mcp-tool-calls), então aceite o trabalho e responda primeiro, depois faça o trabalho.625Em um servidor HTTP ou de conector do claude.ai, a resposta de tarefa precisa começar dentro do [temporizador por requisição](#time-limits-on-mcp-tool-calls), então aceite o trabalho e responda primeiro, e depois faça o trabalho.
626 626
627#### Informar status, resultados e perguntas627#### Informar status, resultados e perguntas
628 628
629Logo após a resposta com a tarefa, o Claude Code envia `tasks/get` com `{ "taskId": ... }` e o repete uma vez por intervalo de polling. A extensão de tarefas exige que sua resposta carregue `"resultType": "complete"` junto com `taskId`, `status`, `createdAt`, `lastUpdatedAt` e `ttlMs`. `ttlMs` pode ser `null`, e `statusMessage` e `pollIntervalMs` são opcionais. Este exemplo informa que o build foi concluído:629Logo após a resposta de tarefa, o Claude Code envia `tasks/get` com `{ "taskId": ... }` e depois o repete uma vez por intervalo de polling. A extensão de tarefas exige que sua resposta carregue `"resultType": "complete"` junto com `taskId`, `status`, `createdAt`, `lastUpdatedAt` e `ttlMs`. `ttlMs` pode ser `null`, e `statusMessage` e `pollIntervalMs` são opcionais. Este exemplo informa que o build foi concluído:
630 630
631```json theme={null}631```json theme={null}
632{632{
645| Status, método ou resposta | Como o Claude Code o trata |645| Status, método ou resposta | Como o Claude Code o trata |
646| - | - |646| - | - |
647| `working` | Continua fazendo polling |647| `working` | Continua fazendo polling |
648| `completed` | Entrega ao Claude o resultado normal de `tools/call` no objeto `result` de nível superior. `isError: true` nele é informado como uma falha |648| `completed` | Entrega ao Claude o resultado normal de `tools/call` no objeto `result` de nível superior. `isError: true` nele é informado como falha |
649| `failed` | Informa ao Claude o `message` do objeto `error` de nível superior `{ code, message, data }`, que a extensão de tarefas exige em uma tarefa com falha. Sem esse `message`, o Claude recebe `statusMessage` em vez disso, ou então `Task failed` |649| `failed` | Informa ao Claude a `message` do objeto `error` de nível superior `{ code, message, data }`, que a extensão de tarefas exige em uma tarefa com falha. Sem essa `message`, o Claude recebe `statusMessage`, ou então `Task failed` |
650| `cancelled` | Informa ao Claude `statusMessage`, ou então `Task was cancelled by the server` |650| `cancelled` | Informa ao Claude `statusMessage`, ou então `Task was cancelled by the server` |
651| `input_required` | Lê `inputRequests`, um objeto que mapeia uma chave que você escolhe para `{ method, params }`. O Claude Code responde a cada chave uma vez por meio de `tasks/update` com `{ taskId, inputResponses }`, onde `inputResponses` mapeia a mesma chave para o resultado dessa requisição. Chaves além de 16 por tarefa são ignoradas |651| `input_required` | Lê `inputRequests`, um objeto que mapeia uma chave escolhida por você para `{ method, params }`. O Claude Code responde a cada chave uma vez por meio de `tasks/update` com `{ taskId, inputResponses }`, em que `inputResponses` mapeia a mesma chave para o resultado dessa requisição. Chaves além de 16 por tarefa são ignoradas |
652| Métodos em `inputRequests` | `elicitation/create` é atendido apenas em sessões interativas no terminal, e `roots/list` em todos os lugares. Quando o Claude Code não consegue atender a uma requisição, ele pede ao servidor que cancele a tarefa |652| Métodos em `inputRequests` | `elicitation/create` é atendido apenas em sessões interativas no terminal, e `roots/list` em todos os lugares. Quando o Claude Code não consegue atender a uma requisição, ele pede ao servidor que cancele a tarefa |
653| Outro valor de `status` | O Claude Code pede ao servidor que cancele a tarefa e a informa ao Claude como com falha |653| Outro valor de `status` | O Claude Code pede ao servidor que cancele a tarefa e a informa ao Claude como com falha |
654| Erro JSON-RPC `-32602` | Lido como um ID de tarefa desconhecido. Para uma tarefa em segundo plano, o Claude Code continua perguntando por até cinco minutos e então informa ao Claude o resultado como desconhecido |654| Erro JSON-RPC `-32602` | Interpretado como um ID de tarefa desconhecido. Para uma tarefa em segundo plano, o Claude Code continua perguntando por até cinco minutos e depois informa ao Claude que o resultado é desconhecido |
655| `tasks/cancel` | Enviado, por exemplo, quando o Claude ou a pessoa interrompe a tarefa enquanto o servidor está conectado. Não é enviado ao sair |655| `tasks/cancel` | Enviado, por exemplo, quando o Claude ou a pessoa interrompe a tarefa enquanto o servidor está conectado. Não é enviado ao sair |
656| `tasks/result`, `tasks/list`, `notifications/tasks` | Não usados, então coloque o resultado nas suas respostas `tasks/get` |656| `tasks/result`, `tasks/list`, `notifications/tasks` | Não utilizados, então coloque o resultado nas suas respostas de `tasks/get` |
657 657
658### Servidores MCP fornecidos por plugins658### Servidores MCP fornecidos por plugins
659 659
660[Plugins](https://code.claude.com/docs/pt/plugins/overview.md) podem agrupar servidores MCP que fornecem ferramentas e integrações quando você ativa o plugin.660[Plugins](https://code.claude.com/docs/pt/plugins/overview.md) podem incluir servidores MCP que fornecem ferramentas e integrações quando você habilita o plugin.
661 661
662**Como funcionam os servidores MCP de plugin**:662**Como funcionam os servidores MCP de plugins**:
663 663
664* Plugins definem servidores MCP em `.mcp.json` na raiz do plugin ou inline em `plugin.json`664* Os plugins definem servidores MCP em `.mcp.json` na raiz do plugin ou inline em `plugin.json`
665* Quando você ativa um plugin, Claude Code inicia seus servidores MCP automaticamente665* Quando você habilita um plugin, o Claude Code inicia seus servidores MCP automaticamente
666* Claude Code oferece ferramentas MCP de plugin ao lado de ferramentas MCP configuradas manualmente666* O Claude Code oferece as ferramentas MCP de plugins junto com as ferramentas MCP configuradas manualmente
667* Você adiciona e remove servidores de plugin instalando ou desinstalando o plugin, não com comandos `/mcp`. Você ainda pode [desativar um servidor de plugin instalado](#disable-a-server-without-removing-it) em `/mcp`, o que impede que Claude Code se conecte a ele sem remover o plugin667* Você adiciona e remove servidores de plugins instalando ou desinstalando o plugin, não com comandos `/mcp`. Você ainda pode [desativar um servidor de plugin instalado](#disable-a-server-without-removing-it) em `/mcp`, o que impede o Claude Code de se conectar a ele sem remover o plugin
668 668
669**Exemplo de configuração MCP de plugin**:669**Exemplo de configuração MCP de plugin**:
670 670
698}698}
699```699```
700 700
701**Recursos MCP de plugin**:701**Recursos MCP de plugins**:
702 702
703* **Ciclo de vida automático**: servidores se conectam e desconectam nestes pontos:703* **Ciclo de vida automático**: os servidores se conectam e desconectam nestes momentos:
704 * Na inicialização da sessão, Claude Code conecta os servidores para plugins ativados automaticamente. Em `/mcp`, um servidor de plugin remoto (HTTP ou SSE) que você usou antes pode mostrar o status [`cached`](#server-status-detail) em vez disso; Claude Code o conecta quando Claude chama pela primeira vez uma de suas ferramentas. Quando a conexão de um servidor de plugin stdio falhou menos de 15 minutos antes, Claude Code [pula a conexão](https://code.claude.com/docs/pt/errors.md#skipping-connection-recent-failure-cached)704 * Na inicialização da sessão, o Claude Code conecta automaticamente os servidores dos plugins habilitados. Em `/mcp`, um servidor de plugin remoto (HTTP ou SSE) que você já usou antes pode mostrar o [status `cached`](#server-status-detail) em vez disso; o Claude Code o conecta quando o Claude chama uma de suas ferramentas pela primeira vez. Quando a conexão de um servidor de plugin stdio falhou há menos de 15 minutos, o Claude Code [ignora a conexão](https://code.claude.com/docs/pt/errors.md#skipping-connection-recent-failure-cached)
705 * Se você ativar ou desativar um plugin durante uma sessão, Claude Code conecta ou desconecta seus servidores MCP quando a mudança se aplica. [Apply plugin changes without restarting](https://code.claude.com/docs/pt/plugins/cli-reference.md#reload-plugins) descreve quando isso é. Em uma sessão sem um terminal interativo, `/reload-plugins` não conecta ou desconecta servidores MCP de plugin; essas mudanças entram em vigor em sua próxima sessão705 * Se você habilitar ou desabilitar um plugin durante uma sessão, o Claude Code conecta ou desconecta seus servidores MCP quando a alteração é aplicada. [Aplicar alterações de plugins sem reiniciar](https://code.claude.com/docs/pt/plugins/cli-reference.md#reload-plugins) descreve quando isso acontece. Em uma sessão sem um terminal interativo, `/reload-plugins` não conecta nem desconecta servidores MCP de plugins; essas alterações entram em vigor na sua próxima sessão
706 * Quando você recarrega, Claude Code mantém as conexões ativas de servidores de plugin cuja configuração não mudou, e faz o mesmo quando você [substitui a lista de servidores MCP da sessão](https://code.claude.com/docs/pt/agent-sdk/typescript.md#mcpsetserversresult) do Agent SDK sem nomeá-los706 * Quando você recarrega, o Claude Code mantém as conexões ativas dos servidores de plugins cuja configuração não mudou, e faz o mesmo quando você [substitui a lista de servidores MCP da sessão](https://code.claude.com/docs/pt/agent-sdk/typescript.md#mcpsetserversresult) a partir do Agent SDK sem nomeá-los
707 * Quando você [move a sessão com `/cd`](https://code.claude.com/docs/pt/permissions#move-the-session-to-another-directory) na v2.1.246 ou posterior, Claude Code conecta os servidores de plugins que as configurações do novo diretório ativam e desconecta os servidores de plugins que não estão mais ativados, portanto você não precisa executar `/reload-plugins` após a mudança707 * Quando você [move a sessão com `/cd`](https://code.claude.com/docs/pt/permissions#move-the-session-to-another-directory) na v2.1.246 ou posterior, o Claude Code conecta os servidores dos plugins que as configurações do novo diretório habilitam e desconecta os servidores dos plugins que não estão mais habilitados, então você não precisa executar `/reload-plugins` após a mudança
708 * Em [sessões na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), uma chamada MCP para um servidor de plugin que ainda não está conectado, como logo após uma sessão ociosa acordar, inicia o servidor sob demanda e aguarda sua conexão708 * Em [sessões na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), uma chamada MCP para um servidor de plugin que ainda não está conectado, como logo após uma sessão ociosa ser retomada, inicia o servidor sob demanda e aguarda a conexão
709* **Espaços reservados de caminho**: `${CLAUDE_PLUGIN_ROOT}` resolve para o diretório de instalação do plugin, `${CLAUDE_PLUGIN_DATA}` para seu diretório de [estado persistente](https://code.claude.com/docs/pt/plugins/components.md#path-variables-and-persistent-data), e `${CLAUDE_PROJECT_DIR}` para a raiz do projeto estável. A substituição se aplica a:709* **Placeholders de caminho**: `${CLAUDE_PLUGIN_ROOT}` resolve para o diretório de instalação do plugin, `${CLAUDE_PLUGIN_DATA}` para seu diretório de [estado persistente](https://code.claude.com/docs/pt/plugins/components.md#path-variables-and-persistent-data) e `${CLAUDE_PROJECT_DIR}` para a raiz estável do projeto. A substituição se aplica a:
710 * servidores `stdio`: `command`, `args`, `env`710 * Servidores `stdio`: `command`, `args`, `env`
711 * servidores `http`, `sse`, e `ws`: `url`, `headers`, e `headersHelper`711 * Servidores `http`, `sse` e `ws`: `url`, `headers` e `headersHelper`
712* **Acesso ao ambiente do usuário**: acesso às mesmas variáveis de ambiente que servidores configurados manualmente712* **Acesso ao ambiente do usuário**: acesso às mesmas variáveis de ambiente que os servidores configurados manualmente
713* **Múltiplos tipos de transporte**: suporte para transportes stdio, SSE, HTTP, e WebSocket, embora o suporte de transporte possa variar por servidor713* **Vários tipos de transporte**: suporte para transportes stdio, SSE, HTTP e WebSocket, embora o suporte a transportes possa variar conforme o servidor
714 714
715Os servidores de plugin aparecem em `/mcp` com indicadores mostrando que vêm de plugins.715Os servidores de plugins aparecem em `/mcp` com indicadores mostrando que vêm de plugins.
716 716
717`claude mcp get` oculta os valores configurados para o servidor stdio ou WebSocket de um plugin, porque eles podem carregar credenciais:717`claude mcp get` oculta os valores configurados para o servidor stdio ou WebSocket de um plugin, porque eles podem conter credenciais:
718 718
719* **Servidor stdio**: ele imprime `Command: stdio`, uma linha `Args:` vazia, e cada variável de ambiente como `NAME=[REDACTED]`719* **Servidor stdio**: exibe `Command: stdio`, uma linha `Args:` vazia e cada variável de ambiente como `NAME=[REDACTED]`
720* **Servidor WebSocket**: ele imprime `URL: ws` e cada cabeçalho como `<name>: [REDACTED]`, e `claude mcp list` mostra `ws` no lugar da URL720* **Servidor WebSocket**: exibe `URL: ws` e cada header como `<name>: [REDACTED]`, e `claude mcp list` mostra `ws` no lugar da URL
721 721
722Para ver o que o plugin configurou, [encontre o plugin no disco](https://code.claude.com/docs/pt/plugins/loading.md#find-plugins-on-disk) e leia seu `.mcp.json` ou `plugin.json`.722Para ver o que o plugin configurou, [encontre o plugin no disco](https://code.claude.com/docs/pt/plugins/loading.md#find-plugins-on-disk) e leia seu `.mcp.json` ou `plugin.json`.
723 723
724**Nomes de ferramentas MCP de plugin**:724**Nomes de ferramentas MCP de plugins**:
725 725
726As ferramentas de um servidor MCP agrupado em plugin incluem tanto o nome do plugin quanto a chave do servidor em seu nome chamável. A forma completa é `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`, onde qualquer caractere fora de `A-Z`, `a-z`, `0-9`, `_`, e `-` é substituído por `_`. Para o servidor `database-tools` agrupado em um plugin nomeado `my-plugin`, uma ferramenta `query` é chamável como:726As ferramentas de um servidor MCP incluído em um plugin contêm tanto o nome do plugin quanto a chave do servidor em seu nome chamável. A forma completa é `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`, em que qualquer caractere fora de `A-Z`, `a-z`, `0-9`, `_` e `-` é substituído por `_`. Para o servidor `database-tools` incluído em um plugin chamado `my-plugin`, uma ferramenta `query` pode ser chamada como:
727 727
728```728```
729mcp__plugin_my-plugin_database-tools__query729mcp__plugin_my-plugin_database-tools__query
730```730```
731 731
732Use este nome completo ao fazer referência à ferramenta em [regras de permissão](https://code.claude.com/docs/pt/permissions.md), lista `allowed-tools` de uma skill, campo `tools` de um [subagente](https://code.claude.com/docs/pt/sub-agents.md#available-tools), ou [matcher de hook](https://code.claude.com/docs/pt/hooks.md#match-mcp-tools). Um matcher de hook escrito contra a chave do servidor simples, como `mcp__database-tools__.*`, nunca dispara para um servidor agrupado em plugin.732Use esse nome completo ao referenciar a ferramenta em [regras de permissão](https://code.claude.com/docs/pt/permissions.md), na lista `allowed-tools` de uma skill, no [campo `tools` de um subagente](https://code.claude.com/docs/pt/sub-agents#available-tools) ou em um [matcher de hook](https://code.claude.com/docs/pt/hooks.md#match-mcp-tools). Um matcher de hook escrito com base apenas na chave do servidor, como `mcp__database-tools__.*`, nunca é acionado para um servidor incluído em um plugin.
733 733
734O servidor em si se registra sob o nome com escopo `plugin:<plugin-name>:<server-name>`, como `plugin:my-plugin:database-tools`. Use esse nome onde um nome de servidor configurado é esperado, como um [campo `server` de hook `mcp_tool`](https://code.claude.com/docs/pt/hooks#mcp-tool-hook-fields).734O próprio servidor é registrado com o nome com escopo `plugin:<plugin-name>:<server-name>`, como `plugin:my-plugin:database-tools`. Use esse nome onde se espera o nome de um servidor configurado, como no [campo `server` de um hook `mcp_tool`](https://code.claude.com/docs/pt/hooks#mcp-tool-hook-fields).
735 735
736Veja a [referência de componentes de plugin](https://code.claude.com/docs/pt/plugins/components.md#mcp-servers) para detalhes sobre agrupamento de servidores MCP com plugins.736Consulte a [referência de componentes de plugins](https://code.claude.com/docs/pt/plugins/components.md#mcp-servers) para obter detalhes sobre como incluir servidores MCP em plugins.
737 737
738## Escopos de instalação de MCP738## Escopos de instalação de MCP
739 739
1800* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e posteriores**: a busca de ferramentas está ativada por padrão, o mesmo que na API Anthropic.1800* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e posteriores**: a busca de ferramentas está ativada por padrão, o mesmo que na API Anthropic.
1801* **Modelos anteriores da Agent Platform**: Claude Code carrega todas as ferramentas MCP antecipadamente, porque suas pilhas de serviço rejeitam o cabeçalho beta necessário. `ENABLE_TOOL_SEARCH=true` não sobrescreve isso.1801* **Modelos anteriores da Agent Platform**: Claude Code carrega todas as ferramentas MCP antecipadamente, porque suas pilhas de serviço rejeitam o cabeçalho beta necessário. `ENABLE_TOOL_SEARCH=true` não sobrescreve isso.
1802 1802
1803Antes da v2.1.221, Claude Code desativava a busca de ferramentas para todos os modelos na Agent Platform do Google Cloud, a menos que você definisse `ENABLE_TOOL_SEARCH=true`.
1804
1805Controle o comportamento da busca de ferramentas com a variável de ambiente `ENABLE_TOOL_SEARCH`:1803Controle o comportamento da busca de ferramentas com a variável de ambiente `ENABLE_TOOL_SEARCH`:
1806 1804
1807| Valor | Comportamento |1805| Valor | Comportamento |
