Supabase MCP no Claude Code: como conectar o agente ao schema do seu banco

Fala aí, beleza? Nada irrita mais que ver o agente escrever user_id no SQL quando a coluna do seu banco se chama usuario_id 😅

Isso acontece porque, sem acesso ao banco, o Claude Code só consegue INFERIR a estrutura a partir do que está no código: um model aqui, uma query antiga ali, um type desatualizado acolá

O Supabase MCP muda essa lógica: o agente passa a consultar a estrutura de verdade, listando tabelas, rodando SQL, olhando o histórico de migrações e gerando tipos TypeScript a partir do schema

Neste post tu vê como conectar, quais parâmetros seguram o estrago e o que muda na prática em consulta, migração e ajuste de tipos

O que você precisa antes de começar

A lista é curta, e a boa notícia é que não tem nada pra instalar na sua máquina:

• Claude Code instalado e funcionando no projeto
• Conta e projeto na Supabase, de preferência um projeto de desenvolvimento, com dados não produtivos ou ofuscados (essa é a recomendação da própria Supabase, não invenção minha)
• Navegador disponível, porque a autenticação abre um fluxo OAuth fora do terminal
• Supabase CLI rodando, só se você quiser apontar pra uma instância local, que expõe o MCP em http://127.0.0.1:54321/mcp

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

E aqui vale o aviso que economiza uns 20 minutos de busca: o servidor MCP da Supabase é remoto e hospedado

Ele vive em https://mcp.supabase.com/mcp, com transporte http

Ou seja: não tem npm install, não tem binário local, não tem processo pra subir. Tu só aponta pra URL, beleza?

Passo a passo: conectando o Claude Code ao seu banco Supabase

1. Registre o servidor com o comando de CLI

A documentação da Supabase traz o comando pronto pro Claude Code:

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?features=docs,account,database,debugging,development,functions,branching"

Repara em duas coisas: --scope project deixa a configuração no projeto, e --transport http é o que diz que a coisa é remota

O erro comum deste passo: sair procurando um pacote npm do Supabase MCP pra instalar antes. Não existe esse passo, o servidor é hospedado

2. Ou escreva a mesma entrada direto no .mcp.json

Se você prefere versionar a configuração na mão, dá no mesmo. A entrada do servidor fica assim:

"supabase": {
  "type": "http",
  "url": "https://mcp.supabase.com/mcp?features=docs,account,database,debugging,development,functions,branching"
}

O erro comum deste passo: montar a entrada como se fosse um servidor local, com comando e argumentos. Não tem comando pra rodar, é transporte http apontando pra URL

3. Autentique o servidor

Com o servidor registrado, você seleciona o servidor supabase e escolhe Authenticate

Isso abre o navegador pra você fazer login e conceder acesso à sua organização

E se liga nisso, que é a parte que mudou: o Personal Access Token não é mais obrigatório

O servidor usa OAuth por padrão, com registro dinâmico de cliente. O PAT só entra em cenário de CI/CD ou outro fluxo não interativo, passado como header

O erro comum deste passo: seguir tutorial antigo, gerar um PAT e ficar tentando encaixar ele na configuração. Na maioria dos casos você não precisa

4. Ajuste o escopo pelos parâmetros de query

Aqui é onde você decide o tamanho da chave que está entregando

São dois parâmetros que fazem a diferença toda:

• project_ref=<ID do projeto> desabilita as ferramentas de nível de conta e trava o servidor naquele projeto. Sem ele, o servidor alcança TODOS os projetos da sua conta
• read_only=true desabilita todas as ferramentas de escrita e faz o execute_sql rodar como um usuário Postgres somente leitura

Na prática, a URL fica mais ou menos assim:

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=SEU_PROJECT_REF&read_only=true&features=docs,database,debugging,development"

O erro comum deste passo: esquecer o project_ref e dar acesso amplo demais sem perceber. É o tipo de coisa que só aparece quando o agente lista um projeto que não tinha nada a ver com a tarefa

5. Escolha os grupos de features

As ferramentas são organizadas em grupos, e você liga só o que precisa pelo parâmetro features

Os grupos são: docs, account, database, debugging, development, functions, branching e storage

Todos vêm habilitados por padrão, exceto o storage

Menos grupo ligado, menos superfície pro agente fazer besteira. Se a sua tarefa é só entender schema e rodar consulta, database já resolve

Três caminhos de conexão: comando manual, plugin oficial ou instância local

Não existe um caminho certo pra todo mundo. Existe o que combina com o seu setup:

O plugin é o caminho mais curto, porque ele empacota o servidor MCP junto com as agent skills da Supabase

A instalação passa por três comandos:

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install supabase@claude-plugins-official

E depois, dentro do Claude Code:

/reload-plugins

Se as skills que vieram no pacote não engatarem do jeito que você esperava, vale checar antes o que faz uma skill do Claude Code não funcionar no seu projeto, porque quase sempre o problema não é o plugin em si

O que muda na prática: consulta, migração e tipos

Bom, configuração feita. Mas o que muda de verdade no dia a dia?

Bora ver os três cenários que aparecem toda hora

Como o agente lê o schema do seu banco?

O grupo de banco expõe o list_tables, que lista as tabelas de um ou mais schemas

Ele aceita um parâmetro com a lista de schemas a incluir, e o padrão é todos

Junto disso vem o execute_sql, a ferramenta genérica que o modelo usa pra executar consulta SQL

A diferença é sutil no texto e enorme na prática: em vez de deduzir que a tabela chama profiles porque viu isso num arquivo antigo, o agente CONFIRMA o nome antes de escrever a query

É o mesmo salto de qualidade de quando você para de programar de cabeça e abre o banco pra olhar

Como aplicar migração com o agente?

O servidor traz list_migrations e apply_migration

O primeiro deixa o agente ver o histórico do que já foi aplicado, o segundo aplica a mudança

Isso resolve o clássico "o agente escreveu uma migration que recria uma coluna que já existe", porque ele consegue olhar o histórico antes de propor

Aqui é onde vale combinar com subagentes no Claude Code, separando quem só investiga schema de quem tem permissão pra mexer

Como manter os tipos TypeScript alinhados ao banco?

Esse é meu favorito, confesso

O servidor MCP inclui geração de tipos TypeScript a partir do schema do banco

Aí o código para de viver com aquele any estratégico e aquele campo que mudou de nome faz três sprints e ninguém atualizou no front

O tipo passa a refletir a estrutura real, não a estrutura que alguém lembrava 😀

Problemas comuns e como se proteger ao dar acesso ao banco

Dar acesso ao banco pra um agente é poderoso e merece cuidado. Se liga nos casos:

O agente enxerga projetos demais

Sintoma: o agente cita ou consulta projeto que não tem nada a ver com a tarefa atual

Causa: sem o project_ref, o servidor tem acesso a todos os projetos da conta

Solução: passe project_ref=<ID do projeto> na URL. Além de restringir ao projeto, isso desabilita as ferramentas de nível de conta

Medo de escrita indevida no banco

Sintoma: você trava na hora de aprovar qualquer ação, com receio de um UPDATE sem WHERE

Causa: por padrão as ferramentas de escrita estão disponíveis

Solução: read_only=true desabilita todas as ferramentas de escrita e roda o execute_sql como um usuário Postgres somente leitura

Prompt injection vindo de dentro do banco

Sintoma: o agente segue uma instrução que ninguém digitou no chat

Causa: texto malicioso armazenado no próprio banco pode carregar instruções ocultas. E olha que a Supabase é explícita: esse risco existe MESMO com o modo somente leitura ligado, e pode levar à exposição de dados apesar da RLS aplicada

Solução: não tratar read_only como blindagem. Trabalhar com dados não produtivos ou ofuscados e revisar o que o agente executa

Uso indevido em produção

Sintoma: alguém do time aponta o MCP pro banco que atende usuário real

Causa: a expectativa de que o servidor é uma ponte de aplicação. Não é

Solução: a Supabase declara o servidor como ferramenta de desenvolvimento e teste, que roda com as permissões do desenvolvedor. Uso interno, nunca conectado a dados de produção e nunca entregue a clientes ou usuários finais

A prevenção, resumindo o combo: projeto de desenvolvimento com dados ofuscados, read_only ligado, project_ref travado e o recurso de branching pra criar um branch de desenvolvimento do banco, deixando o agente testar as alterações antes do merge

Tome cuidado com o atalho de "depois eu ajusto os parâmetros". Esse depois nunca chega…

Próximo passo

O ganho do Supabase MCP no Claude Code cabe numa frase: o agente consulta a estrutura em vez de adivinhar

E isso derruba uma categoria inteira de erro chato, aquele SQL bonito que quebra porque a coluna tem outro nome

O próximo passo concreto é bem simples:

1. Conecte em um projeto de desenvolvimento, com read_only=true e project_ref na URL
2. Peça um list_tables só pra validar que a conexão está de pé
3. Só depois disso libere migração, e de preferência em um branch de desenvolvimento do banco

Pra referência, o servidor é open source e mora no repositório oficial da Supabase no GitHub, com o caminho antigo supabase-community/supabase-mcp apontando pro mesmo lugar

E um detalhe que confunde muita gente: a Supabase anunciou em fevereiro de 2026 que virou conector oficial do Claude, mas aquilo diz respeito ao Claude web e desktop, que é produto diferente do Claude Code

Aqui a gente falou do Claude Code mesmo, no terminal, dentro do seu projeto 🙂

Bora testar? até o próximo post!