Tutorial prático de MCP: guia completo para consultar bancos de dados e chamar APIs diretamente no Cursor

Na tarde da última quarta-feira, eu estava desenvolvendo um recurso de análise de dados e precisava descobrir quantos usuários novos haviam entrado em dezembro. Pelo meu fluxo antigo, eu teria de abrir o DataGrip, escrever uma consulta SQL, executá-la, copiar o resultado e voltar ao código. Para uma consulta tão simples, alternei de janela três vezes e perdi dois minutos.

Então pensei: uso o Cursor todos os dias para programar, e a IA já me ajuda a escrever funções e corrigir bugs. Por que ela não poderia consultar o banco de dados diretamente?

Depois de configurar o MCP, basta perguntar no Cursor: “Quantos usuários novos entraram em dezembro?”. A IA retorna o resultado em segundos. Não preciso trocar de janela nem escrever SQL, e o ganho de eficiência é enorme.

Quando ouvi falar de MCP pela primeira vez, também demorei para entender. Server, Client, Protocol — tudo parecia muito sofisticado. Os tutoriais disponíveis eram teóricos demais, cheios de diagramas de arquitetura, ou simples demais, parando no Hello World. Levei dois dias de tentativa e erro até compreender a configuração.

Por isso, este artigo mostra da forma mais direta possível como configurar o MCP para que a IA consulte bancos de dados e chame APIs. Em 15 minutos, você terá uma configuração funcional.

O que é MCP e por que você precisa dele

MCP em linguagem simples

MCP significa Model Context Protocol, ou Protocolo de Contexto de Modelo. Parece acadêmico, mas, em termos simples, é como dar um “cinto de ferramentas” à IA.

Antes, a IA funcionava como uma consultora muito inteligente: você fazia uma pergunta, ela sugeria uma solução ou escrevia o código, mas não conseguia executar nada por conta própria. Era preciso copiar a sugestão e fazer o trabalho manualmente.

Com MCP, a IA vira uma assistente de verdade. Além de aconselhar, ela pode consultar bancos de dados, chamar APIs e ler arquivos diretamente.

Fluxo tradicional versus fluxo com MCP

Imagine que você queira descobrir qual produto teve o maior faturamento no mês passado.

Fluxo tradicional (sem MCP):

1. Você pede à IA uma consulta SQL.
2. A IA fornece o código SQL.
3. Você copia o SQL e abre o cliente de banco de dados.
4. Cola o SQL e executa a consulta.
5. Copia o resultado.
6. Volta ao Cursor e envia o resultado à IA.
7. A IA continua a análise com base nesses dados.

Esse processo exige alternar repetidamente entre três janelas.

Fluxo com MCP:

1. Você pergunta diretamente: “Qual produto teve o maior faturamento no mês passado?”.
2. A IA consulta o banco e responde.

Tudo acontece em uma etapa, com uma diferença de eficiência de pelo menos cinco vezes.

Conceitos essenciais em três minutos

A arquitetura do MCP é simples e tem três participantes.

MCP Client — o cérebro de IA que usa ferramentas

É a ferramenta de IA que você usa, como Cursor ou Claude Desktop. Ela interpreta o pedido e decide se precisa recorrer a uma ferramenta.

MCP Server — o serviço que fornece ferramentas

É o serviço configurado para oferecer uma capacidade específica à IA. Um MCP Server de banco de dados permite fazer consultas; um MCP Server de API permite chamar endpoints.

Tools — as capacidades específicas

São as funções expostas por cada MCP Server. Um servidor de banco de dados pode oferecer ferramentas para consultar o esquema, executar um SELECT ou contar linhas.

Pense assim: a IA é uma profissional, o MCP Server é a caixa de ferramentas e as Tools são a chave inglesa e o martelo. Quando você pede para pregar algo, a IA sabe qual ferramenta pegar.

Depois de entender esses três conceitos, fica fácil acompanhar o restante da configuração.

Caso prático 1 — integração com SQLite

Por que começar pelo SQLite

A principal vantagem do SQLite é a simplicidade: não é preciso instalar um serviço de banco de dados nem configurar portas. Um arquivo já é o banco inteiro, o que o torna ideal para aprender.

Depois que você dominar o processo, poderá aplicar a mesma lógica ao PostgreSQL ou MySQL.

Preparação: criar um banco de dados de teste

Primeiro, crie alguns dados para testar as consultas. Gere um arquivo chamado test.db:

-- Criar a tabela de usuários
CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

-- Criar a tabela de pedidos
CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    user_id INTEGER,
    product_name TEXT,
    amount REAL,
    order_date TEXT DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

-- Inserir usuários de teste
INSERT INTO users (name, email) VALUES
    ('João', '[email protected]'),
    ('Maria', '[email protected]'),
    ('Carlos', '[email protected]');

-- Inserir pedidos de teste
INSERT INTO orders (user_id, product_name, amount) VALUES
    (1, 'MacBook Pro', 12999.00),
    (1, 'AirPods', 1299.00),
    (2, 'iPhone 15', 5999.00),
    (3, 'iPad Air', 4799.00),
    (3, 'Apple Watch', 2999.00);

Você pode executar esse SQL em qualquer ferramenta para SQLite, como DB Browser ou a linha de comando, ou usar Python:

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

Ver preços →Anúncio

import sqlite3

conn = sqlite3.connect('test.db')
cursor = conn.cursor()

# Execute as instruções SQL acima
# ...

conn.commit()
conn.close()

Configurar o MCP Server

Esta é a parte central do tutorial. O arquivo de configuração do MCP pode ficar em dois lugares, dependendo da sua necessidade.

Configuração global (disponível para todos os projetos):

• Windows: C:\Users\seu-nome-de-usuario\.cursor\mcp.json
• Mac/Linux: ~/.cursor/mcp.json

Configuração do projeto (ativa somente no projeto atual):

• .cursor/mcp.json na raiz do projeto

Recomendo começar pela configuração do projeto. Depois de confirmar que tudo funciona, você pode movê-la para a configuração global.

Crie o arquivo .cursor/mcp.json com este conteúdo:

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "--db-path",
        "D:/path/to/your/test.db"
      ]
    }
  }
}

Pontos importantes que costumam causar dúvidas:

1. mcpServers: é um nome de campo fixo; não o altere.
2. "sqlite": é o nome que você escolhe para o Server e que ficará visível para a IA.
3. command: "npx": executa o MCP Server diretamente com npx, sem instalação manual.
4. args: são os argumentos passados ao comando.
   • -y: confirma automaticamente a instalação.
   • @modelcontextprotocol/server-sqlite: é o pacote oficial do MCP Server para SQLite.
   • --db-path: aponta para o arquivo do banco e precisa ser um caminho absoluto.

Atenção no Windows: use barras / ou barras invertidas duplas \\, nunca barras invertidas simples:

• ✅ D:/projects/test.db
• ✅ D:\\projects\\test.db
• ❌ D:\projects\test.db — esse formato causa erro

Reiniciar o Cursor e validar a configuração

Depois de salvar o arquivo, você precisa reiniciar o Cursor por completo. Fechar apenas a janela não basta; encerre o aplicativo.

Após reiniciar, confira nas configurações do Cursor se o MCP foi carregado:

1. Abra as configurações com Ctrl+,.
2. Pesquise por MCP.
3. Verifique se o SQLite Server configurado aparece.

Você também pode fazer um teste direto: pergunte algo sobre o banco e veja se a IA chama o MCP.

Demonstração prática

Com a configuração concluída, você pode fazer perguntas como estas.

Consulta 1: listar as tabelas

Você: Quais tabelas existem no banco?
IA: [chama o MCP] Existem duas tabelas: users e orders.

Consulta 2: contar usuários

Você: Quantos usuários existem no total?
IA: [executa SELECT COUNT(*) FROM users] Existem três usuários.

Consulta 3: consultar os pedidos de um usuário

Você: O que João comprou?
IA: [executa uma consulta com JOIN] João comprou:
- MacBook Pro (12.999 yuans)
- AirPods (1.299 yuans)
Total: 14.298 yuans

Consulta 4: análise agregada

Você: Qual usuário gastou mais?
IA: [executa GROUP BY] João gastou mais, totalizando 14.298 yuans.

Você não precisa escrever SQL: a IA faz isso automaticamente. Essa é a principal vantagem do MCP.

Solução de problemas comuns

Problema 1: o MCP Server não inicia

Sintoma: a IA responde, mas não consulta o banco.

Soluções:

• Confira a sintaxe do arquivo de configuração; o JSON não pode ter vírgulas sobrando.
• Reinicie o Cursor por completo.
• Consulte os logs de saída do Cursor e procure erros relacionados a MCP.

Problema 2: o arquivo do banco de dados não é encontrado

Sintoma: aparece o erro cannot open database file.

Soluções:

• Confirme que o caminho é absoluto, não relativo.
• No Windows, confira o sentido das barras.
• Verifique se o arquivo existe com ls ou dir.

Problema 3: erro de permissão

Sintoma: Permission denied.

Soluções:

• Confira as permissões de leitura e escrita do arquivo do banco.
• No Windows, clique com o botão direito no arquivo, abra Propriedades → Segurança e confirme que o usuário atual tem permissão de leitura.

Dica de depuração: no VS Code ou Cursor, abra View → Output e selecione o canal MCP para ver os logs detalhados.

Caso prático 2 — integração com PostgreSQL

Cenário avançado: banco de dados de produção

SQLite é adequado para aprender e para projetos pequenos, mas no trabalho você provavelmente usa um banco de produção como PostgreSQL ou MySQL. A boa notícia é que o processo de configuração é o mesmo; apenas os parâmetros mudam.

Usaremos PostgreSQL como exemplo. A configuração do MySQL segue uma lógica parecida.

Diferenças de configuração: conexão e variáveis de ambiente

O PostgreSQL usa uma arquitetura cliente-servidor e exige dados de conexão. Nunca grave a senha diretamente no arquivo de configuração — esse é um dos erros de segurança mais comuns.

A forma correta é usar variáveis de ambiente.

Crie um arquivo .env na raiz do projeto e adicione-o ao .gitignore:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=myapp
POSTGRES_USER=readonly_user
POSTGRES_PASSWORD=your_secure_password

Em seguida, configure .cursor/mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "--stdio"
      ],
      "env": {
        "POSTGRES_HOST": "${POSTGRES_HOST}",
        "POSTGRES_PORT": "${POSTGRES_PORT}",
        "POSTGRES_DATABASE": "${POSTGRES_DATABASE}",
        "POSTGRES_USER": "${POSTGRES_USER}",
        "POSTGRES_PASSWORD": "${POSTGRES_PASSWORD}"
      }
    }
  }
}

Pontos importantes:

• --stdio: indica que a comunicação será feita pela entrada e saída padrão, localmente.
• env: define as variáveis de ambiente; o Cursor lerá automaticamente o arquivo .env do projeto.

Boas práticas de segurança

Ao dar à IA acesso ao banco de dados, a segurança vem em primeiro lugar. Estas são as práticas essenciais.

1. Use uma conta somente leitura

Não dê permissão de escrita à IA. Se ela interpretar o pedido de forma errada e executar DELETE ou UPDATE, o prejuízo pode ser grande.

Crie um usuário somente leitura:

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

Começar →Anúncio

-- Criar um usuário somente leitura
CREATE USER readonly_user WITH PASSWORD 'secure_password';

-- Conceder apenas permissão SELECT
GRANT CONNECT ON DATABASE myapp TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;

-- Garantir que novas tabelas também concedam apenas SELECT
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO readonly_user;

2. Limite o escopo de acesso

Se o banco contém tabelas sensíveis, como senhas ou dados de pagamento, bloqueie o acesso da IA:

-- Revogar o acesso a tabelas sensíveis
REVOKE SELECT ON TABLE user_passwords FROM readonly_user;
REVOKE SELECT ON TABLE payment_info FROM readonly_user;

3. Use uma réplica de leitura em produção

Se você realmente precisar usar MCP em produção — recomendo validar bem antes — conecte-o a uma Read Replica, e não ao banco principal. Se a IA gerar uma consulta muito pesada, pelo menos o serviço online não será afetado.

Demonstração prática

Com a configuração pronta, você pode realizar tarefas que vão além do exemplo com SQLite.

Consulta complexa com JOIN

Você: Calcule o salário médio de cada departamento.
IA: [executa uma consulta complexa]
SELECT d.name, AVG(e.salary) as avg_salary
FROM departments d
JOIN employees e ON d.id = e.department_id
GROUP BY d.name
ORDER BY avg_salary DESC;

Resultado:
- Tecnologia: média de 15.000 yuans
- Produto: média de 12.000 yuans
- Operações: média de 10.000 yuans

Análise de desempenho com plano de execução

Você: Por que esta consulta está tão lenta?
IA: [executa EXPLAIN] A consulta não usa um índice. Recomendo criar um índice para o campo user_id.

Análise de dados e relatórios

Você: Quantos usuários novos entraram em cada um dos últimos sete dias?
IA: [executa uma consulta por janela de tempo]
2024-01-10: 45 usuários
2024-01-11: 52 usuários
...

Problemas comuns

Problema 1: tempo limite de conexão

Sintoma: timeout connecting to database.

Soluções:

• Confira se o banco está em execução com pg_isready.
• Verifique se o firewall permite a conexão.
• Confirme os valores de host e porta.

Problema 2: falha de autenticação

Sintoma: authentication failed.

Soluções:

• Confira o nome de usuário e a senha.
• Confirme que pg_hba.conf permite a conexão desse usuário.
• Tente se conectar manualmente com psql para validar as credenciais.

Problema 3: permissões insuficientes

Sintoma: permission denied for table xxx.

Soluções:

• Isso pode ser positivo: significa que as permissões somente leitura estão funcionando.
• Se a tabela realmente precisar ser consultada, use uma conta administrativa para executar o comando GRANT adequado.

Caso prático 3 — integração com APIs

Cenário: permitir que a IA chame serviços externos

O banco de dados resolve consultas internas, mas às vezes os dados estão em uma API externa. Por exemplo:

• consultar o número de estrelas e a lista de issues de um repositório no GitHub;
• chamar uma API interna de microsserviço;
• obter previsão do tempo ou taxas de câmbio em tempo real.

Com MCP, a IA também pode chamar esses serviços.

Configurar um MCP Server do tipo HTTP

Chamadas de API são diferentes de consultas a banco de dados. Neste exemplo, não é preciso instalar um pacote do MCP Server; basta configurar o tipo HTTP.

Para a API do GitHub, configure .cursor/mcp.json assim:

{
  "mcpServers": {
    "github-api": {
      "url": "https://api.github.com",
      "headers": {
        "Accept": "application/vnd.github.v3+json",
        "User-Agent": "Cursor-MCP-Client"
      }
    }
  }
}

Se a API exigir autenticação, como em repositórios privados do GitHub, adicione um token:

{
  "mcpServers": {
    "github-api": {
      "url": "https://api.github.com",
      "headers": {
        "Accept": "application/vnd.github.v3+json",
        "Authorization": "Bearer ${GITHUB_TOKEN}",
        "User-Agent": "Cursor-MCP-Client"
      }
    }
  }
}

Guarde o token no arquivo .env:

GITHUB_TOKEN=ghp_your_personal_access_token_here

Como obter um token do GitHub:

1. Abra GitHub → Settings → Developer settings.
2. Acesse Personal access tokens → Tokens (classic).
3. Clique em Generate new token e marque as permissões necessárias, como repo e user.
4. Copie o token; ele só será exibido uma vez.

Demonstração prática

Depois da configuração, você pode pedir à IA para chamar a API diretamente.

Consultar informações do repositório

Você: Quantas estrelas tem o repositório facebook/react?
IA: [chama GET /repos/facebook/react]
O repositório React tem atualmente 218.345 estrelas e 79.234 forks.

Obter as issues mais recentes

Você: Quais são as issues recentes de facebook/react?
IA: [chama GET /repos/facebook/react/issues?state=open&per_page=5]
As cinco issues mais recentes são:
1. [Bug] useEffect é executado duas vezes no modo estrito
2. [Feature] Suporte à nova API do Suspense
3. [Question] Como otimizar a renderização de listas grandes
...

Analisar a frequência de commits

Você: Quantos commits o facebook/react recebeu na última semana?
IA: [chama GET /repos/facebook/react/commits?since=...]
Houve 43 commits nos últimos sete dias, e os principais colaboradores foram...

Configurar uma API personalizada

APIs internas também podem ser configuradas dessa forma. Imagine que sua empresa tenha um serviço de usuários:

{
  "mcpServers": {
    "user-service": {
      "url": "https://api.yourcompany.com/user-service",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_API_KEY}",
        "Content-Type": "application/json"
      }
    }
  }
}

Depois, basta perguntar:

Você: Consulte o histórico de pedidos do usuário de ID 12345.
IA: [chama a API interna] O usuário 12345 fez oito pedidos nos últimos 30 dias, totalizando 3.200 yuans.

Pontos de atenção

Limites de chamadas de API

Muitas APIs têm limites de frequência. A versão gratuita da API do GitHub permite apenas 60 chamadas por hora sem autenticação. Se a IA fizer chamadas demais, você atingirá o limite rapidamente.

Soluções:

• Use um token de autenticação; no GitHub, o limite autenticado sobe para 5.000 chamadas por hora.
• Peça à IA para reduzir as chamadas e reutilizar resultados sempre que possível.

Riscos de segurança

Dar à IA acesso a uma API equivale a dar a ela capacidade de operar um serviço externo. Portanto:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

• use tokens somente leitura, sem permissões de escrita;
• altere os tokens regularmente;
• monitore os logs de chamadas da API.

Técnicas avançadas e boas práticas

Usar vários MCP Servers ao mesmo tempo

Você pode configurar vários MCP Servers em um único projeto. A IA escolherá automaticamente a ferramenta adequada.

Por exemplo, esta é uma configuração possível:

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "D:/projects/myapp/data.db"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "--stdio"],
      "env": {
        "POSTGRES_HOST": "${POSTGRES_HOST}",
        "POSTGRES_PORT": "${POSTGRES_PORT}",
        "POSTGRES_DATABASE": "${POSTGRES_DATABASE}",
        "POSTGRES_USER": "${POSTGRES_USER}",
        "POSTGRES_PASSWORD": "${POSTGRES_PASSWORD}"
      }
    },
    "github-api": {
      "url": "https://api.github.com",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}",
        "Accept": "application/vnd.github.v3+json"
      }
    }
  }
}

Com essa configuração, você pode pedir:

Você: Consulte quantos usuários existem no SQLite local e depois verifique quantas estrelas nosso repositório tem no GitHub.
IA: [seleciona automaticamente o MCP sqlite] Existem 245 usuários locais.
    [seleciona automaticamente o MCP github-api] O repositório tem 1,2 mil estrelas.

A IA identifica pelo conteúdo da pergunta qual ferramenta deve usar.

Configuração do projeto versus configuração global

As duas abordagens atendem a cenários diferentes.

Configuração do projeto (.cursor/mcp.json):

• indicada para bancos de dados e APIs específicos do projeto;
• vantagem: os projetos não interferem entre si e a configuração pode ser versionada no Git, desde que informações sensíveis sejam excluídas;
• desvantagem: é preciso configurar cada projeto separadamente.

Configuração global (~/.cursor/mcp.json):

• indicada para ferramentas genéricas, como sistema de arquivos e APIs comuns;
• vantagem: uma configuração funciona em todos os projetos;
• desvantagem: pode ficar confusa, e o arquivo fora do projeto dificulta a colaboração da equipe.

Minha recomendação:

• banco de dados e APIs específicas do projeto → configuração do projeto;
• GitHub, previsão do tempo e outras APIs genéricas → configuração global;
• depois de concluir o desenvolvimento, documente a configuração do projeto para que outras pessoas da equipe possam reproduzi-la.

Otimização de desempenho

Cada chamada do MCP executa uma consulta ou requisição de API real. Se isso acontecer muitas vezes, o fluxo pode ficar mais lento. Algumas práticas ajudam.

1. Peça à IA para reutilizar resultados

Você: Consulte a lista de usuários e lembre-se do resultado, pois vamos usá-lo depois.
IA: [consulta e armazena o contexto] Existem 245 usuários...

Você: Entre aqueles 245 usuários, quantos são VIP?
IA: [analisa o resultado anterior sem consultar novamente]

2. Limite a complexidade das consultas

Não deixe a IA criar consultas complexas demais. Se ela gerar um SQL com dez níveis de aninhamento, interrompa e simplifique manualmente.

3. Use índices no banco de dados

Por mais inteligente que seja a consulta gerada pela IA, ela continua limitada pelo desempenho do banco. Crie índices onde forem necessários.

Técnicas de depuração

Quando algo der errado, estas práticas ajudam a encontrar a causa rapidamente.

1. Consulte os logs do MCP

No painel View → Output do Cursor, selecione o canal MCP. Ali você encontra:

• logs de inicialização do MCP Server;
• parâmetros e resultados de cada chamada de ferramenta;
• rastreamentos de erros.

2. Teste a configuração do MCP

Depois de editar o arquivo, comece com uma pergunta simples:

Você: Teste a conexão com o banco e diga quais tabelas existem.

Se isso falhar, o problema provavelmente está na configuração.

3. Faça uma validação manual

Se a IA disser que a consulta falhou, execute-a manualmente. Assim você descobre se o erro está no SQL gerado ou nas permissões e na conexão.

Significado dos códigos de erro mais comuns

• ENOENT: o arquivo ou caminho não existe; confira o caminho.
• ECONNREFUSED: a conexão foi recusada; o banco pode estar parado ou a porta pode estar errada.
• EACCES: permissão insuficiente no arquivo ou no banco.
• ERR_MODULE_NOT_FOUND: o pacote do MCP Server não está instalado; confira o comando npx.
• ETIMEDOUT: tempo esgotado devido a problema de rede ou consulta lenta.

Conclusão

Depois de configurar o MCP, minha forma de programar mudou de verdade.

Antes, uma simples consulta exigia alternar entre três janelas, o que interrompia constantemente meu raciocínio. Agora, pergunto diretamente no Cursor e recebo o resultado em segundos, sem sair da lógica do código.

Este artigo tem mais de 3.000 palavras, mas o essencial se resume a três pontos:

1. Entender o conceito: MCP fornece ferramentas à IA para que ela execute tarefas, em vez de apenas dar sugestões.
2. Seguir a configuração: use SQLite para aprender, PostgreSQL em cenários de produção e APIs para ampliar as capacidades.
3. Priorizar a segurança: use permissões somente leitura, variáveis de ambiente e mantenha a IA longe do banco principal de produção.

Reserve 15 minutos hoje para configurar um MCP de SQLite. O ganho não é de apenas 10% ou 20%; é uma maneira completamente diferente de trabalhar.

Por fim, o MCP ainda é uma tecnologia relativamente nova. A especificação continua evoluindo, e a comunidade cria novos Servers rapidamente. Tenho uma lista de MCP Servers salva no GitHub; vale a pena explorar para encontrar ferramentas adequadas ao seu fluxo.