Gatekeeper
Seus agentes propõem o SQL. Você aprova o que roda.
O Gatekeeper é uma ponte aprovada por humanos entre agentes de IA e o seu banco de dados. Um agente propõe uma consulta via MCP; por padrão, nada roda até você aprovar no Beekeeper Studio, com base no texto SQL, antes da execução. A consulta então roda na conexão que o Beekeeper já mantém, e as linhas retornam ao agente.
Somente leitura por padrão. Uma escrita só roda em um modo que você mesmo ativa no plugin, e esse modo é efêmero. O agente nunca tem acesso às credenciais do seu banco de dados.
Música de #Uppbeat
Shine por Swoop: https://uppbeat.io/t/swoop/shineDica
Modo automático beta: ative explicitamente a aprovação automática para um subconjunto restrito de leituras no PostgreSQL. As verificações locais e o Jev precisam passar. Veja Modo automático para configuração, compartilhamento com provedores e limitações.
As três partes
| Parte | O que faz | Onde roda |
|---|---|---|
| Plugin do Beekeeper Studio | Mostra cada consulta proposta, classifica seu risco e a executa na sua conexão quando você aprova | Dentro do Beekeeper Studio |
| Servidor MCP | O lado voltado ao agente: as ferramentas que um agente chama para propor uma consulta e obter o resultado | Na sua máquina, iniciado pelo seu agente |
| Skill do agente | Ensina qualquer agente a usar bem essas ferramentas | Na pasta de skills do seu agente |
Elas são distribuídas juntas sob uma única versão e só fazem sentido juntas: o plugin sem o servidor não tem nada para aprovar, e o servidor sem o plugin não tem a quem perguntar.
Por quê
- Aprovação manual por padrão. O modo automático é opcional e efêmero. A origem da aprovação e a atribuição do avaliador disponível são registradas.
- Nenhuma credencial do banco sai do Beekeeper. As consultas rodam pela conexão já autenticada dele. Aponte o Beekeeper para uma réplica de leitura ou um role somente leitura para ter uma proteção extra.
- O risco é classificado, não presumido. Um parser que entende o dialeto classifica cada consulta como leitura, escrita ou destrutiva, e o botão Aprovar fica bloqueado até o modo correspondente ser ativado.
Como funciona
MCP client Gatekeeper server (127.0.0.1) Beekeeper Studio
┌────────────────────┐ MCP ┌───────────────────────────┐ fetch ┌────────────────────┐
│ submit_query(sql) │ ───────► │ MCP server + HTTP broker │ ◄─────── │ Plugin (iframe) │
│ get_query_result() │ ◄─────── │ SQLite lease queue + audit│ poll │ 1. show SQL │
│ cancel_query() │ │ /pending /executing │ ───────► │ 2. human approves │
│ │ │ /result /lease/renew │ result │ 3. runQuery() │
└────────────────────┘ └───────────────────────────┘ │ 4. post result │
└────────────────────┘
- O agente envia uma proposta e recebe imediatamente um id de requisição. Nada fica bloqueado.
- O plugin consulta o broker local, reivindica a proposta sob um lease e exibe o SQL.
- Você aprova ou rejeita. Na aprovação, o Beekeeper roda a consulta na sua conexão.
- O plugin envia o resultado de volta, e o agente o coleta quando estiver pronto.
O plugin roda em um iframe isolado, então nunca pode receber uma conexão de entrada: em vez disso, ele consulta o broker. Essa única restrição explica todo o formato. Detalhes completos em Arquitetura.
Primeiros passos
Pré-requisitos: Beekeeper Studio >= 5.4 e Node >= 22. Se você usa Claude Code ou Codex CLI, já tem o Node. Não há serviço em segundo plano para instalar: seu agente inicia o servidor quando a sessão abre, e ele encerra quando a sessão termina.
Aviso
Somente macOS, por enquanto. O Gatekeeper é desenvolvido e testado no macOS. Windows e Linux ainda não foram testados, então considere-os sem suporte até que alguém dê um retorno. Nada no código distribuído é específico do macOS (o servidor resolve caminhos a partir do seu diretório home, o plugin é um webview padrão do Beekeeper), então ambos devem funcionar, mas esperado não é verificado. Relatos de qualquer uma das plataformas são muito bem-vindos.
Instalação rápida
Uma skill dedicada configura tudo para você: o plugin, o servidor MCP, a skill complementar e o pareamento. Adicione as skills ao seu agente:
npx skills add Gldywn/gatekeeper
Depois peça ao seu agente para instalar o Gatekeeper, ou execute a skill diretamente:
/install-gatekeeper
Ela faz todas as etapas que o seu ambiente permite e entrega uma lista curta para o resto, como reiniciar o Beekeeper. Depois, /update-gatekeeper verifica as três partes e atualiza só o que estiver desatualizado.
Instalação manual
Prefere fazer à mão ou quer ver exatamente o que acontece?
Importante
Ainda não está no registro de plugins do Beekeeper. Uma submissão está em andamento com os mantenedores do Beekeeper. Até ser aceita, o Manage Plugins não listará o Gatekeeper e a instalação com um clique não estará disponível, então o passo 1 abaixo é o caminho manual. Nada mais muda.
1. Instale o plugin no Beekeeper Studio. Baixe gatekeeper-<version>.zip da versão mais recente, extraia na pasta de plugins do Beekeeper e reinicie o Beekeeper:
| SO | Pasta de plugins |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/plugins/ |
| Linux | ~/.config/beekeeper-studio/plugins/ |
| Windows | %APPDATA%\beekeeper-studio\plugins\ |
A pasta extraída precisa se chamar exatamente
gatekeeper. O zip é extraído comogatekeeper-<version>/, então renomeie depois de extrair. O Beekeeper compara o nome da pasta com o id do plugin e ignora qualquer pasta diferente sem dizer nada: nenhum erro, nenhuma entrada no Manage Plugins, nada para clicar. Esse é o motivo mais comum para uma instalação manual parecer não fazer nada.
2. Registre o servidor MCP no seu agente. Isso também instala o servidor: o npx o baixa e guarda em cache na primeira execução.
# Claude Code
claude mcp add gatekeeper --scope user -- npx -y @gldywn/gatekeeper-mcp-server
# Codex CLI, in ~/.codex/config.toml
[mcp_servers.gatekeeper]
command = "npx"
args = ["-y", "@gldywn/gatekeeper-mcp-server"]
Prefere pnpm? pnpm dlx @gldywn/gatekeeper-mcp-server é o equivalente direto da linha com npx. Para resolver o pacote uma vez em vez de a cada inicialização do agente, instale com pnpm add -g @gldywn/gatekeeper-mcp-server e aponte seu cliente para o binário gatekeeper-mcp-server que ele coloca no seu PATH.
Qualquer cliente que leia .mcp.json pode usar .mcp.json.example como está. Fixe a versão (@gldywn/gatekeeper-mcp-server@<version>) se preferir auditar as atualizações em vez de recebê-las: sem fixar, o npx resolve novamente a versão mais recente a cada inicialização do agente, o que mantém você atualizado, mas significa que um processo com acesso ao seu banco de dados muda sem você perceber.
3. Instale a skill do agente.
npx skills add Gldywn/gatekeeper
A CLI é interativa: ela pergunta para quais agentes instalar e se a instalação deve ser global. Funciona com Claude Code, Codex, Cursor e os demais.
4. Pareie o plugin, uma vez por máquina. Inicie seu agente e peça qualquer coisa que precise do banco de dados. Até o plugin ser pareado, toda ferramenta do Gatekeeper responde com um código de 6 dígitos: digite esse código no plugin (Tools -> Gatekeeper). O código é de uso único e dura cerca de cinco minutos, e http://127.0.0.1:9999/pair sempre mostra o atual. O token de capacidade entregue é guardado no armazenamento criptografado do Beekeeper.
Nada responde nessa porta até seu agente ter iniciado o servidor pelo menos uma vez. Se você abrir o plugin antes disso, ele avisa, em vez de mostrar um campo de pareamento que não pode atender.
5. Use. Peça ao seu agente algo que precise do banco de dados. Ele propõe o SQL, a consulta aparece no plugin, você aprova e as linhas retornam ao agente. Leituras funcionam de imediato; uma escrita só roda depois que você ativa o modo Write ou Destructive.
A compilação a partir do código-fonte está documentada em Desenvolvimento.
Se o plugin nunca aparecer
O Beekeeper vem com o sistema de plugins bloqueado, então uma instalação nova pode ignorar completamente um plugin de terceiros. Três coisas para verificar, nesta ordem:
1. O nome da pasta. Exatamente gatekeeper, não gatekeeper-0.1.1. Uma divergência é ignorada silenciosamente, como explicado acima.
2. O sistema de plugins está ativado. Os padrões do Beekeeper definem pluginSystem.disabled = true, com uma allowlist que contém apenas seus próprios dois plugins. Adicione isto à sua configuração de usuário e reinicie:
[pluginSystem]
disabled = false
3. Os plugins da comunidade estão ativados. communityDisabled = true também é um padrão, e desativa qualquer plugin que o Beekeeper liste como da comunidade. Se o gerenciador de plugins mostrar “Community plugins are disabled via configuration”, adicione communityDisabled = false no mesmo bloco.
| SO | Arquivo de configuração do usuário |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/user.config.ini |
| Linux | ~/.config/beekeeper-studio/user.config.ini |
| Windows | %APPDATA%\beekeeper-studio\user.config.ini |
Modos de acesso
Por padrão, toda consulta exige um clique humano sobre o seu texto. O modo de execução define quais classes de risco podem rodar. O modo automático é separado e força somente leitura enquanto estiver ativo.
| Modo | Aprova | Ativado por |
|---|---|---|
| Read (padrão) | SELECT e similares |
Nada a fazer |
| Write | INSERT, UPDATE |
Você, no plugin, com uma segunda confirmação |
| Destructive | DELETE, DROP, TRUNCATE, ALTER |
Você, no plugin, com uma segunda confirmação |
O modo ativado fica apenas em memória, nunca é persistido, e volta para somente leitura ao trocar de conexão ou parear novamente. O plugin reclassifica e verifica de novo no momento da execução, então ativar e desativar têm efeito imediato.
O card lê a consulta para você, então decidir leva uma olhada em vez de uma análise cuidadosa. O SQL chega formatado e destacado, com caracteres invisíveis e que invertem a direção exibidos como marcadores explícitos, para que o que você lê seja o que roda. Uma instrução de escrita ou destrutiva traz um selo colorido de classe e indica seu verbo e as tabelas-alvo, e uma instrução que o parser não consegue ler informa isso em texto fixo e é tratada como destrutiva.
Abaixo do SQL, uma anotação indica as tabelas que a consulta lê e as colunas sensíveis entre elas: dados pessoais em uma cor, dados de empresas e comerciais em outra, um valor sensível sinalizado mesmo quando aparece só em um filtro WHERE, e um SELECT * expandido com as colunas reais para que nada se esconda atrás do asterisco. Um ponto no ícone de banco de dados do cabeçalho mostra se a última verificação de conexão passou, e o ícone abre os detalhes: essa verificação e depois as três camadas de somente leitura (o modo ativado, a conexão do Beekeeper e o endpoint do banco). O robô ao lado mostra a ligação com o servidor do Gatekeeper para o qual seus agentes enviam as consultas. Ele fica verde enquanto o servidor responde, âmbar durante a conexão e riscado em vermelho quando inacessível, e ao passar o mouse mostra quando o servidor respondeu pela última vez.
Cada detector é uma opção nas configurações do plugin, todos rodam na sua máquina e nada do que encontram é enviado ao agente. Eles comparam nomes de colunas e formatos de valores, então trate-os como um indicador rápido do que merece uma segunda olhada, não como prova de que uma consulta é segura. A ausência de sinalizações também pode significar que a anotação nunca foi resolvida.
Segurança
- A barreira fica onde a execução acontece. O plugin é o único componente que pode rodar uma consulta, por isso é ali que ficam o classificador e a verificação de modo.
- Token de capacidade em toda requisição. Sem ele, o broker responde
401. Ele é gerado na primeira execução, armazenado com0600em~/.gatekeepere mantido pelo plugin no armazenamento criptografado do Beekeeper. - Pareamento por código. O broker não consegue distinguir o plugin de qualquer página web que você visite, então o token passa por um canal que uma página não pode observar: um código de 6 dígitos de uso único que você lê com seus próprios olhos, válido por cinco minutos e invalidado após cinco tentativas erradas.
- Apenas loopback. O broker escuta em
127.0.0.1e rejeita cabeçalhosHostinesperados, então uma página com DNS rebinding recebe um421. - Resultados limitados, auditoria mínima. As linhas encaminhadas são limitadas por quantidade e bytes, para que uma leitura em massa nunca inunde o contexto do agente. A auditoria voltada ao agente guarda a decisão e um digest do SQL, nunca o SQL bruto nem as linhas.
Leitura não garante zero efeitos colaterais: um SELECT pode chamar uma função volátil, e é exatamente por isso que a aprovação acontece sobre o SQL visível. SECURITY.md traz o modelo de ameaças, o limite de confiança do mesmo usuário, os períodos de retenção e a política de cadeia de suprimentos.
Documentação
| Documento | Conteúdo |
|---|---|
| Arquitetura | Os dois canais, o ciclo de aprovação, a fila de leases, limites de resultados |
| Ferramentas MCP | Cada ferramenta que um agente pode chamar, o formato do ticket, o contrato de espera |
| Configuração | Variáveis de ambiente e notificações na área de trabalho |
| Segurança | Modelo de ameaças, limite de confiança, retenção, cadeia de suprimentos |
| Desenvolvimento | Compilar do código-fonte, configuração de dev, estrutura do repositório, stack |
| Releases | Como um commit vira uma release do plugin e um pacote npm |
Desenvolvimento
pnpm install
pnpm build # both packages
pnpm ci # typecheck + build + test
pnpm dev:link aponta o Beekeeper para o seu checkout e pnpm dev inicia a UI do plugin com hot reload. A configuração completa, incluindo os bancos de teste, está em Desenvolvimento.