🗄️ O que o Database MCP Faz
🎯 SQL Direto no Claude
O Database MCP conecta o Claude a bancos PostgreSQL. Ele pode explorar schemas, executar queries SELECT, analisar dados e sugerir otimizacoes. Com acesso ao banco real, as sugestoes de codigo e SQL sao baseadas em fatos, nao em suposicoes.
- • execute_query: Roda SQL diretamente no banco conectado
- • list_tables: Lista todas as tabelas e views do banco
- • describe_table: Mostra colunas, tipos e constraints de uma tabela
- • get_schema: Retorna o schema completo do banco
📊 Da Suposicao Para o Fato
- Sem MCP: Claude supoe o schema e pode errar nomes de colunas e tipos
- Com MCP: Claude ve o schema REAL e escreve SQL preciso desde o primeiro try
- Economia de iteracoes: queries certas na primeira tentativa em vez de 3-4 correcoes
💡 Dica Pratica
O primeiro comando apos conectar o Database MCP deve ser: 'liste todas as tabelas e descreva as principais'. Isso da ao Claude uma visao geral do banco e permite que ele escreva queries muito mais precisas em pedidos subsequentes.
✓ O que FAZER
- ✓ Comecar com list_tables e describe_table para contexto
- ✓ Usar LIMIT em todas as queries
- ✓ Conectar a bancos de desenvolvimento/staging
✗ O que NAO fazer
- ✗ Conectar a producao com usuario admin
- ✗ Rodar queries sem LIMIT em tabelas grandes
- ✗ Executar DDL (CREATE, ALTER, DROP) sem revisar
🐘 Instalacao PostgreSQL
🎯 Conexao Direta ao Postgres
Para PostgreSQL generico, a conexao e feita via connection string padrao. O MCP suporta qualquer PostgreSQL acessivel pela rede (local, cloud, Docker).
-
•
Comando:
claude mcp add postgres -- npx -y @anthropic/mcp-postgres "postgresql://user:pass@host:5432/dbname" - • Local: postgresql://postgres:senha@localhost:5432/meu_banco
- • Cloud: Use o hostname do seu provider (AWS RDS, GCP Cloud SQL, etc.)
- • Docker: Use o nome do container ou host.docker.internal
📊 Detalhes da Connection String
- Formato: postgresql://usuario:senha@host:porta/banco
- Para SSL (cloud): adicione ?sslmode=require ao final
- Nunca commite a connection string - use variaveis de ambiente
💡 Dica Pratica
Crie um usuario READ-ONLY especifico para o Claude: CREATE USER claude_reader WITH PASSWORD 'xxx'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_reader; Isso garante que o Claude nunca pode modificar dados acidentalmente, mesmo em desenvolvimento.
✓ O que FAZER
- ✓ Criar usuario read-only para o Claude
- ✓ Usar variaveis de ambiente para connection string
- ✓ Testar conexao antes de depender dela
✗ O que NAO fazer
- ✗ Usar usuario admin/superuser
- ✗ Commitar connection strings
- ✗ Conectar a producao sem read-only
⚡ Instalacao Supabase
🎯 Setup Especifico para Supabase
Supabase tem um MCP dedicado que vai alem de SQL puro, oferecendo acesso a auth, storage e funcionalidades especificas do Supabase.
-
•
Comando:
claude mcp add supabase -- npx -y @supabase/mcp-server-supabase --supabase-url https://xxx.supabase.co --supabase-key sua-service-role-key - • URL: Encontre em Supabase Dashboard → Settings → API → Project URL
- • Key: Use service_role key (nao anon key) para acesso completo
- • Extra: O MCP do Supabase inclui tools para auth e storage alem de database
📊 Supabase vs PostgreSQL Generico
- Supabase MCP: acesso a auth, storage, realtime + database
- PostgreSQL MCP: apenas database (SQL puro)
- Use Supabase MCP se usa Supabase; PostgreSQL MCP para outros Postgres
💡 Dica Pratica
A service_role key do Supabase tem acesso TOTAL ao banco, bypassando RLS. Trate-a com o mesmo cuidado que uma senha de admin. Nunca exponha em frontend, nunca commite, sempre use via variavel de ambiente: export SUPABASE_SERVICE_KEY=eyJxxx.
✓ O que FAZER
- ✓ Usar service_role key para acesso completo via MCP
- ✓ Guardar key em variavel de ambiente
- ✓ Usar Dashboard para encontrar URL e key
✗ O que NAO fazer
- ✗ Usar anon key (acesso limitado pelo RLS)
- ✗ Expor service_role key em codigo
- ✗ Compartilhar key com outros devs (cada um cria a sua)
💼 Casos de Uso
🎯 Workflows com Banco de Dados
O Database MCP e mais util quando voce esta debugando problemas de dados, explorando schemas desconhecidos ou criando migrations. Ele traz a verdade do banco para o contexto do Claude.
- • Debug: 'mostre as ultimas 10 orders com status failed e seus error_messages'
- • Exploration: 'descreva todas as tabelas e identifique relacoes entre elas'
- • Migration: 'crie uma migration para adicionar coluna verified_at na tabela users'
- • Performance: 'rode EXPLAIN ANALYZE nesta query e sugira otimizacoes'
📊 Impacto em Diferentes Cenarios
- Debug: encontra problemas de dados em segundos vs minutos com pgAdmin
- Exploration: mapeia bancos desconhecidos rapidamente (onboarding)
- Migration: gera DDL baseado no schema REAL, nao em suposicoes
💡 Dica Pratica
Workflow poderoso para debugging: 'descreva a tabela orders, mostre as ultimas 5 orders com status failed, e analise o padrao de erro'. O Claude ve o schema, busca dados reais e identifica patterns - tudo em uma interacao. Sem MCP, voce precisaria de 3-4 ferramentas diferentes.
✓ O que FAZER
- ✓ Usar para debug rapido de problemas de dados
- ✓ Explorar schemas de bancos desconhecidos
- ✓ Gerar migrations baseadas no estado real
✗ O que NAO fazer
- ✗ Rodar queries pesadas em producao
- ✗ Fazer INSERT/UPDATE/DELETE sem revisar
- ✗ Confiar cegamente em migrations geradas (sempre revise)
🟡 Token Impact: Moderate (~1.500 tokens)
🎯 Custo Controlavel
O overhead fixo do Database MCP e moderado (~1.500 tokens), mas o custo real pode ser muito maior dependendo dos dados retornados pelas queries. Uma query sem LIMIT em tabela grande pode injetar dezenas de milhares de tokens no contexto.
- • Overhead fixo: ~1.500 tokens por mensagem
- • Query simples (10 rows): +500-1.000 tokens de resultado
- • Query sem LIMIT (1000+ rows): +10.000-50.000+ tokens de resultado!
- • Schema completo: +2.000-5.000 tokens dependendo do banco
📊 O Perigo das Queries Sem Limite
- SELECT * FROM users (sem LIMIT): pode retornar milhares de rows
- Cada row ocupa ~50-100 tokens dependendo das colunas
- 1.000 rows x 80 tokens = 80.000 tokens consumidos de uma vez
💡 Dica Pratica
SEMPRE inclua LIMIT nos seus pedidos: 'mostre as ultimas 10 orders' em vez de 'mostre as orders'. Se precisa analisar muitos dados, peca resumos: 'conte quantas orders por status' em vez de 'liste todas as orders'. Agregacoes (COUNT, AVG, SUM) sao muito mais eficientes em tokens.
✓ O que FAZER
- ✓ Sempre usar LIMIT em queries
- ✓ Preferir agregacoes (COUNT, AVG) sobre SELECT *
- ✓ Selecionar colunas especificas em vez de *
✗ O que NAO fazer
- ✗ NUNCA SELECT * sem LIMIT em tabelas grandes
- ✗ NUNCA pedir 'todos os dados' da tabela
- ✗ NUNCA ignorar o custo de dados retornados
🛡️ Seguranca em Production
🎯 Regras Inegociaveis
Conectar o Claude a um banco de producao e como dar as chaves do cofre. Um DELETE sem WHERE, um DROP TABLE acidental ou um UPDATE em massa pode destruir dados de clientes. Regras de seguranca aqui nao sao sugestoes - sao mandatorias.
- • PRODUCAO: SEMPRE usuario read-only. ZERO permissoes de escrita
- • STAGING: Usuario com write permitido, mas sem DROP/TRUNCATE
- • DESENVOLVIMENTO: Pode ser admin para agilidade
- • CREDENCIAIS: NUNCA em arquivos commitados. SEMPRE variaveis de ambiente
📊 Cenarios de Desastre Reais
- Claude executa 'DELETE FROM users WHERE active = false' - apaga dados reais
- Claude roda 'ALTER TABLE' que quebra schema de producao
- Connection string commitada no Git - exposta em repo publico
💡 Dica Pratica
Crie este usuario para producao e NUNCA use outro: CREATE USER claude_prod_reader WITH PASSWORD 'xxx'; GRANT CONNECT ON DATABASE prod TO claude_prod_reader; GRANT USAGE ON SCHEMA public TO claude_prod_reader; GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_prod_reader; Teste tentando INSERT - deve falhar.
✓ O que FAZER
- ✓ Criar usuario read-only dedicado para o Claude
- ✓ Testar que o usuario nao pode escrever
- ✓ Usar staging/dev para operacoes de escrita
✗ O que NAO fazer
- ✗ NUNCA conectar a producao com admin
- ✗ NUNCA permitir escrita em producao via MCP
- ✗ NUNCA commitar connection strings
📋 Resumo do Modulo
Proximo:
6.7 - MCP #5: Google Sheets