Postgres MCP Pro는 초기 코딩부터 테스트 및 배포, 프로덕션 튜닝 및 유지 관리까지 전체 개발 프로세스 동안 사용자와 AI 에이전트를 지원하도록 구축된 오픈 소스 모델 컨텍스트 프로토콜(MCP) 서버입니다.
Postgres MCP Pro는 데이터베이스 연결을 래핑하는 것보다 훨씬 더 많은 기능을 수행합니다.
특징은 다음과 같습니다.
🔍 데이터베이스 상태 - 인덱스 상태, 연결 사용률, 버퍼 캐시, 진공 상태, 시퀀스 제한, 복제 지연 등을 분석합니다.
⚡ 인덱스 튜닝 - 업계 최고 수준의 알고리즘을 사용하여 수천 개의 가능한 인덱스를 탐색하여 작업 부하에 가장 적합한 솔루션을 찾으세요.
📈 쿼리 계획 - EXPLAIN 계획을 검토하고 가상 인덱스의 영향을 시뮬레이션하여 성능을 검증하고 최적화합니다.
🧠 스키마 인텔리전스 - 데이터베이스 스키마에 대한 자세한 이해를 바탕으로 컨텍스트 인식 SQL을 생성합니다.
🛡️ 안전한 SQL 실행 - 읽기 전용 모드와 안전한 SQL 구문 분석을 포함한 구성 가능한 액세스 제어를 제공하여 개발과 운영 모두에 사용할 수 있습니다.
Postgres MCP Pro는 다양한 환경에서의 유연성을 위해 표준 입출력(stdio) 및 서버 전송 이벤트(SSE) 전송을 모두 지원합니다.
Postgres MCP Pro를 만든 이유에 대한 추가 배경 정보는 출시 블로그 게시물에서 확인하세요.
Related MCP server: Postgres MCP Pro
사용 불가능에서 번개처럼 빠른 속도로
과제: AI 보조 기능을 사용하여 영화 앱을 만들었지만, SQLAlchemy ORM 코드는 엄청나게 느렸습니다.
솔루션: Postgres MCP Pro와 Cursor를 사용하여 몇 분 만에 성능 문제를 해결했습니다.
우리가 한 일:
🚀 고정된 성능 - ORM 쿼리, 인덱싱 및 캐싱 포함
🛠️ 에이전트에게 데이터 탐색, 쿼리 수정, 관련 콘텐츠 추가를 요청하여 깨진 페이지를 수정했습니다.
🧠 상위 영화를 개선했습니다. 데이터를 탐색하고 ORM 쿼리를 수정하여 더욱 관련성 있는 결과를 표시했습니다.
아래 영상을 보거나 실황 영상을 읽어보세요.
https://github.com/user-attachments/assets/24e05745-65e9-4998-b877-a368f1eadc13
시작하기 전에 다음 사항을 확인하세요.
데이터베이스에 대한 액세스 자격 증명입니다.
Docker 또는 Python 3.12 이상.
psql 이나 pgAdmin 과 같은 GUI 도구를 사용하여 액세스 자격 증명이 유효한지 확인할 수 있습니다.
Docker와 Python 중 무엇을 사용할지는 사용자의 선택입니다. Python 사용자는 환경에 따라 문제가 발생할 수 있으므로 일반적으로 Docker를 권장합니다. 하지만 가장 익숙한 방법을 사용하는 것이 더 합리적일 수 있습니다.
다음 방법 중 하나를 선택하여 Postgres MCP Pro를 설치하세요.
Postgres MCP Pro MCP 서버 Docker 이미지를 가져오세요. 이 이미지에는 필요한 모든 종속성이 포함되어 있어 다양한 환경에서 Postgres MCP Pro를 안정적으로 실행할 수 있는 방법을 제공합니다.
지엑스피1
pipx 설치되어 있으면 다음을 사용하여 Postgres MCP Pro를 설치할 수 있습니다.
pipx install postgres-mcp그렇지 않은 경우 uv 사용하여 Postgres MCP Pro를 설치하세요.
uv pip install postgres-mcpuv 설치해야 하는 경우 uv 설치 지침을 참조하세요.
Claude Desktop을 사용하여 Postgres MCP Pro를 구성하는 방법에 대한 전체 지침을 제공합니다. 많은 MCP 클라이언트가 유사한 구성 파일을 가지고 있으므로, 원하는 클라이언트에 맞게 이 단계를 조정할 수 있습니다.
Postgres MCP Pro를 추가하려면 Claude Desktop 구성 파일을 편집해야 합니다. 이 파일의 위치는 운영 체제에 따라 다릅니다.
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
윈도우: %APPDATA%/Claude/claude_desktop_config.json
Claude Desktop의 Settings 메뉴 항목을 사용하여 구성 파일을 찾을 수도 있습니다.
이제 구성 파일의 mcpServers 섹션을 편집합니다.
{
"mcpServers": {
"postgres": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"DATABASE_URI",
"crystaldba/postgres-mcp",
"--access-mode=unrestricted"
],
"env": {
"DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
}
}
}
}Postgres MCP Pro Docker 이미지는 컨테이너 내부에서 작동하도록 호스트 이름 localhost 자동으로 다시 매핑합니다.
MacOS/Windows: host.docker.internal 자동으로 사용합니다.
Linux: 172.17.0.1 또는 해당 호스트 주소를 자동으로 사용합니다.
pipx 사용하는 경우{
"mcpServers": {
"postgres": {
"command": "postgres-mcp",
"args": [
"--access-mode=unrestricted"
],
"env": {
"DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
}
}
}
}uv 사용하는 경우{
"mcpServers": {
"postgres": {
"command": "uv",
"args": [
"run",
"postgres-mcp",
"--access-mode=unrestricted"
],
"env": {
"DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
}
}
}
}postgresql://... 을 Postgres 데이터베이스 연결 URI 로 바꾸세요.
Postgres MCP Pro는 AI 에이전트가 데이터베이스에서 수행할 수 있는 작업을 제어할 수 있도록 여러 액세스 모드를 지원합니다.
제한 없음 모드 : 데이터 및 스키마를 수정할 수 있는 전체 읽기/쓰기 권한을 허용합니다. 개발 환경에 적합합니다.
제한 모드 : 작업을 읽기 전용 트랜잭션으로 제한하고 리소스 사용률(현재는 실행 시간만 제한)에 제약을 가합니다. 프로덕션 환경에 적합합니다.
제한 모드를 사용하려면 위의 구성 예에서 --access-mode=unrestricted 를 --access-mode=restricted 바꾸세요.
많은 MCP 클라이언트는 Claude Desktop과 유사한 구성 파일을 가지고 있으며, 위의 예를 원하는 클라이언트에 맞게 적용할 수 있습니다.
커서를 사용하는 경우 Command Palette 에서 Cursor Settings 으로 이동한 다음 MCP 탭을 열어 구성 파일에 액세스할 수 있습니다.
Windsurf를 사용하는 경우 Command Palette 에서 Open Windsurf Settings Page 로 이동하여 구성 파일에 액세스할 수 있습니다.
Goose를 사용하는 경우 goose configure 실행한 다음 Add Extension 선택합니다.
Postgres MCP Pro는 SSE 전송을 지원하며, 이를 통해 여러 MCP 클라이언트가 하나의 서버(원격 서버일 수도 있음)를 공유할 수 있습니다. SSE 전송을 사용하려면 --transport=sse 옵션을 사용하여 서버를 시작해야 합니다.
예를 들어 Docker를 실행하면 다음과 같습니다.
docker run -p 8000:8000 \
-e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse그런 다음 MCP 서버를 호출하도록 MCP 클라이언트 구성을 업데이트하세요. 예를 들어, Cursor의 mcp.json 이나 Cline의 cline_mcp_settings.json 에 다음을 추가할 수 있습니다.
{
"mcpServers": {
"postgres": {
"type": "sse",
"url": "http://localhost:8000/sse"
}
}
}Windsurf의 경우 mcp_config.json 의 형식은 약간 다릅니다.
{
"mcpServers": {
"postgres": {
"type": "sse",
"serverUrl": "http://localhost:8000/sse"
}
}
}인덱스 튜닝과 포괄적인 성능 분석을 사용하려면 데이터베이스에 pg_statements 및 hypopg 확장 기능을 로드해야 합니다.
pg_statements 확장 기능을 사용하면 Postgres MCP Pro에서 쿼리 실행 통계를 분석할 수 있습니다. 예를 들어, 어떤 쿼리가 느리게 실행되거나 많은 리소스를 소모하는지 파악할 수 있습니다.
hypopg 확장 기능을 사용하면 Postgres MCP Pro에서 인덱스를 추가한 후 Postgres 쿼리 플래너의 동작을 시뮬레이션할 수 있습니다.
Postgres 데이터베이스가 클라우드 제공업체 관리형 서비스에서 실행 중이라면 pg_statements 및 hypopg 확장 기능이 이미 시스템에 설치되어 있어야 합니다. 이 경우, 충분한 권한이 있는 역할을 사용하여 CREATE EXTENSION 명령을 실행하면 됩니다.
CREATE EXTENSION IF NOT EXISTS pg_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;Postgres 설치를 직접 관리하는 경우 추가 작업이 필요할 수 있습니다. pg_statements 확장 프로그램을 로드하기 전에 Postgres 설정 파일의 shared_preload_libraries 에 등록되어 있는지 확인해야 합니다. hypopg 확장 프로그램은 Postgres와 함께 제공되는 것이 아니므로 추가적인 시스템 수준 설치(예: 패키지 관리자를 통한 설치)가 필요할 수도 있습니다.
묻다:
데이터베이스 상태를 확인하고 문제가 있는지 확인합니다.
묻다:
내 데이터베이스에서 가장 느린 쿼리는 무엇인가요? 그리고 어떻게 하면 속도를 높일 수 있나요?
묻다:
앱이 느린데, 어떻게 하면 더 빠르게 할 수 있을까요?
묻다:
데이터베이스 작업 부하를 분석하고 성능을 개선하기 위한 인덱스를 제안합니다.
묻다:
이 쿼리를 최적화하는 데 도움을 주세요: SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id WHERE orders.created_at > '2023-01-01';
MCP 표준은 도구, 리소스, 프롬프트 등 다양한 유형의 엔드포인트를 정의합니다.
Postgres MCP Pro는 MCP 도구 만으로 기능을 제공합니다. MCP 클라이언트 생태계가 MCP 도구에 대한 광범위한 지원을 제공하기 때문에 이러한 접근 방식을 선택했습니다. 이는 MCP 리소스를 사용하여 스키마 정보를 노출하는 Reference Postgres MCP Server를 포함한 다른 Postgres MCP 서버의 접근 방식과는 대조적입니다.
Postgres MCP Pro Tools:
도구 이름 | 설명 |
| PostgreSQL 인스턴스에서 사용할 수 있는 모든 데이터베이스 스키마를 나열합니다. |
| 지정된 스키마 내의 데이터베이스 객체(테이블, 뷰, 시퀀스, 확장)를 나열합니다. |
| 예를 들어 테이블의 열, 제약 조건, 인덱스 등 특정 데이터베이스 개체에 대한 정보를 제공합니다. |
| 제한 모드로 연결된 경우 읽기 전용 제한이 적용되어 데이터베이스에서 SQL 문을 실행합니다. |
| PostgreSQL에서 SQL 쿼리를 처리하는 방법을 설명하고 쿼리 플래너의 비용 모델을 보여주는 실행 계획을 가져옵니다. 가상 인덱스와 함께 호출하여 인덱스 추가 후의 동작을 시뮬레이션할 수 있습니다. |
|
|
| 데이터베이스 작업 부하를 분석하여 리소스를 많이 사용하는 쿼리를 식별한 다음, 이에 맞는 최적의 인덱스를 추천합니다. |
| 특정 SQL 쿼리 목록(최대 10개)을 분석하고 이에 대한 최적의 인덱스를 추천합니다. |
| 버퍼 캐시 적중률, 연결 상태, 제약 조건 검증, 인덱스 상태(중복/미사용/무효), 시퀀스 제한, 진공 상태를 포함한 포괄적인 상태 검사를 수행합니다. |
Postgres MCP 서버
MCP 쿼리 . 3계층 안전 아키텍처와 Supabase 관리 API 지원을 갖춘 Supabase Postgres용 MCP 서버입니다.
PG-MCP . 유연한 연결 옵션, 설명 계획, 확장 컨텍스트 등을 갖춘 PostgreSQL용 MCP 서버입니다.
PostgreSQL MCP 서버 참조 . 스키마 정보를 MCP 리소스로 노출하고 읽기 전용 쿼리를 실행하는 간단한 MCP 서버 구현입니다.
Supabase Postgres MCP 서버 . 이 MCP 서버는 Supabase 관리 기능을 제공하며 Supabase 커뮤니티에서 활발하게 관리됩니다.
나일 MCP 서버 . 나일의 멀티 테넌트 Postgres 서비스 관리 API에 대한 액세스를 제공하는 MCP 서버입니다.
Neon MCP 서버 . Neon의 서버리스 Postgres 서비스 관리 API에 대한 액세스를 제공하는 MCP 서버입니다.
Wren MCP 서버 . Postgres 및 기타 데이터베이스에 대한 비즈니스 인텔리전스를 강화하는 의미론적 엔진을 제공합니다.
DBA 도구(상업용 제품 포함)
Aiven Database Optimizer . 전체적인 데이터베이스 워크로드 분석, 쿼리 최적화 및 기타 성능 개선 기능을 제공하는 도구입니다.
dba.ai. GitHub과 통합되어 코드 문제를 해결하는 AI 기반 데이터베이스 관리 도우미입니다.
pgAnalyze . 성능 병목 현상 식별, 쿼리 최적화, 실시간 알림 기능을 제공하는 종합적인 모니터링 및 분석 플랫폼입니다.
Postgres.ai . 광범위한 Postgres 지식 기반과 GPT-4를 결합한 대화형 채팅 환경입니다.
Xata Agent . LLM 기반 추론 및 플레이북을 사용하여 데이터베이스 상태를 자동으로 모니터링하고, 문제를 진단하고, 권장 사항을 제공하는 오픈 소스 AI 에이전트입니다.
Postgres 유틸리티
Dexter . PostgreSQL에서 가상 인덱스를 생성하고 테스트하는 도구입니다.
PgHero . 권장 사항을 포함한 Postgres 성능 대시보드입니다. Postgres MCP Pro는 PgHero의 상태 점검 기능을 통합합니다.
PgTune . Postgres 구성 조정을 위한 휴리스틱.
Postgres MCP Pro는 다른 Postgres MCP 서버와 어떻게 다른가요? AI 에이전트가 Postgres 데이터베이스에 쿼리를 실행할 수 있도록 지원하는 MCP 서버가 많이 있습니다. Postgres MCP Pro도 이러한 기능을 제공할 뿐만 아니라, Postgres 데이터베이스의 성능을 파악하고 개선하는 도구도 제공합니다. 예를 들어, Microsoft SQL Server용 데이터베이스 튜닝 어드바이저(Database Tuning Advisor)의 Anytime Algorithm 버전을 구현합니다. 이 알고리즘은 자동 인덱스 튜닝을 위한 최신 고성능 알고리즘입니다.
Postgres MCP Pro | 다른 Postgres MCP 서버 |
✅ 결정론적 데이터베이스 상태 점검 | ❌ 반복할 수 없는 LLM 생성 상태 쿼리 |
✅ 원칙적인 인덱싱 검색 전략 | ❌ Gen-AI가 인덱싱 개선에 대해 추측 |
✅ 주요 문제를 찾기 위한 작업량 분석 | ❌ 일관성 없는 문제 분석 |
✅ 성능 개선을 시뮬레이션합니다 | ❌ 직접 시도해 보고 효과가 있는지 확인하세요 |
Postgres MCP Pro는 결정론적 도구와 기존 최적화 알고리즘을 추가하여 생성적 AI를 보완합니다. 이러한 조합은 안정적이고 유연합니다.
LLM이 추론, SQL 생성 등을 할 수 있는데 왜 MCP 도구가 필요할까요? LLM은 모호성, 추론 또는 자연어 처리가 필요한 작업에 매우 중요합니다. 그러나 절차적 코드와 비교했을 때 LLM은 느리고, 비용이 많이 들고, 비결정적이며, 때로는 신뢰할 수 없는 결과를 생성할 수 있습니다. 데이터베이스 튜닝의 경우, 수십 년에 걸쳐 개발되어 효과가 입증된 잘 정립된 알고리즘이 있습니다. Postgres MCP Pro는 LLM과 기존 최적화 알고리즘 및 기타 절차적 도구를 결합하여 두 가지 장점을 모두 누릴 수 있도록 지원합니다.
Postgres MCP Pro는 어떻게 테스트하나요? 테스트는 Postgres MCP Pro의 신뢰성과 정확성을 보장하는 데 매우 중요합니다. 저희는 Postgres MCP Pro의 성능을 시험하고 다양한 시나리오에서 성능을 보장하도록 설계된 AI 기반 적대적 워크로드 세트를 구축하고 있습니다.
어떤 Postgres 버전이 지원되나요? 현재 테스트는 Postgres 15, 16, 17에 집중되어 있습니다. Postgres 13부터 17까지 지원할 계획입니다.
이 프로젝트를 만든 사람은 누구인가요? 이 프로젝트는 Crystal DBA 가 만들고 관리하고 있습니다.
미정
여러분과 여러분의 요구는 저희가 만들어가는 모든 것의 핵심입니다. 이슈를 개설하거나 풀 리퀘스트를 통해 어떤 내용을 보고 싶으신지 알려주세요. Discord 를 통해 저희에게 연락하실 수도 있습니다.
이 섹션에서는 Postgres MCP Pro의 디자인에 영향을 준 기술적 고려 사항에 대한 개요를 설명합니다.
개발자들은 인덱스 누락이 데이터베이스 성능 문제의 가장 흔한 원인 중 하나라는 것을 알고 있습니다. 인덱스는 Postgres가 쿼리 실행에 필요한 데이터를 빠르게 찾을 수 있도록 하는 액세스 방법을 제공합니다. 테이블 크기가 작을 때는 인덱스의 영향이 크지 않지만, 데이터 크기가 커짐에 따라 테이블 스캔과 인덱스 조회 간의 알고리즘 복잡도 차이가 커집니다(일반적으로 O ( n ) 대 O ( logn ) , 여러 테이블 조인이 포함된 경우 더 커질 수 있음).
Postgres MCP Pro에서 제안된 인덱스를 생성하는 작업은 여러 단계로 진행됩니다.
튜닝이 필요한 SQL 쿼리를 파악하세요 . 특정 SQL 쿼리에 문제가 있는 경우 해당 쿼리를 제공할 수 있습니다. Postgres MCP Pro는 워크로드를 분석하여 인덱스 튜닝 대상을 파악할 수도 있습니다. 이를 위해 각 쿼리의 실행 시간과 리소스 사용량을 기록하는 pg_stat_statements 확장 기능을 활용합니다.
쿼리가 실행당 또는 전체적으로 리소스를 가장 많이 소비하는 경우 인덱스 튜닝 후보가 됩니다. 현재는 실행 시간을 누적 리소스 소비량의 대리 지표로 사용하지만, 액세스된 블록 수나 디스크에서 읽은 블록 수와 같은 특정 리소스를 살펴보는 것도 유용할 수 있습니다. analyze_query_workload 도구는 실행당 평균 시간과 실행 횟수 및 평균 실행 시간에 대한 임계값을 사용하여 느린 쿼리에 초점을 맞춥니다. 에이전트는 평균 실행 시간 대 전체 실행 시간을 매개변수로 받는 get_top_queries 호출한 후, 해당 쿼리에 대해 analyze_query_indexes 전달하여 인덱스 권장 사항을 얻을 수도 있습니다.
정교한 인덱스 튜닝 시스템은 "워크로드 압축"을 사용하여 전체 워크로드의 특성을 반영하는 대표적인 쿼리 하위 집합을 생성하여 다운스트림 알고리즘의 문제를 줄입니다. Postgres MCP Pro는 동일한 템플릿에서 생성된 쿼리가 하나로 표시되도록 쿼리를 정규화하여 제한된 형태의 워크로드 압축을 수행합니다. 각 쿼리에 동일한 가중치를 부여하는 이 간소화는 인덱싱의 이점이 클 때 효과적입니다.
후보 인덱스 생성 인덱싱을 통해 개선하고자 하는 SQL 쿼리 목록이 준비되면, 추가할 인덱스 목록을 생성합니다. 이를 위해 SQL 구문을 분석하고 필터, 조인, 그룹화 또는 정렬에 사용된 열을 식별합니다.
가능한 모든 인덱스를 생성하려면 Postgres가 다중 열 인덱스를 지원하므로 이러한 열의 조합을 고려해야 합니다. 현재 구현에서는 각 가능한 다중 열 인덱스의 순열을 하나만 포함하며, 이는 무작위로 선택됩니다. 순열은 종종 동일한 성능을 보이기 때문에 검색 공간을 줄이기 위해 이렇게 단순화했습니다. 하지만 이 부분을 개선하고자 합니다.
최적의 인덱스 구성을 검색합니다 . 저희의 목표는 인덱스 저장 및 유지 관리 비용 대비 성능 이점을 최적으로 균형 잡는 인덱스 조합을 찾는 것입니다. hypopg 확장 기능이 제공하는 "what if?" 기능을 사용하여 성능 향상을 예측합니다. 이는 Postgres 쿼리 옵티마이저가 인덱스 추가 후 쿼리를 실행하는 방식을 시뮬레이션하고, 실제 Postgres 비용 모델을 기반으로 변경 사항을 보고합니다.
한 가지 과제는 쿼리 계획을 생성하려면 일반적으로 쿼리에 사용된 특정 매개변수 값에 대한 지식이 필요하다는 것입니다. 고려 대상 쿼리를 줄이기 위해 필요한 쿼리 정규화는 매개변수 상수를 제거합니다. 바인드 변수를 통해 제공된 매개변수 값도 마찬가지로 사용할 수 없습니다.
이 문제를 해결하기 위해 테이블 통계에서 샘플링하여 매개변수로 제공할 수 있는 현실적인 상수를 생성합니다. Postgres 16 버전에서 일반적인 Explain Plan 기능이 추가되었지만, LIKE 절과 같은 제약이 있는데, 이는 저희 구현에는 없는 기능입니다.
검색 전략은 매우 중요합니다. 가능한 모든 인덱스 조합을 평가하는 것은 단순한 상황에서만 가능하기 때문입니다. 이것이 다양한 인덱싱 접근 방식을 구분하는 가장 중요한 요소입니다. Microsoft의 Anytime 알고리즘 방식을 적용하여 탐욕적 검색 전략을 사용합니다. 즉, 최적의 단일 인덱스 솔루션을 찾은 다음, 여기에 최적의 인덱스를 추가하여 두 개의 인덱스 솔루션을 생성합니다. 시간 예산이 소진되거나 탐색 라운드에서 최소 개선 기준인 10% 이상의 성과를 얻지 못하면 검색이 종료됩니다.
비용 편익 분석 . 더 나은 성능을 제공하는 것과 더 많은 공간을 필요로 하는 두 가지 인덱싱 대안이 있을 때, 어떤 것을 선택할지 어떻게 결정해야 할까요? 전통적으로 인덱스 어드바이저는 스토리지 예산을 요청하고 해당 예산에 맞춰 성능을 최적화합니다. 저희도 스토리지 예산을 사용하지만, 최적화 과정 전반에 걸쳐 비용 편익 분석을 수행합니다.
이 문제는 파레토 전선(Pareto front)에서 한 지점을 선택하는 문제로 정의됩니다. 파레토 전선 은 한 품질 지표를 개선할 때 다른 지표가 필연적으로 악화되는 선택지 집합입니다. 이상적인 환경에서는 저장 비용과 성능 향상의 이점을 금전적 가치로 평가하고 싶을 것입니다. 하지만 더 간단하고 실용적인 방법이 있습니다. 바로 상대적인 관점에서 변화를 살펴보는 것입니다. 대부분의 사람들은 저장 비용이 두 배라 하더라도 성능이 100배 향상되는 것은 가치 있다고 동의할 것입니다. 저희 구현에서는 설정 가능한 매개변수를 사용하여 이 임계값을 설정합니다. 기본적으로 성능 향상의 로그(10진수) 변화가 공간 비용의 로그 차이의 두 배여야 합니다. 이는 100배의 성능 향상을 위해 최대 10배의 공간 증가가 가능하다는 것을 의미합니다.
저희 구현은 Microsoft SQL Server의 Anytime 알고리즘 과 가장 밀접하게 연관되어 있습니다. Postgres용 자동 인덱싱 도구인 Dexter 와 비교했을 때, 저희는 더 넓은 공간을 검색하고 다른 휴리스틱을 사용합니다. 이를 통해 더 긴 런타임을 감수하더라도 더 나은 솔루션을 도출할 수 있습니다.
또한 각 검색 라운드에서 수행된 작업을 보여주고, 각 인덱스 추가 전후의 쿼리 계획을 비교합니다. 이를 통해 LLM은 인덱싱 권장 사항에 응답할 때 활용할 수 있는 추가적인 맥락을 확보할 수 있습니다.
데이터베이스 상태 점검은 심각한 문제로 이어지기 전에 튜닝 기회와 유지 관리 필요성을 파악합니다. 현재 릴리스에서는 Postgres MCP Pro가 PgHero 에서 직접 제공하는 데이터베이스 상태 점검 기능을 그대로 사용합니다. 저희는 이러한 점검 기능을 완벽하게 검증하기 위해 노력하고 있으며, 향후 확장할 수 있습니다.
인덱스 상태 . 사용되지 않는 인덱스, 중복 인덱스, 그리고 과도하게 사용된 인덱스를 찾습니다. 과도하게 사용된 인덱스는 데이터베이스 페이지를 비효율적으로 사용합니다. Postgres 자동 진공 기능은 사용되지 않는 튜플을 가리키는 인덱스 항목을 정리하고 재사용 가능한 항목으로 표시합니다. 하지만 인덱스 페이지를 압축하지는 않으므로, 결국 인덱스 페이지에는 활성 튜플 참조가 거의 포함되지 않을 수 있습니다.
버퍼 캐시 적중률 . 디스크 대신 버퍼 캐시에서 처리되는 데이터베이스 읽기 작업의 비율을 측정합니다. 낮은 버퍼 캐시 적중률은 비용 최적화에 도움이 되지 않고 애플리케이션 성능 저하로 이어질 수 있으므로 반드시 확인해야 합니다.
연결 상태 . 데이터베이스 연결 수를 확인하고 사용률을 보고합니다. 가장 큰 위험은 연결 부족이지만, 유휴 또는 차단된 연결이 많은 것도 문제를 나타낼 수 있습니다.
진공 상태 . 진공은 여러 가지 이유로 중요합니다. 가장 중요한 이유 중 하나는 데이터베이스가 쓰기를 허용하지 않도록 하는 트랜잭션 ID 랩어라운드를 방지하는 것입니다. Postgres 다중 버전 동시성 제어(MVCC) 메커니즘은 각 트랜잭션에 대해 고유한 트랜잭션 ID를 요구합니다. 그러나 Postgres는 트랜잭션 ID에 32비트 부호 있는 정수를 사용하기 때문에 최대 20억 개의 트랜잭션 이후에는 트랜잭션 ID를 재사용해야 합니다. 이를 위해 Postgres는 과거 트랜잭션의 트랜잭션 ID를 "고정"하여 먼 과거를 나타내는 특수 값으로 설정합니다. 레코드가 처음 디스크에 저장될 때, 해당 레코드는 특정 범위의 트랜잭션 ID에 대한 가시성을 갖습니다. 이러한 트랜잭션 ID를 재사용하기 전에 Postgres는 디스크에 있는 모든 레코드를 업데이트하여 "고정"하고 재사용할 트랜잭션 ID에 대한 참조를 제거해야 합니다. 이 검사는 트랜잭션 ID 랩어라운드를 방지하기 위해 진공 작업이 필요한 테이블을 찾습니다.
복제 상태 . 기본 복제본과 복제본 간 지연을 모니터링하고, 복제 상태를 확인하고, 복제 슬롯 사용량을 추적하여 복제 상태를 점검합니다.
제약 조건 상태 . 정상적인 작동 중에 Postgres는 제약 조건 위반을 유발하는 모든 트랜잭션을 거부합니다. 그러나 데이터 로드 후 또는 복구 상황에서는 유효하지 않은 제약 조건이 발생할 수 있습니다. 이 검사는 유효하지 않은 제약 조건을 찾습니다.
시퀀스 상태 . 최대값을 초과할 위험이 있는 시퀀스를 찾습니다.
Postgres MCP Pro는 psycopg3를 사용하여 비동기 I/O를 통해 Postgres에 연결합니다. psycopg3는 내부적으로 libpq 라이브러리를 사용하여 Postgres에 연결하여 Postgres의 모든 기능 세트와 Postgres 커뮤니티에서 완벽하게 지원하는 기본 구현에 대한 액세스를 제공합니다.
일부 다른 Python 기반 MCP 서버는 asyncpg를 사용하는데, 이는 libpq 종속성을 제거하여 설치를 간소화할 수 있습니다. asyncpg는 psycopg3보다 빠를 가능성이 높지만, 직접 검증하지는 않았습니다. 이전 벤치마크 에서 더 큰 성능 격차가 보고된 것을 보면, 새로운 psycopg3가 성숙해지면서 그 격차를 줄인 것으로 보입니다.
이러한 고려 사항을 종합하여 asyncpg 대신 psycopg3 선택했습니다. 향후 이 결정을 수정할 가능성도 열려 있습니다.
참조 PostgreSQL MCP 서버 와 마찬가지로 Postgres MCP Pro는 시작 시 Postgres 연결 정보를 가져옵니다. 이는 항상 동일한 데이터베이스에 연결하는 사용자에게는 편리하지만, 사용자가 데이터베이스를 전환할 때는 번거로울 수 있습니다.
PG-MCP 가 채택한 대안적인 접근 방식은 사용 시점에 MCP 도구 호출을 통해 연결 세부 정보를 제공하는 것입니다. 이는 데이터베이스를 전환하는 사용자에게 더욱 편리하며, 단일 MCP 서버로 여러 최종 사용자를 동시에 지원할 수 있습니다.
이 둘보다 더 나은 접근 방식이 분명 있을 것입니다. 두 방법 모두 보안 취약점이 있습니다. MCP 클라이언트 중 MCP 서버 구성을 안전하게 저장하는 클라이언트는 거의 없으며(Goose는 예외), MCP 도구를 통해 제공된 자격 증명은 LLM을 통해 전달되어 채팅 기록에 저장됩니다. 또한 두 방법 모두 일부 상황에서 사용성 문제가 있습니다.
스키마 정보 도구의 목적은 호출하는 AI 에이전트에게 정확하고 효율적인 SQL을 생성하는 데 필요한 정보를 제공하는 것입니다. 예를 들어, 사용자가 "지난 1년 동안 샌프란시스코에서 이륙하여 파리에 착륙한 항공편은 몇 편입니까?"라고 질문한다고 가정해 보겠습니다. AI 에이전트는 항공편 정보를 저장하는 테이블, 출발지와 목적지를 저장하는 열, 그리고 공항 코드와 공항 위치를 매핑하는 테이블을 찾아야 합니다.
LLM이 일반적으로 Postgres에서 직접 이 정보를 검색하기 위한 SQL을 생성할 수 있는데 왜 스키마 정보 도구를 제공합니까?
Claude를 사용한 경험에 따르면, 호출하는 LLM은 Postgres 시스템 카탈로그 와 정보 스키마 (ANSI 표준 데이터베이스 메타데이터 뷰)를 쿼리하여 Postgres 스키마를 탐색하는 SQL을 생성하는 데 매우 능숙합니다. 그러나 다른 LLM들이 이 작업을 이처럼 안정적이고 효율적으로 수행하는지는 알 수 없습니다.
MCP 도구 보다는 MCP 리소스를 사용하여 스키마 정보를 제공하는 것이 더 나을까요?
참조 PostgreSQL MCP 서버는 도구 대신 리소스를 사용하여 스키마 정보를 노출합니다. 리소스 탐색은 파일 시스템 탐색과 유사하므로 이러한 접근 방식은 여러 면에서 자연스럽습니다. 그러나 MCP 클라이언트 생태계에서 리소스 지원은 도구 지원보다 덜 널리 퍼져 있습니다( 예제 클라이언트 참조). 또한, MCP 표준에서는 AI 에이전트 또는 최종 사용자(인간)가 리소스에 액세스할 수 있다고 명시되어 있지만, 일부 클라이언트는 리소스 트리의 인간 탐색만 지원합니다.
AI는 단순한 실수부터 악의적인 행위자의 정교한 공격에 이르기까지 다양한 위협으로부터 데이터베이스를 보호하는 오랜 과제를 더욱 심화시킵니다. 위협이 우발적이든 악의적이든, 기밀성, 무결성, 가용성이라는 세 가지 범주로 구분되는 목표를 가진 유사한 보안 프레임워크가 적용됩니다. 편의성과 안전성 사이의 익숙한 갈등 또한 분명하고 뚜렷하게 드러납니다.
Postgres MCP Pro의 보호된 SQL 실행 모드는 무결성에 중점을 둡니다. MCP와 관련하여, LLM에서 생성된 SQL이 손상을 유발하는 경우(예: 의도치 않은 데이터 수정 또는 삭제, 또는 조직의 변경 관리 프로세스를 우회할 수 있는 기타 변경)에 가장 큰 관심을 기울입니다.
무결성을 보장하는 가장 간단한 방법은 데이터베이스에 대해 실행되는 모든 SQL을 읽기 전용으로 설정하는 것입니다. 한 가지 방법은 읽기 전용 접근 권한을 가진 데이터베이스 사용자를 생성하는 것입니다. 이는 좋은 방법이지만, 실제로는 많은 사람들이 번거롭다고 생각합니다. Postgres는 연결이나 세션을 읽기 전용 모드로 전환하는 방법을 제공하지 않으므로, Postgres MCP Pro는 읽기-쓰기 연결에서 읽기 전용 SQL 실행을 보장하기 위해 더 복잡한 방식을 사용합니다.
Postgres MCP는 데이터 및 스키마 수정을 방지하는 읽기 전용 트랜잭션 모드를 제공합니다. 참조 PostgreSQL MCP 서버 와 마찬가지로, 읽기 전용 트랜잭션을 사용하여 보호된 SQL 실행을 제공합니다.
이 메커니즘을 강력하게 만들기 위해서는 SQL이 COMMIT 이나 ROLLBACK 명령문을 발행한 다음 새로운 트랜잭션을 시작하는 등 읽기 전용 트랜잭션 모드를 우회하지 않도록 해야 합니다.
예를 들어, LLM은 ROLLBACK 문을 실행한 후 새 트랜잭션을 시작하여 읽기 전용 트랜잭션 모드를 우회할 수 있습니다. 예를 들면 다음과 같습니다.
ROLLBACK; DROP TABLE users;이러한 문제를 방지하기 위해 pglast 라이브러리를 사용하여 실행 전에 SQL 구문을 분석합니다. commit 또는 rollback 문이 포함된 SQL은 모두 거부합니다. 다행히도 PL/pgSQL 및 PL/Python을 포함한 널리 사용되는 Postgres 저장 프로시저 언어는 COMMIT 또는 ROLLBACK 문을 허용하지 않습니다. 데이터베이스에 안전하지 않은 저장 프로시저 언어가 활성화되어 있는 경우, 읽기 전용 보호 기능을 우회할 수 있습니다.
현재 Postgres MCP Pro는 데이터베이스에 대해 두 가지 수준의 보호를 제공합니다. 하나는 편의성/안전성 스펙트럼의 양쪽 극단에 위치합니다.
"제한 없음"은 최대한의 유연성을 제공합니다. 속도와 유연성이 가장 중요하고 중요하거나 민감한 데이터를 보호할 필요가 없는 개발 환경에 적합합니다.
"제한됨"은 유연성과 안전성의 균형을 제공합니다. 데이터베이스가 신뢰할 수 없는 사용자에게 노출되고 중요하거나 민감한 데이터를 보호하는 것이 중요한 프로덕션 환경에 적합합니다.
제한 없음 모드는 AI 에이전트가 제한된 인적 감독이나 승인 하에 작동하는 Cursor의 자동 실행 모드 와 같은 접근 방식입니다. 자동 실행은 실수의 결과가 적고, 데이터베이스에 중요하거나 민감한 데이터가 없으며, 필요 시 백업을 통해 재생성하거나 복원할 수 있는 개발 환경에 배포될 것으로 예상됩니다.
제한 모드는 불편할 수 있지만, 안전성을 고려하여 보수적으로 설계되었습니다. 제한 모드는 읽기 전용 작업으로 제한되며, 장시간 실행되는 쿼리가 시스템 성능에 영향을 미치지 않도록 쿼리 실행 시간을 제한합니다. 향후 프로덕션 데이터베이스에서 제한 모드를 안전하게 사용할 수 있도록 조치를 추가할 수 있습니다.
아래 지침은 Postgres MCP Pro에서 작업하려는 개발자나 소스에서 Postgres MCP Pro를 설치하려는 사용자를 위한 것입니다.
uv 설치 :
curl -sSL https://astral.sh/uv/install.sh | sh저장소를 복제합니다 .
git clone https://github.com/crystaldba/postgres-mcp.git
cd postgres-mcp종속성 설치 :
uv pip install -e .
uv sync서버를 실행합니다 :
uv run postgres-mcp "postgres://user:password@localhost:5432/dbname"Analyzes database health. Here are the available health checks:
index - checks for invalid, duplicate, and bloated indexes
connection - checks the number of connection and their utilization
vacuum - checks vacuum health for transaction id wraparound
sequence - checks sequences at risk of exceeding their maximum value
replication - checks replication health including lag and slots
buffer - checks for buffer cache hit rates for indexes and tables
constraint - checks for invalid constraints
all - runs all checks You can optionally specify a single health check or a comma-separated list of health checks. The default is 'all' checks.
| Name | Required | Description | Default |
|---|---|---|---|
| health_type | No | Optional. Valid values are: all, buffer, connection, constraint, index, replication, sequence, vacuum. | all |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description aligns with this by using 'analyzes' and describing read-only checks. The description adds value by explaining what each check examines (e.g., invalid indexes, connection utilization, vacuum health), which helps the agent understand the tool's behavior beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a lead sentence and a bulleted list of checks. It is appropriately sized given the number of checks, and each bullet adds necessary information. It is slightly long but not wasteful, earning a strong score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to explain return values. It thoroughly covers the input parameter, enumerates all health check options, and describes the default behavior, making it complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already lists valid values for health_type with 100% coverage. The description enhances this by explaining what each value does and explicitly noting that comma-separated lists are allowed, which is not in the schema. This additional semantic detail goes beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('analyzes database health') and enumerates eight distinct health check categories. This distinguishes it from sibling tools like analyze_workload_indexes and execute_sql, which focus on other aspects of database operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for using the tool by detailing each health check option and the default behavior. However, it does not explicitly state when to use this tool versus alternatives like analyze_workload_indexes, nor does it mention exclusions, so it falls short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a list of (up to 10) SQL queries and recommend optimal indexes
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | Method to use for analysis | dta |
| queries | Yes | List of Query strings to analyze | |
| max_index_size_mb | No | Max index size in MB |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals this is a safe read operation. The description adds the 'up to 10' query limit, which is a useful constraint, but does not disclose other behaviors such as the default analysis method ('dta'), the effect of 'max_index_size_mb', or potential latency. It adds minimal context beyond the annotations and purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose and a key constraint without unnecessary words. Every word earns its place, and no filler or redundancy exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the annotations mark it read-only, the description is adequate for an AI to understand the tool's basic function. It captures the input limit and the goal. Missing is a note on when to use this vs. analyze_workload_indexes, but that is a usage nuance rather than a completeness gap. Overall it is complete for a simple analysis tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters. The description does not add additional meaning for 'queries', 'method', or 'max_index_size_mb' beyond what the schema provides. Baseline of 3 applies because the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Analyze'), names the resource ('SQL queries'), and clearly states the output ('recommend optimal indexes'). It distinguishes itself from the sibling tool 'analyze_workload_indexes' by noting the input is a list of up to 10 queries rather than a workload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a bounded set of queries (up to 10) but does not explicitly state when to prefer this tool over alternatives like 'analyze_workload_indexes' or 'explain_query'. There are no clear exclusions or alternative references, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze frequently executed queries in the database and recommend optimal indexes
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | Method to use for analysis | dta |
| max_index_size_mb | No | Max index size in MB |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the description's read-only analysis nature is consistent. It adds context that the analysis targets 'frequently executed queries' and produces index recommendations, but does not disclose any potential performance impact, the fact that it does not apply indexes, or what happens with the output beyond being a recommendation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the tool's purpose without superfluous words. It is front-loaded with the action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and full schema parameter coverage, the description is minimally sufficient. However, it lacks information on the two methods ('dta' vs 'llm') and does not clarify how this tool differs from the closely named sibling 'analyze_query_indexes', which is a notable gap for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'method' and 'max_index_size_mb' having descriptions. The tool description adds no parameter-specific semantics beyond the schema, so it does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Analyze') and identifies the resource ('frequently executed queries') and outcome ('recommend optimal indexes'), making the tool's function clear. However, it does not explicitly differentiate from the sibling tool 'analyze_query_indexes', which may operate on a single query rather than a workload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'analyze_query_indexes' or 'get_top_queries'. It does not mention scenarios, prerequisites, or exclusions, leaving the agent to infer usage from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute any SQL query
| Name | Required | Description | Default |
|---|---|---|---|
| sql | No | SQL to run | all |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations include destructiveHint=true, which already alerts the agent to potential destructive side effects. The description's 'any' reinforces that the tool can execute non-read queries, but it adds no additional behavioral context such as permission requirements, transaction handling, or result format. This is a minimal contribution beyond the structured hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of one concise sentence, 'Execute any SQL query', which is immediately front-loaded and free of unnecessary elaboration. It optimizes brevity while conveying the essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple SQL executor with a single parameter and an output schema, and the annotation provides a destructive warning. However, the description gives no context about when to use it (e.g., for arbitrary reads/writes) versus the specialized sibling tools, and it omits any caveats about side effects beyond the bare annotation. Given the tool's low complexity, this is adequate but not enriched, so it falls short of being fully contextual.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a single `sql` parameter with a description ('SQL to run') and a default, achieving 100% coverage. The tool description 'Execute any SQL query' adds no further meaning about the parameter's syntax, allowed statements, or formatting. Since the schema already documents the parameter, no compensating explanation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Execute any SQL query' clearly states the tool's verb (execute) and resource (SQL query), making its core function unambiguous. However, it does not explicitly differentiate from sibling tools like explain_query or analyze_query_indexes, leaving the reader to infer its role as a general-purpose executor. This is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that this is for arbitrary SQL execution while siblings handle query analysis, schema listing, or index insights, nor does it state any restrictions or prerequisites. This leaves the agent without direction for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explains the execution plan for a SQL query, showing how the database will execute it and provides detailed cost estimates.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL query to explain | |
| analyze | No | When True, actually runs the query to show real execution statistics instead of estimates. Takes longer but provides more accurate information. | |
| hypothetical_indexes | No | A list of hypothetical indexes to simulate. Each index must be a dictionary with these keys: - 'table': The table name to add the index to (e.g., 'users') - 'columns': List of column names to include in the index (e.g., ['email'] or ['last_name', 'first_name']) - 'using': Optional index method (default: 'btree', other options include 'hash', 'gist', etc.) Examples: [ {"table": "users", "columns": ["email"], "using": "btree"}, {"table": "orders", "columns": ["user_id", "created_at"]} ] If there is no hypothetical index, you can pass an empty list. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the tool is known to be a safe read operation. However, the description does not disclose that the 'analyze' parameter actually executes the query, which is an important behavioral nuance. No contradiction with annotations, but little added context beyond purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that immediately states what the tool does. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% param coverage) and existing output schema, the description is mostly sufficient. However, it could mention the optional analyze and hypothetical_indexes capabilities in the main description for quicker agent awareness, though these are covered in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed parameter descriptions including examples for hypothetical_indexes. The description itself adds no parameter-level information, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool explains the execution plan for a SQL query, with specific verb 'explains' and resource 'execution plan'. It also mentions cost estimates, distinguishing it from execute_sql and analyze_query_indexes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied ('explains the execution plan') but no explicit guidance on when to use this tool versus alternatives like analyze_query_indexes or execute_sql. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show detailed information about a database object
| Name | Required | Description | Default |
|---|---|---|---|
| object_name | Yes | Object name | |
| object_type | No | Object type: 'table', 'view', 'sequence', or 'extension' | table |
| schema_name | Yes | Schema name |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint: true, which already indicates a safe read operation, and the description aligns with this by saying 'Show detailed information'. However, the description adds no extra behavioral context beyond the annotation, such as what constitutes 'detailed' or how missing objects are handled. With annotations present, the bar is lower, and the description meets the minimum without adding value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource. It contains no filler or redundant wording, earning full marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema (mentioned in context signals), and the fully described input schema, the description is largely adequate. However, it lacks explicit guidance on when to use this tool over siblings, which would improve completeness. The missing usage context is the main gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (schema_name, object_name, object_type) having a clear description. The tool description itself adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies. object_type's default value and allowed values are already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Show detailed information about a database object' uses a specific verb ('Show') and resource ('database object'), making the core purpose clear. It distinguishes itself from sibling tools like 'list_objects' (which likely enumerates objects) by focusing on details of a single object, but it does not explicitly state this differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention that this tool is for inspecting a specific object as opposed to listing all objects, nor does it describe any prerequisites or exclusions. The user must infer usage from the tool name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports the slowest or most resource-intensive queries using data from the 'pg_stat_statements' extension.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of queries to return when ranking based on mean_time or total_time | |
| sort_by | No | Ranking criteria: 'total_time' for total execution time or 'mean_time' for mean execution time per call, or 'resources' for resource-intensive queries | resources |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint: true, so the safe nature is already known. The description adds useful context about the data source (pg_stat_statements) but does not disclose prerequisites like extension availability or any limitations on the reported data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that front-loads the purpose and names the data source. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is simple and self-contained, naming the data source and purpose. Output schema and parameter schema cover the remaining details. A minor gap is not mentioning that the pg_stat_statements extension must be installed for the tool to work.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters, including explanations for valid sort_by values. The tool description adds no extra parameter-level detail, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reports') and the resource ('slowest or most resource-intensive queries') with a specific data source ('pg_stat_statements'). This distinguishes it from siblings like explain_query and analyze_query_indexes, which focus on different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus the sibling analysis tools. No mention of prerequisites, appropriate contexts, or exclusions; the intended use is only implied by the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List objects in a schema
| Name | Required | Description | Default |
|---|---|---|---|
| object_type | No | Object type: 'table', 'view', 'sequence', or 'extension' | table |
| schema_name | Yes | Schema name |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the readOnlyHint annotation; it simply restates the tool's purpose in a generic way. It does not mention pagination, default object_type behavior, or scope limitations, and because annotations already declare read-only, the description provides no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (a single sentence) and free of fluff, but it is also under-specified and essentially repeats the title. It lacks any structured detail (e.g., parameter mentions, usage context) that would make the sentence earn its place beyond the obvious.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the input schema, readOnlyHint annotation, and presence of an output schema provide sufficient context for an agent to use it correctly. The description, while minimal, correctly states the high-level function, which is adequate for a straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters (schema_name required, object_type with allowed values), giving 100% schema description coverage. The description adds no parameter-level meaning, but the schema already handles the semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (list) and resource (objects in a schema), which is a specific verb+resource combination. However, it does not mention the object types or differentiate from sibling tools like get_object_details, so it lacks the scope and differentiation needed for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_schemas or get_object_details. There is no context about prerequisites, exclusions, or typical use cases, so the agent receives no decision-support information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all schemas in the database
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, which covers safety. The description adds the scope 'all schemas' but does not disclose other behavioral traits like ordering, pagination, or return format. With annotations present, a neutral score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, 'List all schemas in the database', with no wasted words. It front-loads the action and object clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with no parameters and an output schema, the description fully covers the necessary context. It is complete without over-explaining, and annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no param info, but none is needed; the empty schema is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'schemas' and scope 'in the database'. It distinguishes from siblings like list_objects and get_object_details by explicitly focusing on schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool (when needing all schemas), but it does not explicitly state alternatives or exclusions. The presence of siblings like list_objects suggests a need for more differentiation, but none is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1analyze_db_healthanalyze_query_indexesanalyze_workload_indexesexecute_sqlexplain_queryget_object_detailsget_top_querieslist_objectslist_schemasv0.3.0analyze_db_healthanalyze_query_indexesanalyze_workload_indexesexecute_sqlexplain_queryget_object_detailsget_top_querieslist_objectslist_schemasv1.0.0analyze_db_healthanalyze_query_indexesanalyze_workload_indexesexecute_sqlexplain_queryget_object_detailsget_top_querieslist_objectslist_schemasScored across 9 tools
Each tool targets a distinct aspect of database interaction: health checks, index analysis, query execution, explain plans, object details, top queries, and listing schemas/objects. There is no overlap; the two index analysis tools are differentiated by input (specific queries vs. workload).
All tool names follow a consistent verb_noun pattern in snake_case (analyze_, execute_, explain_, get_, list_). Verbs like 'analyze', 'execute', 'explain', 'get', and 'list' are used uniformly, making the naming predictable.
With 9 tools, the set is well-scoped for a Postgres MCP server covering health analysis, index optimization, query execution, and schema exploration. It neither feels sparse nor overwhelming, earning its place.
The tool set covers analysis and ad-hoc queries comprehensively via execute_sql, but lacks explicit tools for creating, altering, or dropping database objects. However, execute_sql enables these operations indirectly, making the gap minor.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Xata MCP server lets AI agents interact with your Xata projects, and Postgres database branches.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
