O Cursor tem suporte nativo a MCP, o que significa que configurar um servidor é declarar como ele deve ser iniciado. Este guia mostra onde fica o arquivo, qual é o formato e como verificar se funcionou.
Antes de começar
- O Cursor instalado e funcionando.
- Node.js instalado, se você for usar servidores distribuídos via npx (o caso mais comum).
- Um diretório de projeto para apontar servidores de arquivos — nunca o diretório pessoal inteiro.
Passo 1: escolha o escopo
Existem dois lugares onde declarar servidores MCP, e escolher certo evita confusão depois:
| Arquivo | Escopo | Quando usar |
|---|---|---|
| ~/.cursor/mcp.json | Global — todos os projetos | Ferramentas que você usa sempre, como busca ou notas |
| .cursor/mcp.json | Por projeto | Servidores específicos: banco do projeto, repositório, API interna |
A recomendação é usar o escopo de projeto sempre que possível. Além de manter configuração versionada junto com o código, isso evita que o assistente tenha acesso a recursos irrelevantes ao abrir outra pasta.
Passo 2: escreva a configuração
Crie o arquivo no escopo escolhido e declare os servidores. O formato abaixo é o padrão, e você vai encontrá-lo em praticamente todos os clientes MCP:
{
"mcpServers": {
"arquivos-do-projeto": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/seu-usuario/projetos/meu-projeto"
]
}
}
}Três coisas importantes nesse arquivo:
- `mcpServers` é a chave raiz. Confira a grafia — erro de digitação aqui é causa comum de "não apareceu nada".
- `command` é o executável que inicia o servidor. Usar `npx` permite rodar servidores publicados sem instalação global.
- O último argumento é o **escopo de acesso**. Aqui é onde você define o que o assistente pode ler. Aponte para o diretório do projeto, nunca para `~` ou `/`.
Passo 3: adicione um servidor com credencial
Servidores que acessam serviços externos precisam de credenciais. Elas vão em um bloco `env`, separado dos argumentos:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "seu-token-aqui"
}
}
}
}Alternativa mais segura: mantenha os servidores com credencial no arquivo global (`~/.cursor/mcp.json`), fora do repositório, e deixe apenas servidores sem credencial no arquivo do projeto.
Passo 4: reinicie e verifique
- Salve o arquivo de configuração.
- Reinicie o Cursor — a configuração é lida na inicialização.
- Abra as configurações de MCP e confira se o servidor aparece na lista, com indicador de conectado.
- Se aparecer como erro, expanda a mensagem: geralmente o problema é caminho inexistente ou comando não encontrado.
Passo 5: teste com uma tarefa real
Confirme que o servidor está funcionando pedindo algo que exija usá-lo. Para o servidor de arquivos, algo como: "Liste os arquivos do diretório raiz do projeto e me diga qual é o principal ponto de entrada."
Se o assistente responder com dados reais do seu projeto, a configuração está correta. Se ele disser que não tem acesso, o problema está na configuração — não no modelo.
Problemas comuns
| Sintoma | Causa provável | Solução |
|---|---|---|
| Servidor não aparece na lista | Erro de sintaxe no JSON | Valide o JSON; use um validador |
| Aparece mas não conecta | Caminho inexistente nos args | Confirme que o diretório existe |
| Comando não encontrado | Node.js/npx não instalado | Instale o Node.js e reinicie o Cursor |
| Funciona e depois para | Token expirado ou limite de taxa | Renove a credencial e verifique limites |
| Respostas piores depois de conectar | Excesso de contexto consumido | Reduza o escopo e o número de servidores |
Boas práticas
- Comece com um servidor. Adicione outros apenas quando sentir falta de algo concreto.
- Escopo mínimo sempre: o diretório do projeto, não a pasta pessoal.
- Servidores com credencial ficam fora do repositório.
- Se o assistente ficar mais lento, reduza o número de servidores ativos — cada um consome contexto.
- Versione o `.cursor/mcp.json` do projeto apenas se ele não contiver credenciais.