Gatekeeper

Tus agentes proponen el SQL. Tú apruebas lo que se ejecuta.

Gatekeeper es un puente con aprobación humana entre los agentes de IA y tu base de datos. Un agente propone una consulta vía MCP; por defecto, nada se ejecuta hasta que tú la apruebas en Beekeeper Studio, revisando el texto SQL antes de la ejecución. Luego la consulta se ejecuta en la conexión que Beekeeper ya tiene abierta, y las filas regresan al agente.

Solo lectura por defecto. Una escritura solo se ejecuta bajo un modo que tú mismo activas en el plugin, y ese modo es temporal. El agente nunca tiene tus credenciales de la base de datos.

Música de #Uppbeat

Shine by Swoop: https://uppbeat.io/t/swoop/shine

Consejo

Modo automático beta: activa de forma explícita la aprobación automática para un subconjunto limitado de lecturas en PostgreSQL. Tanto las verificaciones locales como Jev deben aprobarlas. Consulta Modo automático para la configuración, el uso compartido con proveedores y las limitaciones.

Las tres piezas

Pieza	Qué hace	Dónde se ejecuta
Plugin de Beekeeper Studio	Muestra cada consulta propuesta, clasifica su riesgo y la ejecuta en tu conexión cuando la apruebas	Dentro de Beekeeper Studio
Servidor MCP	El lado que ve el agente: las herramientas que llama para proponer una consulta y obtener su resultado	En tu equipo, iniciado por tu agente
Skill del agente	Enseña a cualquier agente a usar bien esas herramientas	En la carpeta de skills de tu agente

Se distribuyen juntas bajo una sola versión y son útiles juntas: el plugin sin el servidor no tiene nada que aprobar, y el servidor sin el plugin no tiene a quién preguntarle.

Por qué

• Aprobación manual por defecto. El modo automático es opcional y temporal. Se registran el origen de la aprobación y la atribución del evaluador disponible.
• Ninguna credencial de la base de datos sale de Beekeeper. Las consultas se ejecutan a través de su conexión ya autenticada. Conecta Beekeeper a una réplica de lectura o a un rol de solo lectura para tener un respaldo firme.
• El riesgo se clasifica, no se supone. Un parser que entiende cada dialecto clasifica cada consulta como lectura, escritura o destructiva, y el botón Aprobar permanece bloqueado hasta que se active el modo correspondiente.

Cómo 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     │
                                                                        └────────────────────┘

1. El agente envía una propuesta y recibe un id de solicitud de inmediato. Nada se bloquea.
2. El plugin consulta al broker local, reclama la propuesta bajo un lease y muestra el SQL.
3. Tú apruebas o rechazas. Al aprobar, Beekeeper ejecuta la consulta en tu conexión.
4. El plugin devuelve el resultado y el agente lo recoge cuando está listo.

El plugin se ejecuta en un iframe aislado, así que nunca puede recibir una conexión entrante: en su lugar, consulta al broker. Esa única restricción explica todo el diseño. Todos los detalles en Arquitectura.

Primeros pasos

Requisitos: Beekeeper Studio >= 5.4 y Node >= 22. Si usas Claude Code o Codex CLI, ya tienes Node. No hay ningún servicio en segundo plano que instalar: tu agente inicia el servidor cuando abre su sesión y este se cierra cuando la sesión termina.

Advertencia

Solo macOS, por ahora. Gatekeeper se desarrolla y prueba en macOS. Windows y Linux aún no están probados, así que considéralos sin soporte hasta que alguien reporte resultados. Nada en el código distribuido es específico de macOS (el servidor resuelve las rutas desde tu directorio personal y el plugin es un webview estándar de Beekeeper), así que se espera que ambos funcionen, pero esperar no es verificar. Los reportes de cualquiera de las dos plataformas son muy bienvenidos.

Instalación rápida

Una skill dedicada configura todo por ti: el plugin, el servidor MCP, la skill complementaria y el emparejamiento. Agrega las skills a tu agente:

npx skills add Gldywn/gatekeeper

Luego pídele a tu agente que instale Gatekeeper, o ejecuta la skill directamente:

/install-gatekeeper

Hace todos los pasos que tu entorno permite y te deja una breve lista de lo que falta, como reiniciar Beekeeper. Más adelante, /update-gatekeeper revisa las tres piezas y actualiza solo lo que esté desactualizado.

Instalación manual

¿Prefieres hacerlo a mano o quieres ver exactamente qué pasa?

Importante

Todavía no está en el registro de plugins de Beekeeper. Hay una solicitud en curso con los mantenedores de Beekeeper. Hasta que se integre, Manage Plugins no mostrará Gatekeeper y la instalación con un clic no está disponible, así que el paso 1 de abajo es la vía manual. Todo lo demás es igual.

1. Instala el plugin en Beekeeper Studio. Descarga gatekeeper-<version>.zip desde la versión más reciente, extráelo en la carpeta de plugins de Beekeeper y reinicia Beekeeper:

SO	Carpeta de plugins
macOS	~/Library/Application Support/beekeeper-studio/plugins/
Linux	~/.config/beekeeper-studio/plugins/
Windows	%APPDATA%\beekeeper-studio\plugins\

La carpeta extraída debe llamarse exactamente gatekeeper. El zip se descomprime como gatekeeper-<version>/, así que renómbrala después de extraerla. Beekeeper compara el nombre de la carpeta con el id del plugin y omite cualquier carpeta que no coincida sin decir nada: sin error, sin entrada en Manage Plugins, nada en qué hacer clic. Esta es la razón más común por la que una instalación manual parece no hacer nada.

2. Registra el servidor MCP en tu agente. Esto también instala el servidor: npx lo descarga y lo guarda en caché en el primer arranque.

# 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"]

¿Prefieres pnpm? pnpm dlx @gldywn/gatekeeper-mcp-server es el equivalente directo de la línea con npx. Para resolver el paquete una sola vez en lugar de en cada arranque del agente, instálalo con pnpm add -g @gldywn/gatekeeper-mcp-server y apunta tu cliente al binario gatekeeper-mcp-server que queda en tu PATH.

Cualquier cliente que lea .mcp.json puede usar .mcp.json.example tal cual. Fija la versión (@gldywn/gatekeeper-mcp-server@<version>) si prefieres auditar las actualizaciones en vez de recibirlas: sin fijarla, npx vuelve a resolver la versión más reciente en cada arranque del agente, lo que te mantiene al día pero significa que un proceso con acceso a tu base de datos cambia sin que te des cuenta.

3. Instala la skill del agente.

npx skills add Gldywn/gatekeeper

La CLI es interactiva: te pregunta para qué agentes instalar y si quieres instalar de forma global. Funciona con Claude Code, Codex, Cursor y los demás.

4. Empareja el plugin, una vez por equipo. Inicia tu agente y pídele cualquier cosa que necesite la base de datos. Hasta que el plugin esté emparejado, todas las herramientas de Gatekeeper responden con un código de 6 dígitos: escribe ese código en el plugin (Tools -> Gatekeeper). El código es de un solo uso y dura unos cinco minutos, y http://127.0.0.1:9999/pair siempre muestra el actual. El token de capacidad que entrega se guarda en el almacenamiento cifrado de Beekeeper.

Nada responde en ese puerto hasta que tu agente haya iniciado el servidor al menos una vez. Si abres el plugin antes, te lo indica, en lugar de mostrar un campo de emparejamiento que no puede funcionar.

5. Úsalo. Pídele a tu agente algo que necesite la base de datos. Propone SQL, la consulta aparece en el plugin, tú la apruebas y las filas regresan al agente. Las lecturas funcionan de inmediato; una escritura solo se ejecuta cuando activas el modo Write o Destructive.

Cómo compilar desde el código fuente está documentado en Desarrollo.

Si el plugin nunca aparece

Beekeeper viene con su sistema de plugins restringido, así que una instalación nueva puede ignorar por completo un plugin de terceros. Revisa tres cosas, en este orden:

1. El nombre de la carpeta. Exactamente gatekeeper, no gatekeeper-0.1.1. Si no coincide, se omite en silencio, como se explicó arriba.

2. El sistema de plugins está habilitado. Los valores predeterminados de Beekeeper establecen pluginSystem.disabled = true, con una lista de permitidos que solo contiene sus dos plugins propios. Agrega esto a tu configuración de usuario y reinicia:

[pluginSystem]
disabled = false

3. Los plugins de la comunidad están habilitados. communityDisabled = true también es un valor predeterminado, y desactiva cualquier plugin que Beekeeper marque como de la comunidad. Si el administrador de plugins muestra “Community plugins are disabled via configuration”, agrega communityDisabled = false en el mismo bloque.

SO	Archivo de configuración de usuario
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 acceso

Por defecto, cada consulta requiere que una persona haga clic sobre su texto. El modo de ejecución decide qué clases de riesgo pueden ejecutarse. El modo automático es independiente y fuerza solo lectura mientras está activo.

Modo	Aprueba	Lo activa
Read (predeterminado)	SELECT y similares	Nada que hacer
Write	INSERT, UPDATE	Tú, en el plugin, con una segunda confirmación
Destructive	DELETE, DROP, TRUNCATE, ALTER	Tú, en el plugin, con una segunda confirmación

El modo activo vive solo en memoria, nunca se guarda y vuelve a solo lectura al cambiar de conexión o al volver a emparejar. El plugin vuelve a clasificar y verificar en el momento de la ejecución, así que activar y desactivar surten efecto de inmediato.

La tarjeta lee la consulta por ti, así que decidir toma un vistazo en lugar de un análisis cuidadoso. El SQL llega formateado y resaltado, con los caracteres invisibles y los que invierten la dirección del texto mostrados como marcadores explícitos, para que lo que lees sea lo que se ejecuta. Una sentencia de escritura o destructiva lleva una insignia de color con su clase e indica su verbo y sus tablas objetivo, y una sentencia que el parser no puede leer lo indica con un texto fijo y se trata como destructiva.

Debajo del SQL, una anotación indica las tablas que lee la consulta y las columnas sensibles entre ellas: datos de personas en un color, datos de empresas y comerciales en otro, un valor sensible señalado incluso cuando solo aparece en un filtro WHERE, y un SELECT * expandido con las columnas reales para que nada se esconda detrás del asterisco. Un punto en el ícono de base de datos del encabezado muestra si pasó la última verificación de conexión, y el ícono abre los detalles: esa verificación y luego las tres capas de solo lectura (el modo activo, la conexión de Beekeeper y el endpoint de la base de datos). El robot a su lado muestra el enlace con el servidor de Gatekeeper al que tus agentes envían sus consultas. Está verde mientras el servidor responde, ámbar mientras se conecta y tachado en rojo cuando no se puede alcanzar; al pasar el cursor encima se muestra cuándo respondió el servidor por última vez.

Cada detector es un interruptor en la configuración del plugin, todos se ejecutan en tu equipo y nada de lo que detectan se envía nunca al agente. Comparan nombres de columnas y formas de valores, así que tómalos como una pista rápida de lo que merece una segunda mirada, no como prueba de que una consulta está limpia. Que no haya señales también puede significar que la anotación nunca se resolvió.

Seguridad

• El control vive donde vive la ejecución. El plugin es el único componente que puede ejecutar una consulta, así que ahí están el clasificador y la verificación del modo.
• Token de capacidad en cada solicitud. Sin él, el broker responde 401. Se genera en la primera ejecución, se guarda con permisos 0600 en ~/.gatekeeper y el plugin lo conserva en el almacenamiento cifrado de Beekeeper.
• Emparejamiento por código. El broker no puede distinguir el plugin de cualquier página web que visites, así que el token viaja por un canal que una página no puede observar: un código de 6 dígitos de un solo uso que lees con tus propios ojos, válido cinco minutos y anulado tras cinco intentos fallidos.
• Solo loopback. El broker escucha en 127.0.0.1 y rechaza encabezados Host inesperados, así que una página con DNS rebinding recibe un 421.
• Resultados limitados, auditoría mínima. Las filas enviadas se limitan por cantidad y bytes para que una lectura masiva nunca sature el contexto del agente. La auditoría del lado del agente guarda la decisión y un digest del SQL, nunca el SQL en bruto ni las filas.

Leer no garantiza cero efectos secundarios: un SELECT puede llamar a una función volátil, y justo por eso la aprobación se hace sobre el SQL visible. SECURITY.md incluye el modelo de amenazas, el límite de confianza del mismo usuario, los periodos de retención y la política de cadena de suministro.

Documentación

Documento	Qué contiene
Arquitectura	Los dos canales, el ciclo de aprobación, la cola de leases, los límites de resultados
Herramientas MCP	Cada herramienta que un agente puede llamar, la forma del ticket, el contrato de espera
Configuración	Variables de entorno y notificaciones de escritorio
Seguridad	Modelo de amenazas, límite de confianza, retención, cadena de suministro
Desarrollo	Compilar desde el código fuente, configuración de desarrollo, estructura del repo, stack tecnológico
Publicación	Cómo un commit se convierte en una versión del plugin y en un paquete npm

Desarrollo

pnpm install
pnpm build     # both packages
pnpm ci        # typecheck + build + test

pnpm dev:link apunta Beekeeper a tu copia local y pnpm dev inicia la interfaz del plugin con recarga en caliente. La configuración completa, incluidas las bases de datos de prueba, está en Desarrollo.

Licencia

MIT