# 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, 14 de novembro de 2026. Original: https://wacrew.com.br/blog/cursor-mcp/

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](https://cursor.com/docs/mcp).

## 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](https://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`:

```json
{
  "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:

```json
{
  "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](https://wacrew.com.br/servidor-mcp-whatsapp/) conecta o Cursor a um painel de WhatsApp. Com o painel rodando, a configuração fica assim:

```json
{
  "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](https://wacrew.com.br/blog/claude-code-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](https://wacrew.com.br/blog/o-que-e-mcp/) explica o protocolo sem jargão.
