WACrew

Blog

Cursor com MCP: como conectar ferramentas ao seu editor

Como configurar servidores MCP no Cursor com o mcp.json, local ou global. Exemplos com npx, servidor remoto, variáveis de ambiente, aprovação de ferramentas e logs.

Por Rodrigo Sumioshi 5 min de leitura
Neste artigo
  1. Duas formas de instalar
  2. Onde fica o mcp.json
  3. Servidor local, iniciado por comando
  4. Servidor remoto, por URL
  5. Variáveis sem expor segredo
  6. Exemplo real: WhatsApp dentro do Cursor
  7. Usando as ferramentas no chat
  8. Quando algo não funciona
  9. Cursor ou Claude Code?
  10. Resumo

O Cursor já vem com um agente que lê o código, edita arquivos e roda comandos. Com MCP, esse agente passa a falar com sistemas fora do editor: o banco de dados, o rastreador de erros, a documentação interna ou o WhatsApp dos clientes. Em vez de colar contexto na conversa toda hora, você conecta a fonte uma vez.

Este guia mostra como configurar servidores MCP no Cursor, com base na documentação oficial.

Duas formas de instalar

Pelo marketplace. Na tela Customize da barra lateral, o Cursor lista plugins oficiais com instalação em um clique. Para servidores da comunidade, o cursor.directory reúne opções com botão "Add to Cursor".

Pelo arquivo mcp.json. Para qualquer servidor que não está no marketplace, ou quando você quer versionar a configuração junto com o projeto. É o caminho que este guia detalha.

Onde fica o mcp.json

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

ArquivoVale para
.cursor/mcp.json na raiz do projetoSó aquele projeto
~/.cursor/mcp.json na sua pasta pessoalTodos os projetos

A regra prática é a mesma do Claude Code. Ferramenta específica de um repositório vai no projeto. Ferramenta que você usa em tudo vai no global. E credencial pessoal nunca entra em arquivo versionado.

Servidor local, iniciado por comando

O formato mais comum é um servidor que o próprio Cursor inicia com npx:

{
  "mcpServers": {
    "nome-do-servidor": {
      "command": "npx",
      "args": ["-y", "nome-do-pacote"],
      "env": {
        "API_KEY": "valor"
      }
    }
  }
}

Esse tipo usa o transporte stdio, em que o Cursor conversa com o processo pela entrada e saída padrão. Funciona igual com Python ("command": "python") ou com qualquer binário.

Servidores stdio aceitam também o campo envFile, que carrega variáveis de um arquivo, por exemplo "${workspaceFolder}/.env".

Servidor remoto, por URL

Para servidores na nuvem, troque o comando pela URL:

{
  "mcpServers": {
    "minha-api": {
      "url": "https://api.exemplo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MEU_TOKEN}"
      }
    }
  }
}

O Cursor suporta os transportes SSE e Streamable HTTP para servidores remotos, além de login por OAuth quando o servidor oferece.

Variáveis sem expor segredo

O mcp.json aceita interpolação nos campos command, args, env, url e headers. As duas mais úteis:

  • ${env:NOME} lê uma variável de ambiente do seu sistema;
  • ${workspaceFolder} aponta para a raiz do projeto.

Assim o arquivo do projeto pode ir para o Git sem carregar chave nenhuma. Cada pessoa define o token no próprio terminal ou perfil.

Exemplo real: WhatsApp dentro do Cursor

O servidor MCP do WACrew conecta o Cursor a um painel de WhatsApp. Com o painel rodando, a configuração fica assim:

{
  "mcpServers": {
    "wacrew": {
      "command": "npx",
      "args": ["-y", "wacrew-mcp"],
      "env": {
        "WAC_CLOUD_URL": "${env:WAC_CLOUD_URL}",
        "WAC_CLOUD_USER": "${env:WAC_CLOUD_USER}",
        "WAC_CLOUD_PASS": "${env:WAC_CLOUD_PASS}"
      }
    }
  }
}

Com isso, dá para pedir ao agente do Cursor coisas como "lê o que o cliente mandou no grupo do projeto e lista os bugs citados" enquanto você está no código desse mesmo projeto. Para responder, o servidor segue o modo de cada conversa. No modo confirmar, que é o padrão, o agente mostra o texto e espera o seu OK antes de enviar.

Usando as ferramentas no chat

Depois de configurado, o Cursor usa as ferramentas MCP listadas em Available Tools quando elas fazem sentido para o pedido. Você também pode citar a ferramenta pelo nome.

Por padrão, o Cursor pede aprovação antes de usar cada ferramenta MCP, e dá para ver os argumentos clicando na seta ao lado do nome. As ferramentas seguem os mesmos modos de execução dos comandos de terminal, então você pode deixar algumas liberadas e manter a aprovação nas que agem para fora, como envio de mensagem.

Para desligar um servidor sem apagar a configuração, abra Customize e use o seletor ao lado dele. Servidores desligados não carregam nem aparecem no chat.

Quando algo não funciona

O Cursor guarda os logs do MCP no painel de saída:

  1. Abra o painel Output (Cmd+Shift+U no Mac).
  2. Escolha MCP Logs na lista.
  3. Procure erro de conexão, de autenticação ou o servidor caindo.

Causas comuns:

  • npx não encontrado. Aplicativos abertos pelo Dock ou pelo menu nem sempre enxergam o mesmo PATH do seu terminal. Use o caminho completo do npx no command (o which npx mostra qual é).
  • Variável vazia. O ${env:NOME} só lê o que existe no ambiente em que o Cursor foi aberto. Abra o Cursor pelo terminal depois de exportar a variável, ou use envFile em servidores stdio.
  • JSON inválido. Uma vírgula sobrando derruba o arquivo inteiro. Valide antes de salvar.
  • Ferramentas demais. Muitos servidores ligados ao mesmo tempo deixam o agente confuso na hora de escolher. Desligue os que não usa naquele projeto.

Cursor ou Claude Code?

Os dois falam MCP, então o mesmo servidor funciona nos dois. A diferença está no jeito de trabalhar. O Cursor é um editor com agente dentro. O Claude Code é um agente de terminal que você usa junto com qualquer editor. Muita gente usa os dois: Cursor para editar com o código à vista e Claude Code para tarefas longas no terminal. A configuração equivalente no terminal está em Claude Code e MCP.

Resumo

No Cursor, servidores MCP entram pelo marketplace ou pelo mcp.json, no projeto (.cursor/mcp.json) ou no global (~/.cursor/mcp.json). Servidores locais usam command e args, remotos usam url. Segredos ficam fora do arquivo com ${env:NOME}, e os logs do MCP no painel Output mostram o que deu errado.

Para entender o que está acontecendo por baixo, o guia o que é MCP explica o protocolo sem jargão.