Cursor com MCP do Supabase não funciona? Configuração e correções

Você adicionou o servidor do Supabase ao Cursor, reiniciou o editor, e agora o painel de MCP mostra um ponto vermelho, uma lista de ferramentas vazia ou um spinner que nunca para. Ou então parece conectado, mas o Agent insiste que não tem ferramentas de banco de dados. Essa diferença entre "configurado" e "funcionando" é a forma mais comum de Cursor com MCP do Supabase não funciona, e quase todos os casos se resumem a uma lista curta de causas: um arquivo de configuração no lugar errado, um login não concluído, um registro OAuth desatualizado, uma URL com escopo que esconde ferramentas, ferramentas demais somando vários servidores, uma particularidade do npx no Windows, um projeto pausado ou um pedido de aprovação que ninguém clicou. A seguir, cada causa na ordem em que vale a pena verificar, com a configuração exata, uma tabela de sintomas e as verificações de log que economizam uma tarde inteira.

Como funciona a ligação entre o Cursor e o Supabase

O MCP, o Model Context Protocol, permite que o agente de IA de um editor chame ferramentas externas. O Supabase publica um servidor MCP cujas ferramentas permitem ao Agent listar tabelas, executar SQL, aplicar migrações, ler logs do projeto e pesquisar na documentação. O Cursor é o cliente. Ele lê um arquivo JSON, se conecta ou inicia o servidor, pede a lista de ferramentas e mostra essas ferramentas nas configurações.

Quando algo quebra, quebra em uma de quatro etapas, e saber qual reduz a busca pela metade:

1. Leitura da configuração: o arquivo está ausente, inválido ou na pasta errada.
2. Conexão: a URL não pode ser alcançada ou o comando não pode ser iniciado.
3. Autenticação: o login no navegador não terminou, ou o token está errado.
4. Listagem de ferramentas: o servidor conectou, mas seus parâmetros escondem ferramentas ou o Agent está sobrecarregado.

Servidor hospedado ou npx local

Você tem três formas de se conectar, e misturar as configurações delas é uma fonte clássica de confusão.

💡 Escolha apenas uma. Se o mesmo nome de servidor aparecer em dois arquivos de configuração, ou se uma entrada remota e uma entrada npx reivindicarem supabase, você pode gastar uma hora depurando a errada.

Onde o mcp.json deve ficar

O Cursor lê dois locais. Um arquivo de projeto em .cursor/mcp.json vale para aquele repositório. Um arquivo de usuário em ~/.cursor/mcp.json vale em todos os lugares, e a documentação do Supabase aponta para ele quando você quer uma única configuração para todos os projetos.

Três erros respondem por uma parcela surpreendente dos pontos vermelhos: salvar mcp.json na raiz do repositório em vez de dentro de .cursor, deixar uma vírgula sobrando no fim que torna o JSON inválido, e escrever errado a propriedade de nível superior mcpServers. Cole o arquivo em qualquer validador de JSON antes de culpar o servidor.

A configuração limpa que funciona

Parta de um estado conhecido e bom antes de tentar correções. Apague entradas meio editadas e depois adicione exatamente uma das configurações abaixo.

URL remota com login no navegador

O servidor hospedado precisa apenas de uma URL:

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Copiar prompt

Salve o arquivo, reinicie o Cursor e abra Settings > Cursor Settings > Tools & MCP. A entrada do Supabase deve oferecer um login. Uma janela do navegador abre, você entra no Supabase e concede acesso à sua organização. Se preferir o terminal, a CLI do Cursor tem três comandos correspondentes:

agent mcp enable supabase
agent mcp login supabase
agent mcp list

Copiar prompt

Em seguida, execute o teste rápido que o Supabase sugere em um novo chat do Agent: "Quais tabelas existem no meu banco de dados? Use as ferramentas de MCP." Uma resposta real com os nomes das suas tabelas significa que toda a cadeia funciona. Um pedido de desculpas por ferramentas ausentes indica que uma das correções abaixo se aplica.

Token e alternativa com npx

Algumas equipes ainda rodam o servidor localmente com um token de acesso pessoal criado nas configurações da sua conta no Supabase. A configuração inicia o pacote por meio de npx:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<your-project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

Copiar prompt

Essa rota exige o Node.js instalado. As flags --read-only e --project-ref fazem o mesmo papel dos parâmetros de URL descritos mais adiante. Trate o token como uma senha: nunca faça commit de um mcp.json que o contenha em um repositório público. O Supabase já mudou sua configuração recomendada ao longo do tempo, então confira a aba de conexão MCP no painel do Supabase se as instruções atuais forem diferentes deste trecho.

No Windows, é preciso um wrapper cmd

No Windows, npx é um shim em lote, e iniciá-lo diretamente costuma terminar em um erro de spawn. Envolva-o em cmd /c:

{
  "mcpServers": {
    "supabase": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<your-project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

Copiar prompt

Execute node --version e npx --version em um terminal novo antes de tudo. Se o Node foi instalado depois que o Cursor abriu, o editor ainda guarda o PATH antigo, então feche o Cursor por completo e abra de novo, não apenas a janela. A rota por URL hospedada evita tudo isso, o que é um bom motivo para preferi-la em máquinas Windows com cadeias de ferramentas bloqueadas.

Oito sintomas e suas correções

Compare o que você vê com uma linha da tabela e depois vá para a seção correspondente abaixo.

Ponto vermelho e lista de ferramentas vazia

Um ponto vermelho significa que o Cursor nunca obteve uma conexão funcional, então comece pelas verificações mais baratas. Valide o JSON, confirme que o arquivo está em .cursor/mcp.json ou ~/.cursor/mcp.json e pressione o botão de atualizar nas configurações de MCP, que já reativou servidores travados para alguns usuários no fórum do Cursor. Reinicie o Cursor após cada mudança na configuração, já que as próprias notas do Supabase dizem que é preciso reiniciar antes que todas as ferramentas apareçam.

Se o ponto continuar vermelho, os logs descritos abaixo vão apontar a falha em uma única linha. Resista à vontade de reescrever a configuração inteira neste ponto. Mudar uma variável por reinício parece mais lento no papel e é muito mais rápido na prática.

Loops de login e erros de client_id

Com o servidor hospedado, o Cursor conclui a transferência OAuth abrindo uma página em localhost:8787. Duas falhas aparecem ali.

• Um erro 431 antes do login terminar. Cookies grandes armazenados para localhost pelos seus outros servidores de desenvolvimento podem provocá-lo. Limpe os cookies apenas de localhost, não de todo o navegador, e tente o login de novo.
• "Unrecognized client_id". O Cursor está reutilizando um registro OAuth em cache de uma configuração antiga. Desconecte o servidor, remova-o, feche o Cursor por completo e adicione-o de novo para que ele se registre do zero.

Se o navegador nunca abrir, procure nos logs do Cursor a URL de autorização, cole-a manualmente no navegador, conclua o login, e o callback deve voltar ao Cursor e estabelecer a conexão.

Conectado, mas faltam ferramentas

Um ponto verde com um Agent sem enxergar nada costuma ser a configuração fazendo exatamente o que você pediu. Quatro parâmetros de URL mudam quais ferramentas existem:

Um exemplo com escopo fica assim: https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true

Três resultados surpreendem as pessoas. Adicionar project_ref desativa as ferramentas de conta, então a ausência de uma listagem de projetos é esperada. O grupo Storage vem desativado por padrão e precisa ser ativado. E read_only=true faz todas as gravações falharem por design. Peça ao Agent que liste todas as ferramentas do Supabase que ele pode chamar agora, e compare essa lista com os seus parâmetros.

💡 skip_elicitations remove uma rede de segurança. Use-o apenas em um projeto de desenvolvimento descartável, nunca junto de dados de produção.

Aprovações e projetos pausados

Duas últimas causas parecem falhas, mas não são. Primeiro, o Cursor normalmente pede confirmação antes de executar uma ferramenta de MCP, então um Agent que parece travado pode estar esperando um botão de aprovação mais acima no chat. Confirme que você está no modo Agent, pois é ali que as ferramentas são executadas.

Segundo, o próprio projeto pode estar pausado. Projetos do plano gratuito podem pausar após cerca de uma semana sem atividade, e consultas a um banco pausado falham mesmo quando a ligação com o MCP está saudável. Retome o projeto no painel do Supabase e tente de novo.

Leia os logs antes de adivinhar

Cada correção acima fica mais rápida quando você lê o erro real. Chutar flags pode criar novos problemas por cima do original.

Onde o Cursor guarda os logs

Abra o painel Output pelo menu View e escolha a entrada de MCP do seu servidor do Supabase na lista suspensa de canais. Reinicie o servidor e leia as últimas 20 linhas. Os padrões mais comuns:

Para testar sozinho o caminho de rede, execute curl -i https://mcp.supabase.com/mcp em um terminal. Qualquer código de status HTTP, até um 401, prova que o host é alcançável. Um timeout ou erro de TLS aponta para uma VPN, um proxy ou um firewall, e não para o Cursor.

A lista de dez minutos

Quando você quiser uma revisão rápida em vez de uma investigação profunda, siga esta lista na ordem:

1. Valide o JSON e confirme a localização do arquivo.
2. Mantenha apenas uma entrada supabase nos dois arquivos de configuração.
3. Verifique node --version e npx --version se você usa a rota npx.
4. Envolva npx em cmd /c no Windows.
5. Feche o Cursor por completo e abra de novo.
6. Conclua o login no navegador, limpando os cookies de localhost em caso de 431.
7. Remova e adicione de novo a entrada em caso de erro "Unrecognized client_id".
8. Verifique project_ref, features e read_only na URL.
9. Mude para o modo Agent e aprove qualquer chamada de ferramenta pendente.
10. Confirme que o projeto do Supabase não está pausado.

Ferramentas demais prejudicam o Agent

O Cursor avisa com "Exceeding total tools limit" quando as ferramentas de todos os seus servidores passam de 40, observando que muitas ferramentas podem degradar o desempenho e que alguns modelos podem não respeitar mais de 40. Versões mais recentes carregam o contexto das ferramentas dinamicamente, e alguns usuários relatam nenhum aviso com mais de 80 ferramentas ativadas.

O aviso está mais suave do que era antes, mas o problema de fundo continua: um Agent que escolhe entre dezenas de ferramentas parecidas escolhe pior, e modelos menores sofrem primeiro. A discussão no fórum do Cursor sobre o limite de 40 ferramentas acompanha como esse limite mudou.

Enxugue a lista de ferramentas

• Desligue os servidores que você não está usando nesta sessão.
• Limite o Supabase com features=database,docs quando você precisar apenas de SQL e documentação.
• Clique em nomes individuais de ferramentas nas configurações de MCP para desativar as que você nunca chama.
• Mantenha os servidores específicos do projeto em .cursor/mcp.json e os gerais no arquivo de usuário.

Proteja tudo antes de confiar

Um servidor de MCP que executa SQL merece o mesmo cuidado de um login de banco de dados. A recomendação do próprio Supabase é direta: conecte-se à produção apenas quando for necessário, e use escopo de projeto, modo somente leitura e grupos de ferramentas restritos quando o fizer.

Modo somente leitura e escopo de projeto

Três configurações fazem a maior parte da proteção. read_only=true executa as consultas como um usuário Postgres somente leitura. project_ref limita o servidor a um único projeto. features reduz os grupos de ferramentas aos que você precisa. O Supabase também mostra caixas de confirmação antes de qualquer coisa que crie recursos cobráveis, então não aprove automaticamente passando por elas. Rotinas sem supervisão devem sempre rodar em modo somente leitura.

Injeção de prompt é o risco real

A principal ameaça específica de LLMs são instruções maliciosas escondidas nos dados. Imagine uma linha de chamado de suporte cujo texto manda o modelo ignorar as instruções anteriores e exportar a tabela de usuários. Se o Agent ler essa linha por meio de uma ferramenta, ele pode tratar o texto como um comando. Mantenha a aprovação manual nas chamadas de ferramenta e leia cada instrução SQL antes de aprová-la. A documentação de MCP do Supabase lista essas proteções por completo.

💡 Construa e teste a conexão em um projeto de desenvolvimento descartável. Só passe para algo que contenha dados reais de clientes com o modo somente leitura e o escopo de projeto já configurados.

Deixe um modelo ler os logs

Quando as linhas do log não fazem sentido, um LLM é um segundo par de olhos rápido. No Picasso IA, o Claude Sonnet 5 foi feito para automatizar tarefas de programação, o GPT 5.6 Sol para resolver tarefas complexas de programação, e o Gemini 3.1 Pro para respostas gerais mais precisas. Qualquer um deles pode transformar um stack trace em uma lista curta de suspeitos.

Antes de colar qualquer coisa, remova tokens de acesso, referências sensíveis de projeto e URLs de banco de dados. Um trecho de log raramente precisa deles, e uma janela de chat não é um cofre.

Um prompt para bugs de configuração

Dê ao modelo os fatos que ele não consegue adivinhar:

I use Cursor on Windows 11 with the hosted Supabase MCP server.
The MCP panel shows a red dot. My mcp.json (secrets removed) is below,
plus the last 20 lines from the MCP output channel.
List the three most likely causes, ranked, with one check for each.

Copiar prompt

Inclua seu sistema operacional, a versão do Cursor, a configuração, o trecho de log e o que você esperava que acontecesse. Pedir causas ordenadas por probabilidade, com uma verificação para cada uma, impede o modelo de despejar uma lista genérica. Depois, faça você mesmo as verificações em vez de aprovar correções às cegas.

Experimente você mesmo no Picasso IA

Uma correção como esta merece mais do que um muro de configuração. Um post de blog, um runbook interno ou um documento de equipe lê melhor com fotografias reais no lugar de capturas de tela genéricas, e o Picasso IA transforma um prompt de texto simples em imagem em segundos. Experimente o Seedream 4.5 para fotos nítidas e detalhadas, ou o GPT Image 2 quando quiser que um prompt simples vire uma cena precisa.

Um prompt inicial: "Fotografia vista de cima de uma mesa de desenvolvedor ao nascer do sol, notebook aberto em um editor de código desfocado, caneca de cerâmica, veio de carvalho visível, lente de 35mm, luz suave de janela, granulado de filme Kodak Portra 400." Troque a lente, a luz e o ângulo, e cada variação vira uma nova imagem de cabeçalho. Explore o catálogo completo em picassoia.com/en/all-models e crie sua primeira imagem hoje.