Solucionando Problemas de Servidores MCP no Cursor

Os servidores MCP estendem o Cursor com ferramentas externas, mas são processos independentes com suas próprias dependências, e quando se comportam mal os sintomas podem ser confusos: um servidor que aparece em vermelho, uma lista de ferramentas que não atualiza ou um botão de desconexão que parece não fazer nada. Este guia oferece uma maneira sistemática de diagnosticar problemas de MCP no Cursor, desde a lista de verificação de triagem rápida até as correções específicas para cada modo de falha comum, e mostra como validar qualquer servidor fora da IDE para que você possa dizer se o problema está no servidor ou na conexão do Cursor com ele.

Lista de Verificação de Triagem Rápida

Quando um servidor MCP se comporta mal, percorra esta tabela de cima para baixo. A maioria dos problemas é resolvida nas três primeiras linhas.

Sintoma	Primeira coisa a verificar	Correção típica
O servidor aparece em vermelho ou não inicia	Execute o comando do servidor manualmente em um terminal	Corrija o caminho do comando, o runtime ausente ou as variáveis de ambiente
Ferramentas ausentes ou obsoletas	Você editou o mcp.json sem reiniciar?	Reinicie o Cursor ou recarregue a janela
O botão de desconexão não faz nada	O processo está realmente morto?	Encerre o processo manualmente e reconecte
O servidor dá erro e nunca tenta de novo	O Cursor não tenta novamente automaticamente após algumas falhas	Desative e ative o servidor, ou reinicie
As requisições travam e depois expiram	A inicialização do servidor ou o runtime das ferramentas está lento demais	Pré-aqueça as dependências, aumente o timeout
Erros de autenticação	Token expirado ou variável de ambiente ausente	Renove o token, corrija o ambiente

O Servidor Não Inicia

A falha de MCP mais comum é a mais simples: o comando que o Cursor usa para iniciar o servidor não funciona de fato. O Cursor executa exatamente o comando do seu mcp.json, com o ambiente que você forneceu, e se isso falhar o servidor nunca aparece.

Caminho de Comando Inválido

Verifique o comando exatamente como o Cursor o executaria. Se o mcp.json diz command": "npx" mas o seu PATH dentro do processo do Cursor não inclui o npx, a inicialização falha. No Windows isso é especialmente comum porque aplicativos com interface gráfica herdam um PATH diferente do seu terminal.

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\projects"]
    }
  }
}

Usar o caminho absoluto para o executável é a correção confiável no Windows. No macOS e no Linux, which npx informa o caminho absoluto se o comando puro não estiver sendo encontrado.

npx ou uvx Ausentes

Muitos servidores MCP são distribuídos como pacotes npm ou Python e são iniciados via npx ou uvx. Se o runtime não estiver instalado, o servidor não consegue iniciar:

# Verify the runtimes exist
node --version    # Node 18+ for npx-based servers
npx --version
python --version
uvx --version     # install with: pip install uv

Se o uvx estiver ausente, instale-o e reinicie seu terminal e o Cursor para que o PATH atualizado seja reconhecido.

Variáveis de Ambiente Erradas

Um servidor que precisa de uma chave de API muitas vezes inicia e depois sai imediatamente, ou inicia e retorna erros em cada chamada de ferramenta, quando seu ambiente está errado. Leia a documentação do servidor para saber os nomes exatos das variáveis e lembre-se de que o Cursor passa apenas o que você lista no bloco env:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    }
  }
}

Ferramentas Não Recarregadas Após Editar o mcp.json

Você edita o mcp.json, salva, abre a lista de ferramentas e as novas ferramentas não estão lá. A configuração do MCP é lida quando o processo do servidor inicia, então as edições não são recarregadas a quente em toda situação.

1. Salve o arquivo e confirme que é um JSON válido. Uma vírgula sobrando torna todo o arquivo não interpretável e todos os servidores podem falhar.
2. Reinicie o Cursor por completo, ou recarregue a janela se sua versão oferecer uma opção de recarregar na paleta de comandos.
3. Abra o painel de configurações de MCP e confirme que o servidor aparece como conectado.
4. Inicie um novo chat. Uma conversa existente pode ter armazenado em cache a lista de ferramentas antiga, então novas ferramentas só aparecem em sessões novas.

Reiniciar é melhor que atualizar

Se desativar e ativar o servidor no painel de MCP não captar suas mudanças, faça um recarregamento completo da janela ou reinicie o Cursor. O mcp.json é lido no momento da conexão, e um processo obsoleto continua servindo sua lista de ferramentas original, não importa o que o arquivo diga agora.

Problemas de Conexão e Nova Tentativa

O Botão de Desconexão Não Faz Nada

A ação de desconectar interrompe o lado cliente da conexão do Cursor, mas com servidores stdio o processo filho real pode sobreviver se não for encerrado corretamente. O resultado é um servidor que ainda parece meio vivo e recusa uma reconexão limpa. Quando o botão parece ser ignorado:

# Find and kill a stubborn stdio MCP server process
# macOS / Linux:
ps aux | grep mcp
kill <PID>

# Windows PowerShell:
Get-Process | Where-Object { $_.ProcessName -like "*npx*" -or $_.ProcessName -like "*uvx*" }
Stop-Process -Id <PID> -Force

Depois que o processo sumir, reconecte pelo painel de MCP. A próxima conexão inicia um processo novo com sua configuração atual.

Sem Novas Tentativas Após um Erro de Servidor

Se um servidor retorna um erro na inicialização ou durante a inicialização, o Cursor geralmente não continua tentando de novo em segundo plano. O servidor permanece em um estado de falha até você intervir. As opções de reinicialização manual, em ordem crescente de força:

1. Desative e ative o servidor no painel de configurações de MCP.
2. Recarregue a janela do Cursor para que todos os servidores MCP se reconectem.
3. Saia completamente e reinicie o Cursor.
4. Se o processo estiver travado, encerre-o como mostrado acima e depois reconecte.

Timeouts em Servidores Lentos

Servidores que baixam dependências na primeira execução, ou ferramentas que chamam APIs externas lentas, podem exceder o timeout padrão e reportar uma falha que parece um servidor quebrado. O caso clássico é um servidor baseado em npx na sua primeira invocação, quando o npm busca o pacote antes que qualquer coisa possa iniciar:

# Pre-warm an npx-based server so the first real connection is fast
npx -y @modelcontextprotocol/server-github --help

Para timeouts no nível do host, muitos hosts de MCP, o Cursor inclusive, respeitam variáveis de ambiente de timeout convencionais. Defini-las antes de iniciar o Cursor dá mais margem a servidores lentos:

# macOS / Linux (add to your shell profile)
export MCP_TIMEOUT=30000        # server startup timeout in ms
export MCP_TOOL_TIMEOUT=120000  # individual tool call timeout in ms

Se um servidor ainda estiver lento demais, hospede-o de outra forma: execute-o como um processo local persistente e conecte-se via SSE ou HTTP em vez de iniciá-lo por sessão.

Tipos de Transporte: stdio vs SSE/HTTP

O Cursor suporta dois estilos de transporte MCP, e várias etapas de solução de problemas diferem entre eles.

Aspecto	stdio	SSE / HTTP
Como roda	O Cursor inicia o processo	O servidor roda separadamente, o Cursor se conecta a uma URL
Chaves de configuração	command, args, env	url (e cabeçalhos onde houver suporte)
Falhas comuns	Caminho de comando inválido, runtime ausente	URL errada, cabeçalhos de autenticação, problemas de CORS ou de rede
Comportamento de reinício	Alternar reconecta o processo	Reconectar acessa o endpoint remoto
Depuração	Execute o comando manualmente	Faça curl no endpoint, verifique os logs do servidor

{
  "mcpServers": {
    "local-stdio-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "remote-http-server": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

Para servidores SSE e HTTP, verifique se o endpoint está acessível antes mesmo de mexer no Cursor:

# A plain GET should return something, even if it is an auth error
curl -i https://mcp.example.com/sse

Um 401 ou 403 significa que o transporte está correto e o problema é a sua autenticação. Um timeout ou conexão recusada significa que o servidor está fora do ar ou a URL está errada.

Variáveis de Ambiente e Segredos

mcp.json de Projeto vs Global

O Cursor lê a configuração de MCP de dois lugares:

• Global: ~/.cursor/mcp.json (no Windows: %USERPROFILE%\.cursor\mcp.json). Aplica-se a todos os projetos. Coloque servidores pessoais aqui: seu token do GitHub, seu navegador de banco de dados, suas ferramentas de scraping.
• Projeto: .cursor/mcp.json dentro do repositório. Aplica-se somente àquele projeto e é compartilhado com colegas quando é commitado. Coloque servidores específicos do projeto aqui: um MCP de schema para o banco de dados deste repositório, uma integração de ferramenta de design usada por esta base de código.

Quando um servidor é definido nos dois lugares, espere que a configuração do projeto governe aquele projeto. Se as ferramentas duplicarem ou desaparecerem, verifique os dois arquivos em busca de uma entrada com o mesmo nome.

Passando Segredos com Segurança

O Cursor expande marcadores ${VAR_NAME} no bloco env a partir do seu ambiente, então os segredos podem ficar fora do mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${MY_DATABASE_URL}"
      }
    }
  }
}

# Set the real value in your shell profile, not in the JSON file
export MY_DATABASE_URL="postgresql://user:password@localhost:5432/appdb"

Não faça commit de segredos no repositório

O .cursor/mcp.json no nível do projeto é um arquivo comum no seu repositório. Se ele contiver uma chave de API literal, toda pessoa e todo agent que clonar o repositório recebe a chave. Use a expansão ${VAR} para qualquer coisa sensível, e adicione o mcp.json do projeto ao .gitignore se ele precisar conter valores locais.

Lendo os Logs do MCP

Quando o sintoma não é claro, os logs normalmente indicam o problema real. O Cursor expõe a atividade do MCP por sua infraestrutura de saída:

1. Abra a paleta de comandos e execute o comando para mostrar o painel de saída, ou use o menu View.
2. Na lista suspensa de canais do painel de saída, selecione o canal de logs do MCP ou do Cursor MCP.
3. Acione a ação que falha e depois leia as entradas mais recentes. Procure erros de spawn, códigos de saída diferentes de zero e stack traces do stderr do servidor.

Linhas de log típicas e o que significam:

[MCP] spawn npx ENOENT                 -> the runtime was not found on PATH
[MCP] server exited with code 1        -> the server crashed; run it manually for the real error
[MCP] initialize timed out             -> slow startup; pre-warm or raise the timeout
[MCP] tool call rejected: invalid args -> the model sent a bad schema; check the tool input

O stderr do lado do servidor é encaminhado para esses logs, então um traceback do Python ou uma exceção de dependência ausente do próprio servidor normalmente aparece aqui literalmente.

Validando um Servidor de Forma Isolada

A maneira mais rápida de provar se um problema é do Cursor ou do servidor é executar o servidor sem o Cursor.

Execute o Comando Manualmente

Copie o command e os args do mcp.json e execute-os em um terminal comum:

# Whatever your mcp.json launches, launch it yourself
npx -y @modelcontextprotocol/server-filesystem /tmp

Um servidor MCP stdio saudável inicia e aguarda em silêncio por entrada JSON-RPC na stdin. Se em vez disso você vir um erro de comando não encontrado, um travamento ou uma falha de instalação de pacote, você encontrou o problema e o Cursor está inocente. Digite alguns caracteres e pressione Enter; uma resposta de erro de protocolo simples na verdade é um bom sinal, porque prova que o processo está falando JSON-RPC.

Use o MCP Inspector

O MCP inspector oficial se conecta a um servidor, lista suas ferramentas e permite que você as chame interativamente:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

Isso abre uma interface web local onde você pode inicializar o servidor, listar ferramentas e invocar uma delas com argumentos escritos à mão. Se uma ferramenta funcionar no inspector mas não no Cursor, a diferença geralmente é o ambiente: variáveis presentes no seu terminal mas ausentes no processo do Cursor, ou um diretório de trabalho diferente. Se a ferramenta falhar no inspector também, corrija o servidor primeiro; nada que você mudar no Cursor vai ajudar.

mcp.json Mínimo Funcional

Use isto como referência quando sua configuração tiver derivado para algo que já não inicia. Ele mostra um servidor stdio e um servidor remoto, com expansão de env:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "remote-search": {
      "url": "https://mcp.example.com/sse",
      "env": {
        "API_TOKEN": "${MY_MCP_TOKEN}"
      }
    }
  }
}

Lista de verificação para adaptá-lo ao seu servidor:

1. Substitua o nome do pacote e os argumentos pelos da documentação do servidor.
2. Use caminhos absolutos para executáveis no Windows se o comando puro não for encontrado.
3. Mantenha segredos como marcadores ${VAR} e defina os valores reais no seu perfil de shell.
4. Valide o JSON, depois reinicie o Cursor e confirme que o servidor aparece como conectado antes de abrir um chat.

Uma entrada ruim pode quebrar o arquivo inteiro

O mcp.json é interpretado como um único documento JSON. Uma única vírgula sobrando ou um valor sem aspas torna todo o arquivo inválido, e todos os servidores nele podem deixar de iniciar juntos, incluindo os que estavam funcionando bem. Se vários servidores quebrarem de uma vez, suspeite da sintaxe do arquivo antes de suspeitar de cada servidor.

Referência Rápida

Objetivo	Faça isto
Servidor em vermelho após a inicialização	Execute o comando manualmente; corrija o caminho, o runtime ou o env
Novas ferramentas não aparecendo	Recarregue a janela e depois inicie um chat novo
Desconexão sem resposta	Encerre o processo filho e depois reconecte
Falhas repetidas, sem nova tentativa	Desative e ative o servidor, ou reinicie o Cursor
Timeout na primeira execução	Pré-aqueça o pacote, aumente as variáveis de ambiente de timeout
Suspeita do servidor, não do Cursor	Valide com uma execução manual ou o MCP inspector
Suspeita do Cursor, não do servidor	Compare seu env com um terminal e leia o canal de logs do MCP