Tutorial completo de MCP no Cursor: como conectar a IA a ferramentas externas

Ao programar com o Cursor, há um problema bastante incômodo. Toda vez que peço à IA uma tarefa relacionada ao projeto, preciso explicar novamente a estrutura, o desenho das tabelas do banco de dados e as interfaces da API. Parece que estou sempre dando uma aula de reforço.

A IA pode ser inteligente, mas não “enxerga” os dados no banco, não sabe quais arquivos existem no sistema e tampouco consegue chamar uma API diretamente. Copiar e colar essas informações manualmente todas as vezes não é nada eficiente.

O MCP (Model Context Protocol) oferece uma solução elegante para isso. Em termos simples, o MCP é um protocolo padrão que permite à IA se conectar a ferramentas externas e fontes de dados. Depois de configurá-lo, a própria IA consegue consultar o banco de dados, ler arquivos e chamar APIs.

O que é MCP?

Uma analogia simples

Se eu tivesse de explicar o MCP da forma mais simples possível, diria: o MCP é como instalar uma porta USB-C na IA.

Pense em como cada dispositivo tinha um conector de carregamento diferente: o iPhone usava Lightning, aparelhos Android usavam Micro-USB e notebooks adotavam outro padrão. Era bastante inconveniente. Depois surgiu o USB-C, resolvendo tudo com uma única interface.

O MCP segue a mesma ideia. É um protocolo aberto desenvolvido pela Anthropic que oferece uma interface padrão para conectar a IA a ferramentas externas. Com esse padrão, cada aplicativo de IA deixa de precisar desenvolver uma integração do zero.

Por que precisamos do MCP?

Antes do MCP, cada aplicativo de IA precisava criar sua própria solução para se conectar a um banco de dados. O Cursor desenvolvia uma, o Claude Desktop desenvolvia outra e as demais ferramentas adotavam abordagens diferentes. Os desenvolvedores repetiam o mesmo trabalho, o custo de manutenção era alto e as ferramentas não eram compatíveis entre si.

O MCP mudou esse cenário ao propor a ideia de “escrever uma vez, usar em qualquer lugar”. Um desenvolvedor só precisa criar um conector de banco de dados de acordo com o padrão MCP para utilizá-lo em qualquer aplicativo de IA compatível. Isso aumenta a eficiência e evita trabalho duplicado.

MCP versus plugins tradicionais

Talvez você esteja se perguntando: qual é a diferença em relação a plugins e extensões tradicionais?

A diferença é significativa. Plugins tradicionais ampliam funções no nível do aplicativo, como um bloqueador de anúncios instalado no navegador ou um tema adicionado ao VSCode. O MCP, por sua vez, amplia as capacidades no nível do modelo de IA.

A diferença mais importante é esta: a IA consegue decidir de forma inteligente quando chamar uma ferramenta, sem que você precise dar uma instrução explícita.

Por exemplo, você pode dizer ao Cursor: “Veja os pedidos deste usuário no banco de dados”. Com o MCP configurado, a IA entende automaticamente que precisa:

1. Conectar-se ao banco de dados
2. Consultar a tabela de usuários para encontrar o ID
3. Consultar a tabela de pedidos para localizar os registros relacionados
4. Organizar os resultados para você

Durante todo o processo, não é necessário dizer “consulte o banco de dados” ou “execute um SQL”. A própria IA sabe o que fazer.

Arquitetura principal

Do ponto de vista técnico, a arquitetura do MCP é bastante clara:

• MCP Host: o aplicativo de IA que você usa, como Cursor ou Claude Desktop
• MCP Client: gerencia a conexão entre o Host e o Server
• MCP Server: encapsula serviços externos, como bancos de dados, APIs e sistemas de arquivos
• Protocolo de comunicação: usa uma interface JSON-RPC padronizada

É como montar blocos: cada parte cumpre sua função. Você só precisa configurar os MCP Servers desejados; a IA cuida do restante.

O que o MCP pode fazer?

Depois de entender o conceito, vejamos o que o MCP consegue fazer na prática. Todos os cenários abaixo foram testados por mim.

Acesso a bancos de dados

Esse recurso realmente me poupou muito tempo.

Imagine um projeto de e-commerce cujo banco contém tabelas de usuários, produtos e pedidos. Antes, para pedir à IA um código que consultasse “os pedidos de determinado usuário no último mês”, você precisava:

1. Copiar a estrutura das tabelas para a IA
2. Explicar os relacionamentos entre elas
3. Especificar os campos da consulta

Agora, depois de configurar um MySQL MCP Server, basta dizer: “Consulte os pedidos do último mês do usuário com ID 123”. A IA automaticamente:

• Conecta-se ao banco de dados
• Analisa a estrutura das tabelas
• Gera o SQL exato
• Executa a consulta
• Organiza os resultados no formato desejado

Além disso, o SQL gerado se baseia na estrutura real das suas tabelas, e não em um exemplo inventado.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Operações no sistema de arquivos

Esse é o recurso que mais uso para organizar código.

Por exemplo, tenho um projeto que usa muitas bibliotecas de terceiros. Com o tempo, vários imports deixaram de ser usados, e conferir um por um manualmente seria cansativo demais.

Depois de configurar um MCP Server para o sistema de arquivos, posso simplesmente dizer ao Cursor: “Analise o projeto inteiro, encontre todos os imports não utilizados e remova-os”. A IA automaticamente:

• Percorre os diretórios do projeto
• Analisa as instruções import de cada arquivo
• Verifica quais imports não são realmente utilizados
• Modifica os arquivos para removê-los

Isso é especialmente útil durante refatorações.

Integração com APIs

O MCP oferece suporte particularmente amplo para integrações com APIs. Já existem MCP Servers para muitos serviços populares.

GitHub MCP

Para quem usa o GitHub com frequência, isso é muito prático. Depois de configurá-lo, você pode pedir diretamente à IA para:

• Ver as Issues de um repositório: “Quais Issues abertas estão marcadas como bug?”
• Criar um Pull Request: “Abra um PR com as alterações deste branch”
• Gerenciar branches: “Crie um novo feature branch”

Slack MCP

Uso essa integração para automatizar notificações da equipe. Por exemplo:

• “Envie uma mensagem no canal #dev avisando que a nova versão entrou no ar”
• “Veja se alguém me mencionou recentemente no canal”

Google Workspace MCP

Essa opção abrange Gmail, Google Docs, Sheets, Drive e Calendar. Se o seu fluxo de trabalho depende do ecossistema Google, configurá-la pode economizar bastante tempo.

Por exemplo: “Organize no Google Sheets os resultados da análise de dados de ontem” ou “Veja minha agenda de amanhã”.

Automação do navegador

O Chrome DevTools MCP é uma ferramenta bastante interessante.

Ele permite que a IA interaja diretamente com o navegador. Você pode pedir à IA para:

• Abrir uma página da web
• Ler a estrutura DOM da página
• Executar JavaScript
• Analisar o desempenho da página

Já usei esse recurso em testes automatizados e análises de desempenho. Por exemplo: “Abra nossa página inicial, analise o tempo de carregamento da primeira tela e identifique quais recursos estão mais lentos”.

Captura de conteúdo da web

O Fetch Server foi feito especificamente para extrair conteúdo de páginas da web.

Ele converte o conteúdo da página em um formato mais adequado para a IA. Se você quiser analisar um artigo, não precisa copiá-lo manualmente. Basta enviar o link e dizer: “Analise os principais argumentos deste artigo”. A IA captura o conteúdo e faz a análise automaticamente.

Como configurar o MCP?

Agora que você já conhece o básico sobre MCP, vamos configurar tudo em detalhes.

Preparação antes da configuração

Antes de começar, confirme dois pontos:

1. Versão do Cursor: certifique-se de usar a versão mais recente. O suporte ao MCP foi adicionado há pouco tempo.
2. Forma de transporte: entenda a diferença entre as duas opções
   • stdio: entrada e saída padrão; o serviço é executado localmente, o Cursor faz o gerenciamento automático e o uso é individual
   • SSE/HTTP: comunicação pela rede; pode ser implantado em um servidor remoto e compartilhado por vários usuários

Na maioria dos casos, recomendo o uso de stdio. A configuração é simples e não exige um servidor adicional.

Opção 1: configurar pela interface do Cursor (recomendado)

Se esta é a primeira vez que você configura o MCP, esta é a opção mais simples.

Passo a passo:

1. Abra o Cursor
2. Use o atalho para abrir as configurações
   • Windows/Linux: Ctrl+Shift+J
   • macOS: Cmd+Shift+J
3. Encontre “Tools & Integrations” no menu à esquerda
4. Clique em “New MCP Servers” na parte inferior
5. O Cursor criará ou abrirá automaticamente o arquivo de configuração mcp.json

A vantagem dessa opção é a interface visual com validação em tempo real. Se houver algum problema na configuração, a mensagem de erro aparecerá diretamente.

Opção 2: editar diretamente o arquivo de configuração

Se você prefere modificar o arquivo de configuração diretamente, pode criá-lo manualmente.

Há dois locais possíveis para o arquivo de configuração do MCP:

• Configuração por projeto: .cursor/mcp.json (válida apenas para o projeto atual)
• Configuração global: ~/.cursor/mcp.json (válida para todos os projetos)

Normalmente, coloco MCP Servers comuns, como GitHub e Fetch, na configuração global e os específicos de cada projeto, como uma conexão de banco de dados, na configuração do projeto.

Estrutura do arquivo de configuração

A estrutura básica do arquivo de configuração do MCP é esta:

{
  "mcpServers": {
    "nome-do-servidor": {
      "command": "comando a executar",
      "args": ["lista de argumentos"],
      "env": {
        "variável de ambiente": "valor"
      }
    }
  }
}

• command: o comando a executar, como npx, node ou python
• args: os argumentos do comando, geralmente o nome do pacote ou o caminho do script do MCP Server
• env: variáveis de ambiente usadas para transmitir API Tokens, senhas de banco de dados e outras informações sensíveis

Caso prático 1: configurar o GitHub MCP

Vamos começar pelo GitHub MCP, que é bastante usado.

Código de configuração:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Explicação da configuração:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

• command: "npx": usa o executor de pacotes do Node.js, sem necessidade de instalação global
• args: ["-y", "@modelcontextprotocol/server-github"]:
  • -y confirma automaticamente
  • @modelcontextprotocol/server-github é o pacote oficial do GitHub MCP Server
• env.GITHUB_PERSONAL_ACCESS_TOKEN: seu token de acesso pessoal do GitHub

Como obter um Token do GitHub:

1. Abra o GitHub e acesse Settings
2. Encontre Developer settings no menu à esquerda
3. Clique em Personal access tokens → Tokens (classic)
4. Clique em Generate new token
5. Selecione as permissões necessárias (pelo menos a permissão repo)
6. Depois de gerar o Token, copie-o e cole-o no arquivo de configuração

Atenção: o Token só será exibido uma vez. Não se esqueça de guardá-lo.

Caso prático 2: configurar o Fetch Server

Este é ainda mais simples, pois não exige API Token.

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

É só isso. Depois de configurá-lo, você pode pedir à IA para capturar o conteúdo de qualquer página da web.

Caso prático 3: configurar um MCP de banco de dados

A configuração de um banco de dados é um pouco mais complexa porque exige informações de conexão.

Aqui usaremos o MySQL como exemplo. Observe que você precisa ter primeiro um MySQL MCP Server, criado por você ou obtido da comunidade:

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/path/to/mysql-mcp-server/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database"
      }
    }
  }
}

Observações importantes:

• Substitua /path/to/mysql-mcp-server/index.js pelo caminho real
• Não grave a senha do banco de dados diretamente no arquivo; você pode usar uma variável de ambiente
• Se o banco de dados estiver em um servidor remoto, altere DB_HOST para o endereço correspondente

Exemplo completo com vários MCP Servers

Na prática, você pode configurar vários MCP Servers. Um arquivo completo poderia ser assim:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    },
    "mysql": {
      "command": "node",
      "args": ["/Users/your-name/mcp-servers/mysql/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database"
      }
    }
  }
}

Verifique se a configuração funcionou

Depois de concluir a configuração, verifique se ela entrou em vigor.

Passos:

1. Reinicie o Cursor: é necessário reiniciá-lo depois de alterar a configuração
2. Teste os recursos MCP: faça alguns testes no chat do Cursor
   • Teste do GitHub: “Mostre a lista dos meus repositórios no GitHub”
   • Teste do Fetch: “Capture o conteúdo principal de https://example.com”
3. Observe a resposta da IA: se a configuração estiver correta, a IA chamará a ferramenta MCP correspondente

Se a IA responder “não tenho permissão para acessar…” ou “não foi possível conectar…”, há algum problema na configuração.

Solução de problemas comuns

Já enfrentei alguns desses problemas. Estas são as soluções que funcionaram para mim:

Problema 1: erro no formato do arquivo de configuração

Sintoma: o Cursor mostra um erro ao iniciar ou os recursos MCP não funcionam.

Solução:

• Confira a sintaxe JSON, principalmente vírgulas, aspas e chaves
• Use uma ferramenta de validação de JSON
• Verifique se não há uma vírgula extra depois do último item

Problema 2: permissões insuficientes no API Token

Sintoma: a IA consegue se conectar ao serviço, mas algumas operações falham.

Solução:

• Confira o escopo das permissões do Token
• O Token do GitHub precisa, no mínimo, da permissão repo
• Se uma operação falhar, talvez seja necessário conceder mais permissões

Problema 3: porta em uso

Sintoma: ocorre um erro ao iniciar o MCP Server.

Solução:

• Verifique se outro programa está usando a porta
• Esse problema normalmente não ocorre com stdio
• Se estiver usando SSE, tente trocar a porta

Problema 4: variável de ambiente não aplicada

Sintoma: você configurou a variável de ambiente, mas o MCP Server não consegue lê-la.

Solução:

• Confira a grafia do nome da variável de ambiente
• Confirme que o arquivo de configuração foi salvo
• No Windows, use barras invertidas duplas ou barras normais nos caminhos

Dicas de uso avançado

Concluir a configuração é apenas o primeiro passo. A seguir estão algumas dicas práticas que reuni.

Escolha o transporte adequado

O transporte stdio é adequado para:

• Desenvolvimento local
• Uso individual
• Configuração rápida, sem servidor adicional

O transporte SSE/HTTP é adequado para:

• Compartilhar o mesmo MCP Server com a equipe
• Usar um banco de dados ou serviço hospedado em um servidor remoto
• Centralizar o gerenciamento e o monitoramento

Costumo usar stdio para ferramentas pessoais, como GitHub e Fetch, e SSE para bancos de dados compartilhados pela equipe.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Gerencie vários MCP Servers

Quando há muitos MCP Servers configurados, o gerenciamento pode ficar confuso. Estas são minhas recomendações:

• Configuração global: mantenha Servers comuns e genéricos, como GitHub, Fetch e Slack
• Configuração por projeto: mantenha Servers específicos, como bancos de dados e APIs internas
• Ativação sob demanda: comente os Servers que não estiverem em uso para evitar desperdício de recursos na inicialização

Recomendações de segurança

A configuração do MCP envolve muitas informações sensíveis, por isso é importante cuidar da segurança:

Não envie Tokens para o Git:

• Adicione .cursor/mcp.json ao .gitignore
• Ou use variáveis de ambiente em vez de valores gravados diretamente

Atualize os Tokens regularmente:

• É possível definir uma data de expiração para o Token do GitHub
• Atualize senhas e Tokens periodicamente

Princípio do menor privilégio:

• Conceda ao Token do GitHub apenas as permissões necessárias
• Dê ao usuário do banco de dados apenas permissão de leitura, caso você só precise fazer consultas

MCP Servers recomendados

Com base na minha experiência, estes são os MCP Servers mais úteis:

Ferramentas de desenvolvimento:

• @modelcontextprotocol/server-github: integração com GitHub
• @modelcontextprotocol/server-gitlab: integração com GitLab

Bancos de dados:

• PostgreSQL MCP Server
• MySQL MCP Server
• MongoDB MCP Server

Produtividade e colaboração:

• Google Workspace MCP Server (Gmail, Docs, Sheets e outros)
• Slack MCP Server

Obtenção de dados:

• @modelcontextprotocol/server-fetch: captura de páginas da web
• Firecrawl MCP Server: recursos mais avançados de crawling

Automação do navegador:

• Chrome DevTools MCP: depuração e automação do navegador

Otimização de desempenho

Ao usar cada vez mais MCP Servers, você talvez perceba problemas de desempenho. Estas são algumas recomendações de otimização:

Ative apenas os Servers necessários:

• Comente ou remova os Servers que não estiverem em uso
• Reduza o consumo de recursos na inicialização

Considere a latência da rede:

• Servers remotos introduzem latência de rede
• Se o banco de dados estiver na nuvem, considere a qualidade da conexão

Defina timeouts adequados:

• Alguns MCP Servers permitem configurar timeouts
• Evite que uma única requisição trave todo o fluxo

Conclusão

Depois de tudo isso, vamos fazer uma revisão rápida.

O que é MCP: um protocolo padrão que permite à IA se conectar a ferramentas e dados externos, como uma porta USB-C para a IA.

O que o MCP pode fazer:

• Acessar bancos de dados, com a IA gerando e executando SQL automaticamente
• Operar o sistema de arquivos e processar arquivos em lote
• Integrar serviços como GitHub, Slack e Google Workspace
• Automatizar o navegador e capturar conteúdo da web

Como configurar:

• Pela interface de configurações do Cursor ou editando diretamente o mcp.json
• O arquivo de configuração contém três partes: command, args e env
• Entre as opções mais usadas estão GitHub, Fetch e MCP Servers de banco de dados

Minha recomendação é começar pelo mais simples. Configure primeiro um Fetch Server para experimentar e sentir o potencial do MCP. Depois que estiver familiarizado, adicione outros Servers conforme suas necessidades reais.

O ecossistema MCP está se desenvolvendo rapidamente, com novos MCP Servers surgindo quase toda semana. A visão de “escrever uma vez, usar em qualquer lugar” está se tornando realidade. No futuro, ao trocar de ferramenta de IA, você não precisará refazer as integrações: poderá usar diretamente os mesmos MCP Servers.