Olá, a Lena está chegando. Eu não estava tentando configurar nada complicado naquela tarde.

Eu só queria que Cursor acessasse um banco de dados e extraísse o contexto sem que eu tivesse que copiar coisas manualmente. Simples o suficiente, em teoria. Mas da primeira vez que olhei para os servidores MCP no Cursor, pausei por mais tempo do que esperava. O painel de configurações parecia um pouco diferente do que eu tinha visto documentado duas versões anteriores. O caminho de configuração havia mudado. A interface tinha um novo rótulo. Não estava quebrado — apenas… o mesmo que eu lembrava.

Na verdade, é disso que este artigo trata. Não apenas "aqui está o JSON." Mais como — aqui está o que notei quando passei pelo processo cuidadosamente, incluindo as partes que me confundiram no início.

O Que os Servidores MCP Fazem no Cursor

Como a chamada de ferramentas funciona dentro do IDE do Cursor

MCP — Model Context Protocol — é um protocolo aberto que padroniza como aplicativos fornecem ferramentas e contexto para LLMs. A Anthropic tornou-o open-source em novembro de 2024. Em meados de 2025, OpenAI e Google DeepMind também o adotaram. Em dezembro de 2025, passou a fazer parte da Agentic AI Foundation — um projeto da Linux Foundation. Essa mudança importa um pouco. Ele deixou de ser algo da Anthropic para se tornar algo mais genuinamente compartilhado.

Dentro do Cursor, o MCP funciona como uma camada de plugin para o Agente. Quando você abre uma sessão de agente, o Cursor escaneia seus servidores MCP habilitados, carrega as ferramentas que eles expõem e determina quais chamar como parte da tarefa que está executando.

O protocolo define três peças: hosts (o próprio Cursor), clientes (os conectores dentro do Cursor) e servidores (programas leves do outro lado, expondo ferramentas via JSON-RPC 2.0).

As ferramentas são as principais — funções executáveis como create_issue ou run_query. O Cursor suporta ferramentas desde cedo. Recursos — dados contextuais como conteúdo de arquivos e esquemas de banco de dados — chegaram ao Cursor na versão 1.6 (setembro de 2025). Prompts, que permitem aos servidores oferecer modelos reutilizáveis, chegaram um pouco depois.

Hmm… eu não percebi que os recursos eram tão recentes. Isso pode explicar por que alguns tutoriais antigos parecem incompletos.

Antes de Começar: Pré-requisitos

Versão do Cursor que suporta MCP

O suporte MCP faz parte do Cursor há algum tempo, mas o formato de configuração mudou entre as versões. Antes de fazer qualquer outra coisa, verifique sua versão. Abra Cursor → Ajuda → Sobre. A versão estável atual, no início de 2026, suporta todos os três tipos de transporte: stdio, SSE e HTTP Streamable.

Uma coisa que vale a pena confirmar: o painel de Configurações agora rotula esta seção como Ferramentas & MCP, e não apenas 'Extensões' ou algo mais genérico. Se você está procurando por ela e não consegue encontrar — provavelmente é por isso.

Requisitos do Node.js ou Python dependendo do servidor

A maioria dos servidores MCP que você encontrará roda em uma de duas stacks:

Servidores baseados em Node.js — iniciados via npx ou node. Requerem Node.js 18+ no seu PATH.
Servidores baseados em Python — iniciados via uv run ou python. Requerem Python 3.10+ e, frequentemente, uv como gerenciador de pacotes.

Eu sugeriria rodar node --version e python --version no seu terminal antes de qualquer outra coisa. Parece óbvio, mas pular este passo é silenciosamente responsável por um número surpreendente de configurações que falham. O processo do servidor simplesmente… nunca inicia, e o Cursor não oferece nada útil no painel.

Como Adicionar um Servidor MCP ao Cursor

Passo 1: Encontrar ou construir seu servidor MCP

Já existe um número considerável de servidores disponíveis — para GitHub, Postgres, Slack, automação de navegador e mais. O registro oficial de servidores MCP no GitHub é um ponto de partida razoável. Alguns têm botões de 'Adicionar ao Cursor' com um clique na documentação, que lidam com a configuração automaticamente.

Se você está construindo o seu próprio: os servidores só precisam imprimir para stdout (transporte stdio) ou servir um endpoint HTTP. Qualquer linguagem funciona, o que é uma das coisas que faz isso parecer um pouco diferente de sistemas de plugins anteriores que usei.

Passo 2: Configurar nas configurações do Cursor

É aqui que quero ser preciso, porque o formato importa e a documentação nem sempre avisa quando está errado.

Existem dois locais de configuração:

Escopo do projeto: .cursor/mcp.json na raiz do seu projeto
Global: ~/.cursor/mcp.json no seu diretório home

A estrutura se parece com isso:

JSON

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "your-mcp-server-package"],
      "env": {
        "API_KEY": "your-value-here"
      }
    }
  }
}

O campo env é como você passa chaves de API e configurações sensíveis — elas não vão em args. Isso levou-me um momento para entender intuitivamente.

Uma coisa que chama atenção das pessoas: se você perder a chave raiz "mcpServers", o Cursor ignora silenciosamente todo o arquivo. Sem erro, sem aviso. O servidor simplesmente não aparece. Não tenho certeza de por que funciona assim, mas funciona.

Para servidores Python usando uv:

JSON

{
  "mcpServers": {
    "my-python-server": {
      "command": "uv",
      "args": ["run", "--with", "my-server-package", "my-server-package", "run"]
    }
  }
}

Alternativamente, você pode adicionar servidores através da interface: Configurações → Ferramentas & MCP → Novo Servidor MCP. Esse caminho é um pouco mais tolerante se você não se sente à vontade editando JSON diretamente.

Passo 3: Verificar a conexão

Após salvar a configuração, abra Configurações → Ferramentas & MCP. Cada servidor deve aparecer com um indicador de status — verde significa conectado, outro mostrará que não está.

Se um servidor não estiver aparecendo: verifique a chave raiz primeiro ("mcpServers", não "servers" ou qualquer outra). Depois, confira se o comando está realmente disponível no seu PATH. O Cursor nem sempre mostra erros úteis aqui — essa é uma das partes que ainda parece um pouco não resolvida para mim.

Passo 4: Testar chamadas de ferramenta em uma sessão de agente

Abra uma nova sessão de Agente no Cursor (não um chat normal). Digite algo que naturalmente invocaria uma das ferramentas do servidor. O Cursor deve pedir sua confirmação antes de executar — isso é comportamento esperado, não um problema.

Se a chamada da ferramenta for executada mas não retornar nada útil, verifique se o servidor está realmente exportando a ferramenta que você pensa. O painel Ferramentas & MCP mostra quais ferramentas cada servidor expõe. Essa lista vale a pena revisar antes de assumir que algo está quebrado.

Solução de Problemas Comuns na Configuração do MCP

Servidor não aparecendo

Normalmente uma de três coisas: chave raiz "mcpServers" faltando, um comando que não pode ser encontrado no PATH, ou um erro de sintaxe no JSON. O Cursor é silencioso sobre todas estas. Validar seu JSON manualmente — mesmo colando em um verificador (linter) — economiza tempo.

Chamadas de ferramenta falhando silenciosamente

O Cursor tem um limite de cerca de 40 ferramentas ativas entre todos os servidores. Passado isso, o agente começa a ter dificuldade para escolher a ferramenta certa porque o contexto se enche. Se você tiver muitos servidores habilitados, tente desligar os que não está usando e clique no botão de atualizar no painel Ferramentas & MCP. Isso me ajudou mais de uma vez.

Erros de autenticação

Se o seu servidor requer uma chave de API e a chamada da ferramenta falha com um erro de permissões, verifique novamente se a chave está no campo env da sua configuração, e não codificada no args. Alguns pacotes de servidor também esperam nomes específicos de variáveis de ambiente — vale a pena conferir a documentação do próprio servidor para o nome exato da variável esperado.

Tornando sua Configuração MCP do Cursor Reutilizável

Por que sua configuração é reiniciada e como mantê-la

Se você estiver usando apenas .cursor/mcp.json dentro de um único projeto, a configuração desaparece quando você trabalha em uma pasta diferente. Isso me surpreendeu na primeira vez. A solução é também manter um ~/.cursor/mcp.json em nível global para servidores que você quer em todos os lugares — coisas como um servidor de sistema de arquivos ou uma ferramenta de consulta de documentação.

Para configurações de equipe, commitar .cursor/mcp.json no controle de versão significa que todos no projeto terão a mesma configuração de servidor. Os valores env obviamente não devem ser commitados — eles pertencem à configuração do ambiente local ou a um gerenciador de segredos.

Mais uma coisa importante para lembrar: servidores MCP executam código com suas credenciais. Quaisquer permissões que você conceder a um servidor — acesso a banco de dados, tokens do GitHub, chaves de API — ele irá usá-las. Antes de adicionar qualquer servidor de terceiros, vale a pena conferir as diretrizes de segurança do MCP na documentação oficial. As divulgações CVE de 2025 sobre o Cursor MCP foram corrigidas, mas o princípio subjacente permanece: trate cada servidor como uma integração totalmente confiável.

FAQ

Como adiciono um servidor MCP ao Cursor?

Crie ou edite .cursor/mcp.json no diretório do seu projeto (ou ~/.cursor/mcp.json para acesso global), usando a chave raiz "mcpServers". Adicione o comando do servidor, argumentos e quaisquer variáveis de ambiente. Em seguida, verifique Configurações → Ferramentas & MCP para confirmar se a conexão foi feita.

Qual versão do Cursor suporta MCP?

O suporte à ferramenta MCP está disponível no Cursor há algum tempo. O suporte a recursos (dados contextuais como esquemas e conteúdos de arquivos) chegou na v1.6 (setembro de 2025). Verifique Ajuda → Sobre para confirmar sua versão e mantenha o Cursor atualizado — a integração MCP mudou significativamente entre as versões.

Por que meu servidor MCP não está aparecendo no Cursor?

A causa mais comum é uma chave raiz "mcpServers" ausente ou escrita incorretamente no seu arquivo de configuração. O Cursor ignora silenciosamente o arquivo se essa chave estiver ausente. Outras causas incluem o comando não ser encontrado no PATH, ou um erro de sintaxe JSON. Valide seu arquivo de configuração e verifique se o runtime (Node.js ou Python) está acessível a partir do terminal.

Provavelmente vou continuar observando como isso evolui. O ecossistema MCP ainda está se formando — servidores estão sendo adicionados, o protocolo está ganhando adoção em mais ferramentas — e como a configuração será em uma ou duas versões futuras, ainda realmente não sei.

...mas não parece ser aleatório.

Leitura relacionada: Documentação Oficial MCP · Documentos Cursor MCP · Registro do Servidor MCP no GitHub