1. 소개
Antigravity CLI와 같은 AI 에이전트에 데이터베이스에 대한 안전하고 구조화된 액세스 권한을 부여하려면 AlloyDB Omni를 데이터베이스용 MCP 도구 상자와 통합하면 됩니다.
AlloyDB Omni는 다운로드 가능한 컨테이너화된 PostgreSQL용 AlloyDB 버전으로, 온프레미스, 개발자 워크스테이션, 에지, 클라우드 등 어디서나 실행되도록 설계되었으며 엔터프라이즈급 PostgreSQL 성능과 호환성을 제공합니다.
데이터베이스용 MCP 도구 상자는 데이터베이스와 상호작용하는 생성형 AI 도구를 더 쉽고 빠르고 안전하게 빌드할 수 있도록 Model Context Protocol(MCP)을 구현하는 Google의 오픈소스 서버입니다. 에이전트의 조정 프레임워크와 데이터베이스 사이에 위치하며 다음 기능을 제공합니다.
- 개발 간소화: 최소한의 구성으로 에이전트에 연결하고 여러 에이전트 또는 프레임워크에서 재사용할 수 있는 사전 빌드된 데이터베이스 도구 또는 커스텀 데이터베이스 도구입니다.
- 성능 개선: 연결 풀링 및 수명 주기 관리와 같은 기본 제공 권장사항을 활용합니다.
- 보안 강화: 사용자 인증 정보 및 인증 관리가 중앙 집중화되어 에이전트에 원시 데이터베이스 사용자 인증 정보가 필요하지 않습니다.
- 엔드 투 엔드 모니터링 가능성: OpenTelemetry를 기본적으로 지원하는 즉시 사용 가능한 측정항목 및 추적
이 Codelab을 마치면 샘플 전자상거래 데이터가 채워진 실행 중인 AlloyDB Omni 컨테이너, 사전 빌드된 AlloyDB Omni 관리 및 쿼리 도구 31개를 노출하는 MCP 도구 상자 서버, 자연어 프롬프트를 사용하여 스키마를 검사하고, SQL 쿼리를 실행하고, 쿼리 계획을 분석하고, 데이터베이스 상태를 진단할 수 있는 구성된 Antigravity CLI(agy) 에이전트가 생성됩니다.
기본 요건
- Google Cloud 콘솔 또는 Linux 워크스테이션에서 Google Cloud 프로젝트 및 Cloud Shell에 액세스할 수 있어야 합니다.
- Docker가 설치되어 실행 중이어야 합니다.
psqlPostgreSQL 클라이언트가 설치되었습니다.- Antigravity CLI 및 MCP 도구 상자를 설정하기 위해
curl및jq가 설치되어 있어야 합니다.
학습할 내용
- Docker를 사용하여 AlloyDB Omni 데이터베이스 서버 컨테이너를 배포하고 실행하는 방법
- AlloyDB Omni에서 샘플 테이블, 데이터, 색인을 만드는 방법
- 사전 빌드된
alloydb-omni도구 모음을 사용하여 데이터베이스용 MCP 도구 상자를 다운로드, 구성, 시작하는 방법 - Antigravity CLI를 MCP 클라이언트로 구성하여 MCP 도구 상자 서버에 연결하는 방법
- Antigravity CLI에서 자연어 프롬프트를 사용하여 데이터베이스 상태를 검사하고, 스키마를 탐색하고, SQL 쿼리를 실행하고, 쿼리 계획을 분석하고, 유지보수 진단을 수행하는 방법
필요한 항목
- Docker,
psql,curl,jq가 있는 작업 터미널 환경 이러한 도구가 사전 설치된 Google Cloud Shell을 사용할 수 있습니다.
2. 설정 및 요건
프로젝트 설정
Google Cloud 프로젝트 만들기
- Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
- Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.
Cloud Shell 시작
노트북에서 AlloyDB Omni 및 MCP 도구 상자를 로컬로 실행할 수 있지만, 이 Codelab에서는 Docker, psql, curl, jq가 사전 설치된 클라우드에서 실행되는 명령줄 환경인 Google Cloud Shell을 사용할 수 있습니다.
- Google Cloud 콘솔을 열고 오른쪽 상단 툴바에서 Cloud Shell 활성화를 클릭합니다. 다음 방법 중 하나를 사용하여 Cloud Shell을 열 수도 있습니다.
- Google Cloud 콘솔을 사용하는 경우
G를 누른 다음S를 누릅니다. - Cloud Shell을 직접 엽니다.
- Google Cloud 콘솔을 사용하는 경우
환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 이 작업이 완료되면 다음과 비슷한 결과가 표시됩니다.
3. AlloyDB Omni 데이터베이스 서버 준비 및 실행
이 섹션에서는 AlloyDB Omni Docker 컨테이너를 가져와 실행하고 테스트를 위해 샘플 이커머스 데이터를 채웁니다.
AlloyDB Omni 데이터베이스 서버 시작
- AlloyDB Omni 호스트, 포트, 데이터베이스, 사용자, 생성된 비밀번호의 환경 변수를 정의합니다.
export ALLOYDB_OMNI_HOST="127.0.0.1" export ALLOYDB_OMNI_PORT="5432" export ALLOYDB_OMNI_DATABASE="postgres" export ALLOYDB_OMNI_USER="postgres" export ALLOYDB_OMNI_PASSWORD="$(openssl rand -hex 8)@1aA" echo "Your generated AlloyDB Omni postgres password is: $ALLOYDB_OMNI_PASSWORD" - Docker를 사용하여 분리 모드에서 AlloyDB Omni 컨테이너를 시작합니다.
docker run --name alloydbomni \ -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \ -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \ -d google/alloydbomni:latest - 컨테이너가 실행 중이고
psql을 사용하여 AlloyDB Omni 서버에 연결할 수 있는지 확인합니다.docker ps -a until docker exec alloydbomni pg_isready -U "$ALLOYDB_OMNI_USER" -d "$ALLOYDB_OMNI_DATABASE"; do sleep 2; done PGPASSWORD=$ALLOYDB_OMNI_PASSWORD psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE -c "SELECT 1;"
테스트용 샘플 데이터 만들기
MCP 도구 상자를 통해 스키마 검사, SQL 쿼리, 쿼리 실행 계획을 테스트할 수 있도록 샘플 categories, products, customers, orders 테이블을 만들고, 테스트 레코드를 삽입하고, 색인을 만듭니다.
PGPASSWORD="$ALLOYDB_OMNI_PASSWORD" psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE << 'EOF'
CREATE TABLE IF NOT EXISTS categories (
category_id SERIAL PRIMARY KEY,
name VARCHAR(50) UNIQUE NOT NULL
);
CREATE TABLE IF NOT EXISTS products (
product_id SERIAL PRIMARY KEY,
product_name VARCHAR(100) UNIQUE NOT NULL,
category VARCHAR(50) NOT NULL,
price NUMERIC(10, 2) NOT NULL,
stock INT DEFAULT 0
);
CREATE TABLE IF NOT EXISTS customers (
customer_id SERIAL PRIMARY KEY,
first_name VARCHAR(50),
last_name VARCHAR(50),
email VARCHAR(100) UNIQUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS orders (
order_id SERIAL PRIMARY KEY,
customer_id INT REFERENCES customers(customer_id),
order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
total_amount NUMERIC(10, 2)
);
-- Insert sample rows
INSERT INTO categories (name) VALUES
('Smartphones'),
('Laptops'),
('Audio')
ON CONFLICT DO NOTHING;
INSERT INTO products (product_name, category, price, stock) VALUES
('Pixel 9 Pro', 'Smartphones', 999.00, 50),
('MacBook Pro M3', 'Laptops', 1999.00, 20),
('ThinkPad X1 Carbon', 'Laptops', 1450.00, 35),
('Dell XPS 15', 'Laptops', 1700.00, 15),
('Bose QuietComfort', 'Audio', 349.00, 100)
ON CONFLICT DO NOTHING;
INSERT INTO customers (first_name, last_name, email) VALUES
('Ada', 'Lovelace', 'ada@example.com'),
('Alan', 'Turing', 'alan@example.com'),
('Grace', 'Hopper', 'grace@example.com')
ON CONFLICT DO NOTHING;
INSERT INTO orders (order_id, customer_id, total_amount, order_date) VALUES
(1, 1, 999.00, pg_catalog.now() - INTERVAL '7 months'),
(2, 2, 349.00, pg_catalog.now() - INTERVAL '1 month')
ON CONFLICT DO NOTHING;
CREATE INDEX IF NOT EXISTS idx_products_category ON products(category);
CREATE INDEX IF NOT EXISTS idx_orders_customer ON orders(customer_id);
EOF
4. MCP 도구 상자 서버 시작
이 섹션에서는 MCP 도구 상자 바이너리를 다운로드하고, 사전 빌드된 AlloyDB Omni 도구 정의를 구성하고, MCP 도구 상자 서버를 시작합니다.
MCP 도구 상자 다운로드
- MCP 도구 상자의 디렉터리를 만들고
toolbox바이너리를 다운로드합니다.mkdir -p ~/mcp/tools cd ~/mcp curl -L -O https://storage.googleapis.com/genai-toolbox/v0.31.0/linux/amd64/toolbox chmod +x toolbox ./toolbox --version
MCP 도구 상자 서버 구성 및 시작
- 사전 빌드된
alloydb-omni.yaml도구 구성을 다운로드하고 포트5000에서 MCP 도구 상자 서버를 시작합니다(이전에 내보낸ALLOYDB_OMNI_*환경 변수 사용).curl -sL --create-dirs -o "tools/alloydb-omni.yaml" "https://raw.githubusercontent.com/googleapis/mcp-toolbox/v0.31.0/internal/prebuiltconfigs/tools/alloydb-omni.yaml" # Remove the trailing group definition block and YAML document separator for --config-folder compatibility sed -i '/^kind: group/,$d' tools/alloydb-omni.yaml sed -i '${/---/d;}' tools/alloydb-omni.yaml ./toolbox --config-folder ./tools/ --port 5000 --address 127.0.0.1alloydb-omni.yaml구성은 이 Codelab에서 시연한 주요 도구를 포함하여 사전 빌드된 도구 31개를 제공합니다.execute_sqlget_query_plandatabase_overviewlist_active_querieslist_tables,list_indexes,list_views,list_triggerslist_top_bloated_tables,list_locks,list_autovacuum_configurations,list_invalid_indexes
alloydb-omni.yaml를 참고하세요. - 새 터미널 탭에서 MCP 도구 상자 서버가 실행 중이고 JSON-RPC
/mcp엔드포인트를 통해 도구를 노출하는지 확인합니다.curl -X POST http://localhost:5000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
5. MCP 클라이언트(Antigravity CLI) 구성
이 섹션에서는 Antigravity CLI(agy)를 설치하고 MCP 도구 상자 서버에 연결하도록 구성합니다.
Antigravity CLI 설치
- 아직 설치하지 않았다면 Antigravity CLI(
agy) 설치 프로그램을 다운로드하여 실행하고 버전을 확인합니다.curl -fsSL https://antigravity.google/cli/install.sh -o /tmp/install.sh bash /tmp/install.sh rm -f /tmp/install.sh # If prompted by the installer, add ~/.local/bin to your PATH: export PATH="$HOME/.local/bin:$PATH" # Verify the installation agy --version
Antigravity CLI 구성하기
클라이언트의 MCP 구성 파일(예: Antigravity CLI의 경우 ~/.gemini/config/mcp_config.json, Claude Code의 경우 .cursor/mcp.json, .vscode/mcp.json, claude_desktop_config.json 또는 .mcp.json)에 MCP Toolbox 서버 항목을 추가합니다.
- Antigravity CLI를 포트
5000에서 실행 중인 MCP 도구 상자 HTTP 서버에 연결하려면agy mcp add를 실행하고agy mcp list로 항목을 확인합니다.export MCP_SERVER="127.0.0.1" export MCP_PORT="5000" agy mcp add alloydb-omni "http://${MCP_SERVER}:${MCP_PORT}/mcp" agy mcp listalloydb-omni서버 구성이~/.gemini/config/mcp_config.json에 기록됩니다.{ "mcpServers": { "alloydb-omni": { "url": "http://127.0.0.1:5000/mcp" } } }
구성 확인
- Antigravity CLI를 시작합니다.
agyagy를 처음 실행하는 경우 화면 안내에 따라 Google OAuth 또는 Google Cloud 프로젝트로 로그인하고 현재 디렉터리를 신뢰할지 묻는 메시지가 표시되면 예, 이 폴더를 신뢰합니다를 선택합니다. - Antigravity CLI 프롬프트에서
/mcp를 입력하여 MCP 서버 패널을 열고alloydb-omni가 연결되어 있는지 확인합니다./mcpMCP Servers Configured (~/.gemini/config/mcp_config.json) > ✓ alloydb-omni Tools: database_overview, execute_sql, get_column_cardinality, get_query_plan, list_active_queries, +26 more Keyboard: ↑/↓ Navigate enter Actions
Esc를 눌러 MCP 서버 패널을 닫고 Antigravity CLI 프롬프트로 돌아갑니다.
6. AlloyDB Omni용 쿼리를 사용하여 테스트
이제 Antigravity CLI가 MCP 도구 상자를 통해 AlloyDB Omni 인스턴스에 연결되었으므로 자연어 프롬프트를 사용하여 데이터베이스와 상호작용할 수 있습니다.
데이터베이스 개요 쿼리 실행
- Antigravity CLI 프롬프트에서 현재 데이터베이스의 개요를 요청합니다.
Give me an overview of the current database.> Give me an overview of the current database. ● alloydb-omni/database_overview(Database overview check) (ctrl+o to expand) Here is an overview of the current AlloyDB Omni database instance: ### Database Overview • Instance / Engine: PostgreSQL 17.9 (AlloyDB Omni) • Role: Primary (is_replica: false) • Uptime: ~7 hours, 57 minutes • Connected Database: postgres • Connected User: postgres • Connections: 11 current / 100 max (1 active, 11% used) ### Databases in Instance • postgres • alloydbadmin (~15.74 MB) • alloydbmetadata (~14.82 MB)
카테고리별 테스트 예시
다음 자연어 요청을 Antigravity CLI에 프롬프트로 입력합니다. 에이전트는 각 요청을 AlloyDB Omni MCP 도구 모음의 해당 도구에 자동으로 매핑합니다.
1. 데이터베이스 개요 및 상태
테스트 목표 | 자연어 프롬프트 | 도구 호출됨 |
시스템 검사 |
|
|
활성 연결 |
|
|
설치된 확장 프로그램 |
|
|
사용 가능한 확장 프로그램 |
|
|
2. 스키마 및 카탈로그 탐색
테스트 목표 | 자연어 프롬프트 | 도구 호출됨 |
테이블 나열 |
|
|
색인 검사 |
|
|
뷰 탐색 |
|
|
테이블 트리거 확인 |
|
|
3. 데이터 쿼리 및 필터링(execute_sql)
테스트 목표 | 자연어 프롬프트 | 도구 호출됨 |
집계 쿼리 |
|
|
조인 쿼리 |
|
|
일치하지 않는 레코드 |
|
|
4. 쿼리 성능 및 계획 설명(get_query_plan)
테스트 목표 | 자연어 프롬프트 | 도구 호출됨 |
실행 계획 |
|
|
색인 확인 |
|
|
5. 데이터베이스 유지보수 및 진단
테스트 목표 | 자연어 프롬프트 | 도구 호출됨 |
테이블 비대화 |
|
|
잠금 경합 |
|
|
자동 배큠 설정 |
|
|
잘못된 색인 |
|
|
7. 삭제
Codelab을 완료한 후 시작한 로컬 컨테이너와 프로세스를 삭제합니다.
/quit를 입력하거나Ctrl+D를 두 번 눌러 Antigravity CLI를 종료합니다.- MCP 도구 상자 서버를 실행 중인 터미널 탭으로 전환하고
Ctrl+C를 눌러 중지합니다. - AlloyDB Omni Docker 컨테이너를 중지하고 삭제합니다.
docker stop alloydbomni docker rm alloydbomni
8. 축하합니다
Codelab을 완료했습니다. 축하합니다. 컨테이너에 AlloyDB Omni를 배포하고, 사전 빌드된 AlloyDB Omni 도구 모음으로 데이터베이스용 MCP 도구 상자를 구성하고, Antigravity CLI와 통합하여 자연어를 사용해 데이터베이스를 쿼리하고 관리했습니다.
학습한 내용
- Docker를 사용하여 AlloyDB Omni 컨테이너를 배포하고 확인하는 방법
- 에이전트 워크플로 테스트를 위해 샘플 테이블과 색인을 채우는 방법
- 사전 빌드된
alloydb-omni도구 구성을 사용하여 데이터베이스용 MCP 도구 상자를 구성하고 실행하는 방법 - Antigravity CLI를 MCP 도구 상자에 연결하고 스키마 검색, SQL 쿼리, 쿼리 계획 분석, 데이터베이스 진단을 위한 자연어 프롬프트를 실행하는 방법
자세한 내용은 다음 리소스를 참조하세요.