Capítulo 04 / Da nuvem read-only para o local read-write

MCP local

Trabalhar com agentes de IA acoplados ao banco mudou de figura. Antes, o agente tinha que se comportar diante do simpe-ms-test compartilhado. Agora, apontando para o seu Postgres local, ele pode fazer, não só olhar.

O que é MCP, em uma linha

MCP (Model Context Protocol) é um padrão que permite a um cliente de IA — Claude Code, Cursor, etc. — chamar ferramentas e ler recursos de um servidor externo. Aplicado a banco de dados, isso significa que o agente pode listar tabelas, ler colunas, rodar queries e (com permissão) executar SQL, sem que você precise copiar e colar nada.

Antes & depois

Antes — até abr/2026

MCP do simpe-ms-test (cloud)

  • Apontava para o banco de QA na nuvem
  • Modo read_only=true obrigatório
  • Agente conseguia inspecionar mas não mutar
  • Risco: query pesada acidental afetava o time todo
  • Migrations e mutações precisavam ser feitas manualmente fora do agente
Agora — a partir de mai/2026

MCP do Supabase local

  • Aponta para o seu Postgres em Docker
  • Pode ser read-write — banco é descartável
  • Agente pode rodar mutations, criar migrations, testar SQL na hora
  • Sem afetar ninguém: cada dev tem seu próprio
  • Reset rápido com npm run db:reset a qualquer momento

A combinação banco descartável + agente com escrita destrava um ciclo: pedir para o agente gerar uma migration, aplicar, testar, e se quebrar, db:reset e tentar de novo. Tudo no seu local, sem cerimônia.

Endpoint

Quando você roda supabase start, o stack expõe automaticamente um servidor MCP nesta URL: 

http://127.0.0.1:54321/mcp

Não precisa autenticar — é a sua máquina, não tem ninguém escutando. Não requer chave, não expira, não tem rate limit.

Como sei que está no ar?

Olha a saída do supabase start: a tabela "🔧 Development Tools" lista MCP entre Studio e Mailpit. Se está nessa lista, está vivo.

Configurando no Claude Code

O projeto já tem um .mcp.json na raiz apontando para o servidor MCP local. Não precisa editar nada: 

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "http://127.0.0.1:54321/mcp"
    }
  }
}

Dentro do Claude Code, rode /mcp para habilitar o servidor — é instantâneo, sem OAuth. A partir daí, o agente passa a "ver" o seu banco local. Se o supabase start não estiver rodando, o servidor MCP não responde e o Claude Code avisa — basta subir o stack.

O que dá pra pedir agora

Algumas coisas que ficaram simples com MCP local read-write:

  • "Olha o schema da tabela monitoramento e me diz se tem trigger BEFORE INSERT"
  • "Cria uma migration que adiciona coluna X com default Y, aplica, e me confirma que rodou"
  • "Insere 10 entregas de teste com semáforos variados e mostra o que ficou no home_dashboard_cache"
  • "Roda essa query e me diz quantas linhas voltaram"
  • "Verifica se essa RPC existe e qual é a assinatura dela"

Tudo isso sem você nunca abrir o Studio ou copiar SQL para lugar nenhum. O agente consegue trabalhar como um desenvolvedor pareando: escreve, testa, ajusta.

Quando ainda usar o MCP cloud

O MCP do simpe-ms-test ainda tem utilidade para uma coisa específica: quando você quer verificar comportamentos contra dados reais e em volume que o seed local não reproduz. Por exemplo:

  • Investigar uma performance que só aparece com 5000+ entregas
  • Confirmar a forma de um JSONB populado por uso real
  • Testar uma query analítica em distribuição de dados realista

Para esses casos, o cloud read-only continua valendo. Para o resto, o local read-write é o caminho.

Nunca configure o MCP de produção

Não existe um cenário onde adicionar o simpe-ms-dev como MCP faça sentido. Mesmo em modo read-only, é risco desnecessário e não traz nenhum dado que o cloud de teste não traga em forma equivalente.