Claude Desktop MCP não funciona? Soluções para config e servidores HTTP

Seu servidor MCP funcionava ontem. Hoje o Claude Desktop não mostra ferramentas, exibe um aviso de "Server disconnected" ou simplesmente nada acontece, e a única pista é um erro vago que não leva a lugar nenhum. Isso acontece com quase todo mundo que configura um servidor local, e a causa quase sempre é uma destas cinco: um claude_desktop_config.json quebrado, um comando que o app não consegue encontrar, um servidor que imprime o texto errado no stdout, um servidor HTTP adicionado do jeito errado ou um app que nunca foi reiniciado por completo.

Este artigo percorre cada falha na ordem em que você deve verificá-las, com o JSON, os caminhos e os comandos exatos para colar. Comece do topo e pare no momento em que suas ferramentas aparecerem. A maioria das correções leva menos de cinco minutos.

💡 Resposta rápida: feche o Claude Desktop pela bandeja ou pela barra de menus (não apenas a janela), rode sua configuração em um validador de JSON, substitua npx pelo caminho absoluto e adicione servidores remotos em Configurações, Conectores em vez do arquivo de configuração. Só isso já resolve a maioria dos casos.

Verifique o básico primeiro

Antes de mexer em uma única linha de JSON, descarte as causas banais. Elas explicam mais configurações com falha do que qualquer bug real.

Feche o Claude Desktop por completo

Fechar a janela não é sair do app. No Windows, o app continua rodando na bandeja do sistema, e no macOS ele permanece ativo até você pressionar Cmd+Q. O Claude Desktop lê a configuração somente na inicialização, então cada edição feita enquanto ele estava aberto é ignorada.

Clique com o botão direito no ícone da bandeja (ou use a barra de menus), escolha Sair, espere dois segundos e abra o app de novo. Faça isso depois de cada mudança, até de um único caractere.

Abra o arquivo de configuração certo

Não procure o arquivo manualmente. Abra Configurações, escolha Desenvolvedor e clique em Editar configuração. Isso abre exatamente o arquivo que o app lê. Os locais habituais são assim:

💡 Se você edita um arquivo e nada nunca muda, talvez esteja editando uma cópia que o app não usa. Algumas instalações empacotadas no Windows redirecionam os dados do app para outra pasta. Editar configuração sempre abre a correta.

Uma configuração mínima que funciona tem esta aparência. Se esta carrega e a sua não, a diferença entre os dois arquivos é o seu bug.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

Copiar prompt

Leia os logs antes de adivinhar

Cada servidor local grava o próprio log, chamado mcp-server-NAME.log, ao lado de um mcp.log geral. Em Configurações, Desenvolvedor, cada servidor também mostra se está em execução ou se falhou, então você vê de relance qual entrada é o problema.

Para acompanhar os logs ao vivo no macOS:

tail -n 40 -F ~/Library/Logs/Claude/mcp*.log

Copiar prompt

E no PowerShell do Windows:

Get-Content "$env:APPDATA\Claude\logs\mcp.log" -Tail 40 -Wait

Copiar prompt

Reinicie o app com a janela de logs aberta e o erro costuma passar rolando nos primeiros segundos. Estas são as linhas que vale reconhecer:

Corrija o JSON de configuração quebrado

O Claude Desktop não perdoa erros de sintaxe. Uma vírgula sobrando e todos os servidores do arquivo desaparecem, não só aquele que você acabou de editar.

Erros de sintaxe que quebram tudo

Confira esta lista linha por linha:

• Vírgulas sobrando depois da última propriedade de um objeto ou array.
• Comentários. O JSON não tem nenhum, então linhas com // copiadas de um tutorial vão quebrar o arquivo.
• Aspas inteligentes. Aplicativos de chat e processadores de texto transformam " em aspas curvas que parecem idênticas e falham imediatamente.
• Uma vírgula faltando entre duas entradas de servidor.
• Um nome de nível superior errado. Ele deve ser exatamente mcpServers, com esse S maiúsculo. Variantes como mcpservers ou servers são ignoradas sem aviso.
• Números em env. Os valores de ambiente devem ser strings, então escreva "PORT": "8080", não "PORT": 8080.
• Seções apagadas. Se o arquivo já tinha outras configurações de nível superior, mantenha-as ao colar um novo bloco mcpServers.

Aqui está um arquivo quebrado típico:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      // path to my server
      "args": ["C:\Users\Ana\notes-server\index.js"],
    }
  }
}

Copiar prompt

E a versão corrigida:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["C:\\Users\\Ana\\notes-server\\index.js"]
    }
  }
}

Copiar prompt

A forma mais rápida de pegar tudo isso de uma vez é deixar um parser fazer o trabalho. O Python já traz um:

python -m json.tool claude_desktop_config.json

Copiar prompt

Se ele imprimir seu arquivo de volta, a sintaxe é válida. Se imprimir um erro com número de linha, vá direto para essa linha.

Caminhos do Windows e barras invertidas

A barra invertida é o caractere de escape do JSON, então C:\Users\Ana é inválido porque \U não é um escape real. Você tem duas opções seguras:

1. Dobre cada barra invertida: C:\\Users\\Ana\\notes-server\\index.js
2. Use barras normais: C:/Users/Ana/notes-server/index.js

O Windows aceita barras normais em quase todos os casos, e elas são muito mais difíceis de errar. Espaços em nomes de pasta são aceitos dentro de uma string JSON, mas teste o caminho em um terminal antes.

Corrija erros de comando e de inicialização

A configuração é válida, o app reiniciou e o servidor ainda falha. Agora o problema está no próprio processo.

Por que acontece spawn npx ENOENT

ENOENT significa "arquivo ou diretório inexistente". O Claude Desktop aberto pelo Dock ou pelo menu Iniciar não lê o perfil do seu shell, então nunca enxerga o PATH que você tem no terminal. Se você instalou o Node pelo nvm, fnm, asdf ou Volta, os binários ficam em uma pasta que só o seu shell conhece. O comando funciona no terminal e falha dentro do app, e é exatamente por isso que parece tão confuso.

Use caminhos absolutos para o Node

Pergunte ao seu terminal onde o binário realmente está:

which npx     # macOS
where npx     # Windows

Copiar prompt

Depois cole o caminho completo em command. Como npx precisa encontrar node, adicione uma entrada PATH em env que inclua a mesma pasta:

{
  "mcpServers": {
    "filesystem": {
      "command": "/Users/you/.nvm/versions/node/v22.11.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"],
      "env": {
        "PATH": "/Users/you/.nvm/versions/node/v22.11.0/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Copiar prompt

Rode também node --version. Muitos servidores iniciados com npx precisam de uma versão LTS recente do Node, e uma instalação antiga do sistema é uma causa oculta clássica.

O wrapper cmd do Windows

No Windows, npx é na verdade um arquivo em lote chamado npx.cmd, e iniciá-lo diretamente pode falhar. Envolva-o em cmd /c para que o shell o resolva corretamente:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:/Users/Ana/Documents"]
    }
  }
}

Copiar prompt

Mantenha o stdout limpo

Isso afeta quem escreve o próprio servidor. Um servidor stdio conversa com o Claude por mensagens JSON-RPC no stdout, e nada mais é permitido ali. Um único console.log("server started") corrompe o fluxo, e o app derruba a conexão com um erro Unexpected token.

💡 Algumas bibliotecas imprimem um banner ou um aviso de descontinuação ao serem importadas. Se o log mostrar um texto que você nunca escreveu, rode o servidor em um terminal e observe o que aparece antes da primeira mensagem do protocolo.

Corrija servidores HTTP e remotos

Servidores HTTP geram mais confusão, porque o arquivo de configuração parece o lugar para adicioná-los. Não é.

O arquivo de configuração roda apenas servidores locais

As entradas em mcpServers iniciam um programa na sua máquina e conversam com ele por stdin e stdout. Elas não acessam um endereço web. Adicionar "url": "https://example.com/mcp" dentro desse bloco é o erro HTTP mais comum, porque o app não tem como usar essa entrada.

Adicione um conector personalizado

Servidores remotos passam pelos Conectores. Conectores personalizados estão disponíveis nos planos Pro, Max, Team e Enterprise, e, nos planos Team ou Enterprise, um proprietário da organização pode precisar adicionar o conector primeiro.

1. Abra Configurações e escolha Conectores.
2. Clique em Adicionar conector personalizado.
3. Cole o endereço HTTPS do endpoint do servidor, que geralmente termina em /mcp.
4. Faça login se o servidor pedir OAuth.
5. Ative o conector pelo menu de ferramentas em um novo chat.

Procure um endpoint Streamable HTTP. Um servidor que fala apenas o transporte SSE, mais antigo, é uma incompatibilidade frequente. Quando o conector falhar, esta tabela ajuda a estreitar o problema:

Um servidor vinculado a localhost é o principal culpado quando um conector personalizado se recusa a conectar, porque esse endereço significa algo diferente do ponto de onde a requisição parte.

Faça a ponte com o mcp-remote

Quando o servidor é privado, local ou precisa de um cabeçalho, o pacote mcp-remote atua como uma ponte stdio. O Claude o inicia como qualquer outro servidor local, e ele encaminha o tráfego para o seu endpoint HTTP:

{
  "mcpServers": {
    "my-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://example.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Copiar prompt

Dois detalhes importam aqui. Primeiro, escreva o cabeçalho sem espaço depois dos dois-pontos e mantenha o valor real em env. No Windows, espaços dentro de args podem ser corrompidos quando npx inicia, e este formato evita o problema. Segundo, o mcp-remote tem opções para forçar o comportamento somente HTTP ou somente SSE, então confira o README dele quando a negociação padrão escolher o transporte errado. Tudo das seções anteriores continua valendo: reinicie por completo, use caminhos absolutos, leia o log.

Teste os servidores fora do Claude

Quando você não consegue saber se a falha está no servidor ou no app, tire o app da equação.

Rode o MCP Inspector

O MCP Inspector oficial se conecta a um servidor e lista suas ferramentas em uma aba do navegador:

npx @modelcontextprotocol/inspector node build/index.js

Copiar prompt

Para um servidor HTTP, abra o Inspector, escolha o tipo de transporte correspondente e cole a URL. O resultado separa o problema com clareza:

• As ferramentas aparecem no Inspector, mas não no Claude: o problema está na sua configuração, no PATH ou na reinicialização.
• O Inspector também falha: o servidor é o problema, então corrija-o primeiro.

Teste o HTTP com curl

Para um servidor Streamable HTTP, envie uma requisição initialize real e leia o código de status:

curl -i -X POST https://example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-test","version":"0.0.1"}}}'

Copiar prompt

Use as ferramentas do PicassoIA dentro do Claude

Quando os conectores funcionam, o benefício está em usá-los. O PicassoIA oferece uma conexão MCP para que o Claude crie imagens e clipes para você dentro de um chat. A conexão expõe quatro modelos:

Os trabalhos de geração são assíncronos. A ferramenta devolve um ID de predição logo de cara, e o Claude então verifica o status até o trabalho dar certo ou falhar. Esse desenho explica a maioria dos relatos de "fica travado":

• Um trabalho ainda aparece como em execução: peça ao Claude para verificar a predição existente pelo ID. Enviar o mesmo prompt de novo só inicia um segundo trabalho.
• Falhas quando muitos trabalhos rodam juntos: uma conta roda até cinco predições ao mesmo tempo, compartilhadas entre todas as conexões, então fique em cinco ou menos.
• Ferramentas ausentes depois de conectar: ative o conector pelo menu de ferramentas e abra um chat novo.
• Não sabe o que o seu plano permite: peça ao Claude para consultar sua conta, ou confira a página de conexões MCP na sua conta do PicassoIA.

Use o Claude Sonnet 5 no PicassoIA

Travado em uma configuração que parece certa e ainda falha? Peça uma segunda opinião. O Claude Sonnet 5 roda no PicassoIA e foi feito para depurar código, e consegue ler capturas de tela de faixas de erro.

1. Abra a página do modelo. Acesse o Claude Sonnet 5 no PicassoIA.
2. Preencha o prompt. Cole sua configuração, as últimas 30 linhas do log, seu sistema operacional, sua versão do Node e o que você esperava que acontecesse. Remova todos os tokens antes.
3. Anexe uma captura de tela. O campo image aceita uma imagem do erro. Aumente max_image_resolution acima do padrão de 0,5 megapixel se o texto ficar borrado após o redimensionamento.
4. Defina o esforço. O padrão low é o mais rápido. Mude para high quando vários servidores interagirem ou a causa não estiver clara.
5. Adicione um prompt de sistema. Algo como: "Você é um assistente de solução de problemas de MCP. Devolva primeiro o JSON corrigido e depois uma lista curta de causas."
6. Gere e compare. Compare a resposta com o seu arquivo, aplique uma mudança por vez e reinicie o app por completo depois de cada uma.

💡 Nunca cole tokens ativos em nenhuma janela de chat. Substitua-os por YOUR_TOKEN e coloque o valor real de volta apenas no seu arquivo local.

Para problemas teimosos com vários arquivos, Claude Fable 5 e Claude Opus 4.7 também estão disponíveis na mesma categoria.

Crie sua primeira imagem hoje

Seus servidores estão rodando, as ferramentas estão visíveis, e a parte difícil já ficou para trás. Agora dedique dez minutos à parte divertida. Abra o PicassoIA Image e escreva um prompt para uma cena que você realmente penduraria em uma parede. Refine com o PicassoIA Image Editor Pro e depois dê vida ao resultado com o PicassoIA Video.

Teste o mesmo prompt em três estilos, mude o ângulo da câmera, troque a iluminação do amanhecer para o entardecer e compare. A forma mais rápida de ficar bom nisso é fazer muitos experimentos pequenos e guardar os que surpreendem. Quando quiser mais opções, navegue por todos os modelos em picassoia.com/en/all-models e veja o que se encaixa no seu próximo projeto no Picasso IA.