A causa isolada mais comum de «o meu assistente não vê os meus dados» não é um
servidor quebrado. É um cliente que nunca foi reiniciado depois que a
configuração mudou. A maioria dos clientes MCP lê a configuração na inicialização
e nunca mais; um arquivo que você editou com o aplicativo aberto é um arquivo que
o aplicativo não leu. Encerre-o por completo — no macOS, fechar a janela deixa o
processo rodando — e abra de novo. No Claude Code, rode /mcp em vez de
reiniciar o terminal.
Se isso não resolver, a pergunta útil seguinte não é «qual cliente eu estou usando», e sim «o que exatamente está acontecendo». Um servidor ausente, um servidor que conecta mas não expõe ferramenta alguma, ferramentas que não retornam nada e ferramentas que só falham quando tentam alterar algo são quatro defeitos diferentes com quatro correções diferentes — e a correção quase não depende do aplicativo que você usa. Cada detalhe aqui foi conferido na documentação dos fornecedores em 14 de agosto de 2026.
Antes de mudar qualquer coisa, olhe o que o cliente já sabe. Cada cliente tem exatamente um lugar que responde «este servidor conectou?», e tentar adivinhar pela janela de conversa é como se gasta uma hora com um problema que essa tela nomeia em um segundo.
| Cliente | Onde olhar | Como é um servidor saudável |
|---|---|---|
| Claude Code | claude mcp list ou o painel /mcp |
✔ Connected |
| Claude Desktop | ícone de mais no campo de mensagem → Connectors | servidor listado com as ferramentas dele |
| Cursor | painel Output (Cmd+Shift+U) → MCP Logs |
inicialização, sem erros de conexão |
| VS Code | MCP: List Servers na Command Palette | o servidor sobe e o log de Show Output está limpo |
| Zed | Settings → AI → MCP Servers | ponto verde, dica Server is active |
O Claude Code é o mais informativo de todos. O claude mcp list imprime um
estado de saúde ao lado de cada servidor — ✔ Connected,
! Needs authentication, ✘ Failed to connect, ⏸ Pending approval — e
acrescenta o detalhe da falha na mesma linha; o claude mcp get <name> mostra o
mesmo em uma linha Issue:, inclusive com o texto do erro que o próprio servidor
devolveu.
Se a tela de status não mostra o seu servidor, o cliente não está lendo a entrada que você escreveu. Três causas explicam quase todos os casos.
O arquivo não é um JSON válido. Uma vírgula sobrando ou uma chave faltando e o cliente ignora o arquivo inteiro — não só a entrada quebrada — normalmente sem avisar. Cole o arquivo em qualquer validador de JSON antes de suspeitar de qualquer outra coisa.
Você editou um arquivo diferente daquele que o cliente lê. Quase todo cliente
tem uma configuração pessoal e outra no escopo do projeto, e editar a errada
produz exatamente este sintoma. O Cursor lê ~/.cursor/mcp.json globalmente e
.cursor/mcp.json dentro de um projeto; o VS Code lê .vscode/mcp.json em um
espaço de trabalho e um mcp.json do perfil de usuário, aberto com
MCP: Open User Configuration. O Claude Code tem três escopos — local e user
no ~/.claude.json, project em um .mcp.json na raiz do repositório — e, quando
um nome está definido em mais de um, local vence project, que vence user. A
entrada inteira vem do escopo vencedor; os campos não são mesclados.
O nome da chave está errado para aquele cliente. A chave de primeiro nível do
VS Code é servers, a do Zed é context_servers, e todos os outros usam
mcpServers. Um bloco mcpServers colado no VS Code não é um erro que o editor
reporte: é simplesmente uma chave que ele não lê. Isso está detalhado cliente por
cliente em onde fica a configuração do
MCP.
Um caso parece um servidor ausente, mas não é: no Claude Code, um servidor no
escopo do projeto fica em ⏸ Pending approval até você rodar claude de forma
interativa naquela pasta e aprová-lo, e as aprovações versionadas no repositório
são ignoradas enquanto você não confiar no espaço de trabalho.
Quando nada mudou na configuração e o servidor parou de conectar, a configuração
em geral ainda guarda um caminho absoluto para um programa que não está mais ali.
Atualizar um aplicativo para outra pasta, renomeá-lo ou tirá-lo da pasta
Applications quebram o caminho enquanto o JSON continua parecendo correto, e nada
no erro do cliente aponta para a mudança de lugar. Confira o valor de command
contra a realidade antes de qualquer outra coisa:
ls -l "/absolute/path/from/your/config"
A mesma classe de falha atinge os servidores iniciados por um gerenciador de
versões. Se command for node, npx, python ou uv e o seu runtime vier do
nvm, do pyenv ou do asdf, o caminho existe no seu terminal e não existe para o
cliente, porque o cliente não inicia um shell de login. Troque o nome puro pelo
caminho absoluto — o which node mostra qual é — ou aponte command direto para o
binário.
Um status verde com a lista de ferramentas vazia quer dizer que o aperto de mão
deu certo e que tools/list não devolveu nada de útil. Duas coisas produzem
isso.
A primeira é um servidor que de fato reporta um conjunto vazio de ferramentas, o que você confirma fora do cliente com o MCP Inspector — a interface de teste de referência, que conecta direto a um servidor stdio ou Streamable HTTP e lista o que ele publica. Se o Inspector enxerga ferramentas e o seu cliente não, o defeito está na configuração do cliente.
A segunda é um teto de ferramentas. O VS Code limita cada requisição de chat a 128 ferramentas ativas e recusa a requisição quando o total passa disso — uma máquina cheia chega lá mais rápido do que se imagina; o botão Configure Tools na visão de Chat é onde você desliga servidores para voltar abaixo do limite. O Cursor deixa desativar servidores individuais pelo painel Customize da barra lateral, e um servidor desativado não sobe nem aparece na conversa — vale conferir primeiro, porque um botão que alguém desligou mês passado é idêntico a um servidor que falhou.
As ferramentas estão listadas, o assistente as chama e os resultados vêm vazios. O transporte aqui está bem; a questão é de dados, não de configuração. Confira se a biblioteca que o servidor lê é a que você tem em mente — conta certa, dispositivo certo e conteúdo que realmente sincronizou para esta máquina, em vez de existir só em outra. Depois, confira no log do cliente os argumentos da chamada: um assistente que chutou um intervalo de datas ou um filtro consegue produzir resultado vazio a partir de uma biblioteca perfeitamente saudável.
Se as buscas funcionam mas toda tentativa de renomear, marcar ou atualizar algo falha, isso não é problema de transporte. Os servidores costumam se dividir em ferramentas que leem e ferramentas que alteram dados, e a metade que altera frequentemente carrega uma exigência a mais: um aplicativo em execução, uma sessão autenticada, uma permissão que o cliente não recebeu. Vale descartar antes duas causas do lado do cliente. As ferramentas que alteram dados são declaradas como tal, então o cliente pergunta antes de executá-las — e uma pergunta que você dispensou fica registrada como falha na transcrição. E um servidor iniciado com uma opção de somente leitura simplesmente não publica essas ferramentas, o que é uma escolha de configuração, e não um defeito.
Esta é um defeito do servidor, não seu, e vale reconhecê-la porque a mensagem de
erro confunde. Sobre stdio, o protocolo exige que a saída padrão não carregue
nada além de mensagens JSON-RPC, então um servidor que imprime um banner de
versão, uma linha de «subindo» ou um log colorido em stdout corrompe o fluxo, e o
cliente falha com um erro de parsing que cita os primeiros caracteres do que foi
impresso — Unexpected token 'S', "Starting s"... is not valid JSON. A correção
é do autor do servidor: linhas de log vão para stderr, que o host captura de
qualquer forma.
O ambiente é a outra armadilha de inicialização. Um servidor stdio herda apenas
um subconjunto limitado e dependente da plataforma das variáveis de ambiente —
não o seu perfil de shell — e o diretório de trabalho dele pode ser indefinido,
na prática / no macOS. Passe o que o servidor precisa pela chave env na
entrada de configuração dele, e mantenha todo caminho absoluto.
command existe, como caminho absoluto.Trabalhar de cima para baixo custa um minuto. Começar pelo passo sete é como um problema de cinco segundos vira uma tarde inteira.
O Speak-Y traz o servidor MCP dentro do aplicativo de macOS, então várias das
falhas acima simplesmente não acontecem com ele: não há pacote npm para instalar,
não há runtime para resolver pelo nvm e não há token para expirar. A que pode
acontecer é o caminho velho, e o aplicativo conserta isso sozinho. Na
inicialização ele confere as configurações de Claude Code, Claude Desktop e
Cursor e reescreve o valor de command onde ele aponta para um local antigo do
aplicativo — apenas nas entradas que são de fato dele, reconhecidas pelo binário
do aplicativo e pelo argumento --mcp, de modo que outro servidor que por acaso
tenha o mesmo nome fica intocado. Se precisar ser feito à mão, em
Configurações → Integrações aparece Reinstalar ao lado de cada cliente
detectado; depois disso, reinicie o cliente, ou rode /mcp no Claude Code.
A separação entre ler e alterar é o outro sintoma que vale reconhecer. Buscar nas
gravações e ler transcrições, resumos e itens de ação funciona direto contra a
biblioteca desta máquina e não exige nada mais em execução. As ferramentas que
organizam — tags, títulos, nomes de participantes, retranscrição, publicação em
um canal de equipe — passam pelo aplicativo em execução, então, com o
Speak-Y fechado, elas falham enquanto a busca continua funcionando. Essa
assimetria já é um diagnóstico em si: se ler funciona e alterar não, abra o
aplicativo em vez de editar qualquer configuração. Acrescentar --read-only aos
argumentos do servidor remove as ferramentas que alteram da vista do cliente por
completo — comportamento intencional, não defeito. Resultados vazios vindos de um
servidor saudável normalmente querem dizer que a gravação ainda está em outro
dispositivo: o servidor lê este disco e não vai buscar o resto.
Se você está configurando em vez de consertando, os guias por cliente são mais úteis que esta página: Claude Desktop e Claude Code em detalhe, e VS Code, Zed e Devin Desktop para os editores cuja forma de configuração difere da de todos os outros.
A maioria dos clientes lê a configuração de MCP só na inicialização, então uma configuração escrita com o cliente aberto ainda não foi carregada. Encerre o aplicativo por completo e abra de novo — no macOS, fechar a janela não basta — e, no Claude Code, rode /mcp em vez de reiniciar o terminal.
Cada cliente tem um lugar que responde isso. Claude Code: claude mcp list, que imprime ✔ Connected, ! Needs authentication ou ✘ Failed to connect ao lado de cada servidor. Claude Desktop: o ícone de mais no campo de mensagem e depois Connectors. VS Code: MCP: List Servers pela Command Palette. Cursor: o painel Output com MCP Logs selecionado. Zed: Settings → AI → MCP Servers, onde um ponto verde significa Server is active.
Em ~/Library/Logs/Claude no macOS e em %APPDATA%\Claude\logs no Windows. Para acompanhar ao vivo, use tail -n 20 -F ~/Library/Logs/Claude/mcp*.log. O arquivo mcp.log guarda os eventos gerais de conexão, e mcp-server-NOME.log guarda o que aquele servidor específico escreveu em stderr.
O cliente inicia o processo por conta própria, e não pelo seu shell de login. Ele não herda o seu PATH completo, apenas um subconjunto limitado das variáveis de ambiente que depende da plataforma, e o diretório de trabalho dele pode ser indefinido. Use um caminho absoluto em command, caminhos absolutos nos argumentos, e passe as variáveis necessárias de forma explícita pela chave env.
Quase sempre o caminho absoluto da configuração de MCP, que aponta para onde o aplicativo ficava antes. Reinstalar em outra pasta, renomear o aplicativo ou tirá-lo da pasta Applications quebram o caminho enquanto a configuração continua parecendo correta. Rode de novo a instalação de um clique daquele cliente para que o caminho seja reescrito.