Gatekeeper
SQL은 에이전트가 제안하고, 실행은 여러분이 승인해요.
Gatekeeper는 AI 에이전트와 데이터베이스 사이를 사람의 승인으로 잇는 다리예요. 에이전트가 MCP로 쿼리를 제안하면, 기본적으로 여러분이 Beekeeper Studio에서 실행 전에 SQL 텍스트를 보고 승인할 때까지 아무것도 실행되지 않아요. 승인된 쿼리는 Beekeeper가 이미 가진 연결에서 실행되고, 결과 행이 에이전트에 돌아가요.
기본값은 읽기 전용이에요. 쓰기는 플러그인에서 직접 활성화한 모드에서만 실행되며, 그 모드는 일시적이에요. 에이전트는 데이터베이스 자격 증명을 절대 갖지 않아요.
음악: #Uppbeat
Shine by Swoop: https://uppbeat.io/t/swoop/shine팁
자동 모드 베타: 제한된 PostgreSQL 읽기 쿼리에 대해 자동 승인을 명시적으로 켤 수 있어요. 로컬 검사와 Jev를 모두 통과해야 해요. 설정, 제공자 공유, 제한 사항은 자동 모드를 참고하세요.
세 가지 구성 요소
| 구성 요소 | 하는 일 | 실행 위치 |
|---|---|---|
| Beekeeper Studio 플러그인 | 제안된 쿼리를 보여주고 위험도를 분류하며, 승인하면 여러분의 연결에서 실행해요 | Beekeeper Studio 내부 |
| MCP 서버 | 에이전트 쪽 인터페이스: 에이전트가 쿼리를 제안하고 결과를 받을 때 호출하는 도구 | 내 컴퓨터에서, 에이전트가 시작 |
| 에이전트 스킬 | 어떤 에이전트든 이 도구를 잘 다루도록 가르쳐요 | 에이전트의 스킬 폴더 |
세 가지는 하나의 버전으로 함께 배포되고, 함께 써야 의미가 있어요. 서버 없는 플러그인은 승인할 것이 없고, 플러그인 없는 서버는 물어볼 사람이 없어요.
왜 필요한가요
- 기본은 수동 승인이에요. 자동 모드는 선택 사항이며 일시적이에요. 승인 출처와 가능한 평가자 정보가 기록돼요.
- 데이터베이스 자격 증명이 Beekeeper 밖으로 나가지 않아요. 쿼리는 이미 인증된 연결을 통해 실행돼요. 확실한 안전장치가 필요하면 Beekeeper를 읽기 전용 복제본이나 읽기 전용 역할에 연결하세요.
- 위험도는 추정이 아니라 분류돼요. 방언을 인식하는 파서가 각 쿼리를 읽기, 쓰기, 파괴적 작업으로 분류하고, 해당 모드가 활성화될 때까지 승인 버튼은 막혀 있어요.
작동 방식
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 │
└────────────────────┘
- 에이전트가 제안을 제출하면 즉시 요청 id를 받아요. 아무것도 블로킹되지 않아요.
- 플러그인이 로컬 브로커를 폴링하고, 리스(lease)로 제안을 가져와 SQL을 표시해요.
- 승인하거나 거부하세요. 승인하면 Beekeeper가 여러분의 연결에서 쿼리를 실행해요.
- 플러그인이 결과를 다시 보내고, 준비되면 에이전트가 가져가요.
플러그인은 샌드박스된 iframe에서 실행되므로 들어오는 연결을 받을 수 없어요. 그래서 대신 브로커를 폴링해요. 이 하나의 제약이 전체 구조를 설명해요. 자세한 내용은 아키텍처를 참고하세요.
시작하기
사전 요구 사항: Beekeeper Studio >= 5.4, Node >= 22. Claude Code나 Codex CLI를 쓰고 있다면 Node는 이미 있어요. 설치할 백그라운드 서비스는 없어요. 에이전트가 세션을 열 때 서버를 시작하고, 세션이 끝나면 서버도 종료돼요.
경고
현재는 macOS 전용이에요. Gatekeeper는 macOS에서 개발 및 테스트되었어요. Windows와 Linux는 아직 테스트되지 않았으니 누군가 확인해 줄 때까지 지원되지 않는 것으로 간주하세요. 배포된 코드에 macOS 전용 부분은 없으므로(서버는 홈 디렉터리 기준으로 경로를 찾고, 플러그인은 표준 Beekeeper 웹뷰예요) 두 플랫폼 모두 작동할 것으로 예상되지만, 예상이 검증은 아니에요. 두 플랫폼의 사용 보고를 언제든 환영해요.
빠른 설치
전용 스킬이 플러그인, MCP 서버, 동반 스킬, 페어링까지 모두 설정해 줘요. 에이전트에 스킬을 추가하세요:
npx skills add Gldywn/gatekeeper
그런 다음 에이전트에게 Gatekeeper 설치를 요청하거나 스킬을 직접 실행하세요:
/install-gatekeeper
환경이 허용하는 모든 단계를 수행하고, Beekeeper 재시작처럼 남은 작업은 짧은 체크리스트로 알려줘요. 나중에 /update-gatekeeper를 실행하면 세 구성 요소를 모두 확인하고 뒤처진 것만 업데이트해요.
수동 설치
직접 설치하고 싶거나, 어떤 일이 일어나는지 정확히 보고 싶으신가요?
중요
아직 Beekeeper 플러그인 레지스트리에 없어요. Beekeeper 메인테이너와 등록 절차가 진행 중이에요. 병합되기 전까지는 플러그인 관리에 Gatekeeper가 표시되지 않고 원클릭 설치도 불가능하므로, 아래 1단계가 수동 설치 방법이에요. 그 외에는 다른 점이 없어요.
1. Beekeeper Studio에 플러그인을 설치하세요. 최신 릴리스에서 gatekeeper-<version>.zip을 다운로드해 Beekeeper 플러그인 폴더에 압축을 풀고, Beekeeper를 재시작하세요:
| OS | 플러그인 폴더 |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/plugins/ |
| Linux | ~/.config/beekeeper-studio/plugins/ |
| Windows | %APPDATA%\beekeeper-studio\plugins\ |
압축을 푼 폴더 이름은 정확히
gatekeeper여야 해요. zip을 풀면gatekeeper-<version>/이 생기므로 압축을 푼 뒤 이름을 바꾸세요. Beekeeper는 폴더 이름을 플러그인 id와 비교하고 일치하지 않는 폴더는 아무 말 없이 건너뛰어요. 오류도, 플러그인 관리 항목도, 클릭할 것도 없어요. 수동 설치가 아무 효과 없어 보이는 가장 흔한 이유예요.
2. 에이전트에 MCP 서버를 등록하세요. 이것이 곧 서버 설치이기도 해요. npx가 첫 실행 시 다운로드하고 캐시해요.
# 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"]
pnpm을 선호하시나요? pnpm dlx @gldywn/gatekeeper-mcp-server가 npx 명령과 동일해요. 에이전트를 실행할 때마다가 아니라 한 번만 패키지를 받으려면 pnpm add -g @gldywn/gatekeeper-mcp-server로 설치하고, PATH에 추가되는 gatekeeper-mcp-server 바이너리를 클라이언트에 지정하세요.
.mcp.json을 읽는 클라이언트라면 .mcp.json.example을 그대로 쓸 수 있어요. 업그레이드를 자동으로 받기보다 직접 검토하고 싶다면 버전을 고정하세요(@gldywn/gatekeeper-mcp-server@<version>). 고정하지 않으면 npx가 에이전트를 실행할 때마다 최신 릴리스를 다시 가져와요. 항상 최신 상태가 유지되지만, 데이터베이스에 접근할 수 있는 프로세스가 모르는 사이에 바뀐다는 뜻이기도 해요.
3. 에이전트 스킬을 설치하세요.
npx skills add Gldywn/gatekeeper
CLI는 대화형이에요. 어떤 에이전트에 설치할지, 전역으로 설치할지 물어봐요. Claude Code, Codex, Cursor 등 여러 에이전트에서 작동해요.
4. 플러그인을 페어링하세요(컴퓨터당 한 번). 에이전트를 시작하고 데이터베이스가 필요한 작업을 요청하세요. 플러그인이 페어링되기 전까지 모든 Gatekeeper 도구는 6자리 코드로 응답해요. 그 코드를 플러그인(Tools -> Gatekeeper)에 입력하세요. 코드는 일회용이며 약 5분간 유효하고, http://127.0.0.1:9999/pair에서 항상 현재 코드를 확인할 수 있어요. 전달받은 capability 토큰은 Beekeeper의 암호화된 저장소에 보관돼요.
에이전트가 서버를 한 번 이상 시작하기 전에는 해당 포트에서 아무것도 응답하지 않아요. 그 전에 플러그인을 열면 사용할 수 없는 페어링 입력란 대신 그 사실을 알려줘요.
5. 사용하세요. 데이터베이스가 필요한 작업을 에이전트에 요청하세요. 에이전트가 SQL을 제안하면 쿼리가 플러그인에 나타나고, 승인하면 결과 행이 에이전트에 돌아가요. 읽기는 바로 작동하고, 쓰기는 Write 또는 Destructive 모드를 활성화해야만 실행돼요.
소스에서 빌드하는 방법은 개발 문서에 있어요.
플러그인이 나타나지 않는다면
Beekeeper는 플러그인 시스템이 잠긴 상태로 배포되므로, 새로 설치한 경우 서드파티 플러그인을 완전히 무시할 수 있어요. 다음 세 가지를 순서대로 확인하세요:
1. 폴더 이름. gatekeeper-0.1.1이 아니라 정확히 gatekeeper여야 해요. 위에서 설명했듯 불일치하면 조용히 건너뛰어요.
2. 플러그인 시스템 활성화. Beekeeper 기본 설정은 pluginSystem.disabled = true이고, 허용 목록에는 자체 플러그인 2개만 들어 있어요. 사용자 설정에 다음을 추가하고 재시작하세요:
[pluginSystem]
disabled = false
3. 커뮤니티 플러그인 활성화. communityDisabled = true도 기본 설정이며, Beekeeper가 커뮤니티로 분류한 플러그인을 모두 비활성화해요. 플러그인 관리자에 “Community plugins are disabled via configuration”이 표시되면 같은 블록에 communityDisabled = false를 추가하세요.
| OS | 사용자 설정 파일 |
|---|---|
| macOS | ~/Library/Application Support/beekeeper-studio/user.config.ini |
| Linux | ~/.config/beekeeper-studio/user.config.ini |
| Windows | %APPDATA%\beekeeper-studio\user.config.ini |
접근 모드
기본적으로 모든 쿼리는 사람이 텍스트를 보고 클릭해야 실행돼요. 실행 모드는 어떤 위험 등급을 실행할 수 있는지 결정해요. 자동 모드는 별개이며, 켜져 있는 동안 읽기 전용을 강제해요.
| 모드 | 승인 대상 | 활성화 주체 |
|---|---|---|
| Read (기본값) | SELECT 등 |
할 일 없음 |
| Write | INSERT, UPDATE |
플러그인에서 직접, 2차 확인 후 |
| Destructive | DELETE, DROP, TRUNCATE, ALTER |
플러그인에서 직접, 2차 확인 후 |
활성화된 모드는 메모리에만 있고 저장되지 않으며, 연결을 전환하거나 다시 페어링하면 읽기 전용으로 초기화돼요. 플러그인은 실행 시점에 다시 분류하고 확인하므로, 활성화와 비활성화가 즉시 적용돼요.
카드가 쿼리를 대신 읽어줘요. 꼼꼼히 분석할 필요 없이 한눈에 판단할 수 있어요. SQL은 서식과 하이라이트가 적용되어 표시되고, 보이지 않는 문자나 방향을 뒤집는 문자는 명시적인 표시로 나타나서 보이는 그대로 실행돼요. 쓰기나 파괴적 구문에는 색상 등급 배지와 함께 동사와 대상 테이블이 표시되고, 파서가 읽지 못한 구문은 그 사실을 고정 텍스트로 알리며 파괴적 작업으로 취급돼요.
SQL 아래의 주석에는 쿼리가 읽는 테이블과 그중 민감한 컬럼이 표시돼요. 개인 데이터와 회사·상업 데이터는 서로 다른 색으로 강조되고, 민감한 값은 WHERE 필터에만 나타나도 표시되며, SELECT *는 실제 컬럼으로 펼쳐져 별표 뒤에 숨는 것이 없어요. 헤더의 데이터베이스 아이콘에 있는 점은 마지막 연결 확인 통과 여부를 보여주고, 아이콘을 열면 그 확인 결과와 세 가지 읽기 전용 계층(활성화된 모드, Beekeeper 연결, 데이터베이스 엔드포인트)을 볼 수 있어요. 옆의 로봇 아이콘은 에이전트가 쿼리를 보내는 Gatekeeper 서버와의 연결 상태를 보여줘요. 서버가 응답하면 초록색, 연결 중이면 주황색, 연결할 수 없으면 빨간색 X로 표시되고, 마우스를 올리면 서버가 마지막으로 응답한 시간이 나와요.
각 탐지기는 플러그인 설정에서 켜고 끌 수 있고, 모두 내 컴퓨터에서 실행되며, 탐지된 내용은 절대 에이전트로 전송되지 않아요. 컬럼 이름과 값의 형태로 판단하므로, 쿼리가 안전하다는 증거가 아니라 다시 살펴볼 부분을 빠르게 짚어주는 용도로 생각하세요. 표시가 없다는 것은 주석 분석이 완료되지 않았다는 뜻일 수도 있어요.
보안
- 관문은 실행이 일어나는 곳에 있어요. 쿼리를 실행할 수 있는 유일한 구성 요소가 플러그인이므로, 분류기와 모드 확인도 그곳에 있어요.
- 모든 요청에 capability 토큰을 사용해요. 토큰이 없으면 브로커는
401로 응답해요. 토큰은 첫 실행 시 생성되어~/.gatekeeper아래에0600권한으로 저장되고, 플러그인은 이를 Beekeeper의 암호화된 저장소에 보관해요. - 코드로 페어링해요. 브로커는 플러그인과 여러분이 방문하는 웹 페이지를 구별할 수 없으므로, 토큰은 웹 페이지가 관찰할 수 없는 채널로 전달돼요. 직접 눈으로 읽는 일회용 6자리 코드로, 5분간 유효하며 5번 틀리면 폐기돼요.
- 루프백 전용이에요. 브로커는
127.0.0.1에만 바인딩되고 예상치 못한Host헤더를 거부하므로, DNS 리바인딩 페이지는421을 받아요. - 결과 제한, 최소한의 감사 기록. 전달되는 행은 개수와 바이트로 제한되어 대량 읽기가 에이전트 컨텍스트를 넘치게 하지 않아요. 에이전트 쪽 감사 기록에는 결정과 SQL 다이제스트만 남고, 원본 SQL이나 행은 절대 남지 않아요.
읽기가 부작용이 전혀 없다는 보장은 아니에요. SELECT도 volatile 함수를 호출할 수 있기 때문에, 바로 그 이유로 눈에 보이는 SQL을 보고 승인하는 거예요. 위협 모델, 동일 사용자 신뢰 경계, 보존 기간, 공급망 정책은 SECURITY.md에 있어요.
문서
| 문서 | 내용 |
|---|---|
| 아키텍처 | 두 채널, 승인 루프, 리스 큐, 결과 제한 |
| MCP 도구 | 에이전트가 호출할 수 있는 모든 도구, 티켓 구조, 대기 규약 |
| 설정 | 환경 변수와 데스크톱 알림 |
| 보안 | 위협 모델, 신뢰 경계, 보존, 공급망 |
| 개발 | 소스에서 빌드, 개발 환경 연결, 저장소 구조, 기술 스택 |
| 릴리스 | 커밋이 플러그인 릴리스와 npm 패키지가 되는 과정 |
개발
pnpm install
pnpm build # both packages
pnpm ci # typecheck + build + test
pnpm dev:link는 Beekeeper가 내 체크아웃을 사용하도록 연결하고, pnpm dev는 핫 리로드로 플러그인 UI를 시작해요. 테스트 데이터베이스를 포함한 전체 설정은 개발 문서에 있어요.