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:
| Arquivo | Vale para |
|---|---|
.cursor/mcp.json na raiz do projeto | Só aquele projeto |
~/.cursor/mcp.json na sua pasta pessoal | Todos 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:
- Abra o painel Output (Cmd+Shift+U no Mac).
- Escolha MCP Logs na lista.
- Procure erro de conexão, de autenticação ou o servidor caindo.
Causas comuns:
npxnão encontrado. Aplicativos abertos pelo Dock ou pelo menu nem sempre enxergam o mesmoPATHdo seu terminal. Use o caminho completo donpxnocommand(owhich npxmostra 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 useenvFileem 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.



