Configure o MCP no Cursor passo a passo. Veja onde ficam os arquivos mcp.json global e de projeto, como escrever entradas de servidores locais e remotos com variáveis seguras, como funcionam as chaves e as aprovações em Settings, como se comportam as instalações pelo Marketplace e como corrigir um servidor que não inicia.
Você cola um trecho em um arquivo de configuração, reinicia o editor, e o novo servidor aparece com um ponto vermelho ao lado do nome. É por causa desse momento que uma configuração de MCP no Cursor bem feita importa. O Model Context Protocol permite que o Agent do Cursor chame ferramentas externas, de um navegador a um banco de dados ou um gerador de imagens, mas só quando a conexão está montada corretamente. Este artigo segue o caminho em ordem. Você verá onde fica o mcp.json, como escrever entradas locais e remotas, quais chaves ficam em Settings, como o Marketplace instala servidores com um clique e o que verificar quando algo falha. Cada configuração abaixo usa nomes de campos da própria documentação do Cursor, e nenhum segredo fica no arquivo.
O MCP é um protocolo aberto que dá a um cliente de IA uma forma padrão de conversar com programas externos. O Cursor é o cliente. Cada programa que você conecta é um servidor, e cada servidor expõe ferramentas que o Agent pode chamar durante um chat: ler um arquivo, consultar um banco de dados, abrir uma página web, registrar um chamado, gerar uma imagem.
Pense em três camadas. O Agent decide o que você pediu. O servidor anuncia o que consegue fazer. Uma ferramenta é uma ação com nome, descrição e um conjunto de entradas. Quando você pede ao Cursor para descobrir por que um endpoint retorna um 500, o Agent lê a lista de ferramentas, escolhe as que servem e pede permissão antes de executá-las.
Duas consequências práticas seguem daí:
github ou project-files, deixam as solicitações de aprovação fáceis de ler depois.💡 Comece com um ou dois servidores que você vai usar todos os dias. Adicione os demais quando uma tarefa real pedir.
Veja como isso aparece no dia a dia. Um servidor de navegador permite que o Agent abra o seu site de homologação, percorra um checkout e informe o que quebrou. Um servidor do GitHub permite que ele leia uma issue, encontre o código correspondente e escreva o rascunho do pull request. Um servidor de banco de dados permite que ele confira uma linha antes de sugerir uma migração. Em todos os casos, o Agent deixa de adivinhar e passa a ler dados reais, que é o motivo inteiro de gastar dez minutos com a configuração.
O Cursor aceita três transportes, e a escolha define como você escreve a entrada em mcp.json.
| Transporte | Onde roda | Quem gerencia | Login |
|---|---|---|---|
| stdio | Na sua máquina | O Cursor inicia e para o processo | Manual, por meio de valores de env ou headers |
| SSE | Local ou remoto | Você ou um provedor implanta | OAuth suportado |
| Streamable HTTP | Local ou remoto | Você ou um provedor implanta | OAuth suportado |
Um servidor stdio é o mais simples: o Cursor executa um comando como npx e conversa com ele pela entrada e saída padrão. Um servidor remoto é apenas uma URL. Você confia que o provedor o mantém em funcionamento e, muitas vezes, entra pelo navegador com OAuth em vez de colar um token.
O Cursor lê as definições de MCP em um arquivo JSON chamado mcp.json. Há dois lugares para ele, e você pode usar os dois ao mesmo tempo.
| Escopo | Caminho | Ideal para |
|---|---|---|
| Global | ~/.cursor/mcp.json | Ferramentas que você quer em todos os workspaces, como GitHub, um servidor de notas ou um gerador de imagens |
| Projeto | .cursor/mcp.json na raiz do repositório | Ferramentas ligadas a uma base de código, como o banco dela ou a API de homologação |
No Windows, a pasta pessoal é o perfil do usuário, então o arquivo global fica em C:\Users\YourName\.cursor\mcp.json.
O Cursor combina os dois arquivos. Dê nomes diferentes aos servidores em cada um para nunca ficar em dúvida sobre qual definição está em uso. Versione o arquivo do projeto somente quando ele não tiver segredos, e use variáveis para tudo que for privado.
Um arquivo de projeto compartilhado tem mais uma vantagem: um novo integrante clona o repositório e recebe a mesma lista de servidores sem precisar de uma reunião de configuração. Cada pessoa então informa os próprios tokens por variáveis de ambiente, de modo que o arquivo fica idêntico para todos enquanto as credenciais continuam pessoais.
Todo arquivo tem um objeto de primeiro nível chamado mcpServers. Dentro dele, cada nome de propriedade é o rótulo de um servidor, e o valor diz como chegar até ele.
| Campo | Usado para | Exemplo |
|---|---|---|
command | O programa que o Cursor executa em um servidor stdio | npx |
args | Argumentos passados a esse programa | ["-y", "@playwright/mcp@latest"] |
env | Valores de ambiente entregues ao processo | {"API_TOKEN": "${env:MY_TOKEN}"} |
envFile | Um arquivo dotenv carregado para o processo | .env |
url | Endereço de um servidor remoto | https://example.com/mcp |
headers | Cabeçalhos HTTP enviados a um servidor remoto | {"Authorization": "Bearer ..."} |
Uma entrada stdio usa command, args, env e envFile. Uma entrada remota usa url e headers. Mantenha os dois formatos separados: uma entrada, um transporte.
Quatro passos resolvem quase todos os casos: criar o arquivo, adicionar uma entrada, salvar e conferir o resultado em Settings. Os dois exemplos abaixo mostram uma entrada local e uma remota.
~/.cursor/mcp.json caso ele ainda não exista.{
"mcpServers": {
"project-files": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
}
}
}
A flag -y permite que npx instale o pacote sem pedir confirmação. A variável ${workspaceFolder} aponta o servidor para o projeto aberto, então ele só alcança arquivos dentro dessa pasta.
Uma entrada remota substitui command e args por uma url. Este exemplo conecta o servidor hospedado do GitHub e lê o token de uma variável de ambiente.
{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ${env:GITHUB_TOKEN}"
}
}
}
}
Servidores que suportam OAuth não precisam de nenhum header. O Cursor abre uma janela do navegador na primeira vez que você os usa, você aprova o acesso, e o login fica salvo para as sessões seguintes. Quando um provedor entrega um client ID e um client secret fixos, o Cursor aceita um objeto auth com CLIENT_ID, CLIENT_SECRET e scopes. Para o aplicativo desktop, registre http://localhost:8787/callback como endereço de redirecionamento.
O Cursor expande estas variáveis dentro de command, args, env, url e headers:
${env:NAME} lê uma variável de ambiente.${userHome} é o seu diretório pessoal.${workspaceFolder} é a raiz do projeto.${workspaceFolderBasename} é o nome da pasta do projeto.${pathSeparator} ou ${/} dá a barra correta para o sistema operacional.Um servidor local que precisa de um endereço de banco de dados e de um caminho de script pode combinar os dois:
{
"mcpServers": {
"notes-db": {
"command": "node",
"args": ["${userHome}${/}tools${/}notes-server${/}index.js"],
"env": { "DB_URL": "${env:NOTES_DB_URL}" },
"envFile": "${workspaceFolder}/.env"
}
}
}
💡 Nunca cole um token real em um arquivo que você versiona. Referencie uma variável de ambiente e adicione
.enva.gitignore.
Abra Cursor Settings e procure por Tools & MCP. Versões recentes também listam os mesmos servidores em Customize, na barra lateral. Este é o painel de controle de tudo o que você escreveu em mcp.json.
Cada servidor tem um interruptor e uma contagem de ferramentas. Um servidor saudável lista as suas ferramentas. Um servidor com problema mostra um estado de erro. Três verificações informam o estado de relance:
Desative os servidores que você não precisa para determinada tarefa, em vez de excluí-los. A entrada continua no arquivo, e religá-la leva um segundo. Também é a forma mais rápida de reduzir a carga de contexto antes de uma refatoração longa.
Por padrão, o Cursor pede aprovação antes de executar uma ferramenta MCP. Você vê o nome da ferramenta e seus argumentos, e então aceita ou recusa. As ferramentas MCP seguem as mesmas regras do Run Mode que os comandos de terminal, então, se o seu modo executa ações da lista de permitidas imediatamente, as ferramentas MCP da lista de permitidas também são executadas imediatamente.
💡 Permita ferramentas somente leitura, como busca, listagem e obtenção de dados. Mantenha a aprovação ativa para tudo que escreve, apaga, publica ou gasta dinheiro.
Escrever o JSON à mão funciona, mas a maioria das pessoas começa pelo marketplace. As listagens ficam em cursor.com/marketplace e no cursor.directory.
Cada listagem tem um botão Add to Cursor. Ao clicar, o Cursor abre, pede que você confirme e grava a entrada no seu ~/.cursor/mcp.json global. Se o servidor precisar de OAuth, o Cursor em seguida leva você à página de login do provedor.
Depois, abra a lista de MCP e confira a contagem de ferramentas. A entrada é um JSON comum, então você pode editá-la depois: renomear, adicionar um valor env ou movê-la para um arquivo de projeto.
Um servidor roda com as suas permissões, então uma instalação com um clique merece dez segundos de desconfiança.
npx baixa código de um registro e o executa na sua máquina.package@version quando a estabilidade importa mais que as atualizações.Se você não tem certeza do que adicionar primeiro, esta lista curta reúne as tarefas diárias mais comuns:
| Tarefa | Tipo de servidor | Por que merece uma vaga |
|---|---|---|
| Testar uma página web em um navegador real | Automação de navegador, como o Playwright | O Agent vê a página renderizada, não apenas o código-fonte |
| Trabalhar com issues e pull requests | Servidor hospedado do GitHub | Issues, branches e revisões ficam em um só chat |
| Ler e editar arquivos fora do repositório | Sistema de arquivos, limitado a uma pasta | O acesso termina onde você traçar o limite |
| Conferir dados antes de uma migração | Um servidor de banco de dados com um usuário somente leitura | Linhas reais, sem risco de uma escrita errada |
A maioria das falhas vem de cinco ou seis causas. Comece pelos logs e depois compare com o sintoma.
Abra o painel Output com Cmd+Shift+U no Mac ou Ctrl+Shift+U no Windows e Linux, e depois escolha MCP Logs no menu suspenso. O log registra a inicialização do servidor, as chamadas de ferramentas e as mensagens de erro. Leia o primeiro erro, não o último. As linhas seguintes costumam ser efeitos colaterais.
| Sintoma | Causa provável | Correção |
|---|---|---|
| Ponto vermelho, "command not found" | npx ou node não está no PATH que o Cursor enxerga | Instale o Node, reinicie o Cursor ou informe o caminho absoluto em command |
| Funciona no terminal, falha no Cursor no Windows | npx é um script, não um executável | Use "command": "cmd" com "args": ["/c", "npx", "-y", "package"] |
| Configuração ignorada | JSON inválido, como uma vírgula sobrando ou um comentário | Valide o arquivo, porque o JSON não aceita nenhum dos dois |
| Inicia e depois dá erro no login | Uma variável está vazia porque o Cursor foi aberto por um menu, e não pelo seu shell | Defina o valor em env ou envFile e reinicie |
| 401 ou 403 de um servidor remoto | Header errado ou um login OAuth expirado | Confira o valor de Authorization e entre novamente |
| Ferramentas ausentes no chat | Servidor desligado, ou o chat começou antes do recarregamento | Ligue o servidor e abra um novo chat no modo Agent |
Quando nenhuma dessas linhas se encaixa, execute o servidor manualmente. Copie o command e os args da sua entrada para um terminal, com os mesmos valores de ambiente, e observe o que ele imprime. Se falhar ali, o problema está no servidor ou na instalação dele, não no Cursor. Se funcionar sem problemas, compare o PATH e as variáveis do terminal com o que o Cursor passa por meio de env, e verifique o log mais uma vez, procurando a primeira linha que cite o servidor pelo nome.
A conexão é só metade do trabalho. Três recursos do PicassoIA ajudam no entorno.
Escrever e revisar configurações. Um modelo de linguagem (LLM) pode identificar uma vírgula sobrando, explicar um erro dos MCP Logs ou transformar um trecho de instalação de um README em uma entrada do Cursor. No PicassoIA você pode usar Claude Sonnet 5, GPT 5.6 Sol, Kimi K2.6 ou Gemini 3.5 Flash em um só lugar e comparar como cada um interpreta o mesmo erro. Substitua todo token por um placeholder antes de colar uma configuração.
Imagens para documentação e READMEs. Páginas de configuração ficam mais fáceis de ler com uma imagem de cabeçalho clara. Seedream 4.5, Flux 2 Pro e GPT Image 2 transformam um prompt de texto em uma imagem fotográfica, e a imagem para vídeo pode transformar uma foto parada em um clipe curto para um changelog ou uma postagem nas redes sociais.
Uma conexão MCP própria. O PicassoIA oferece uma API em https://api.picassoia.com/v1 e conexões MCP gerenciadas pela sua conta, cobrindo geração de imagens, edição de imagens e geração de vídeo com áudio. Até cinco previsões rodam ao mesmo tempo por conta, compartilhadas entre os tokens e as conexões MCP, então uma sessão que dispara muitas requisições vai entrar em fila. O endereço do servidor é mostrado dentro da sua conta, por isso este artigo não o imprime. Com ele em mãos, a entrada segue o mesmo formato url do exemplo github acima. Confira a página do seu plano para ver quais níveis incluem conexões MCP antes de montar um fluxo de trabalho com elas.
Escolha um servidor deste artigo, adicione-o hoje e aprove a primeira chamada de ferramenta você mesmo. Depois abra o PicassoIA e gere uma imagem de cabeçalho para as suas notas de configuração: uma foto da sua mesa, um fundo tranquilo para um diagrama ou um clipe curto para um post de lançamento. Experimente três prompts diferentes, compare os resultados e fique com o que combina com a sua página. A lista completa de modelos está em picassoia.com/en/all-models.
Escolha seu idioma
