Enables containerized deployment of the PostgreSQL MCP server with Docker Compose support for simplified setup and management.
Supports environment configuration through .env files for storing database connection details and other configuration parameters.
Provides comprehensive PostgreSQL database analysis and optimization tools including health monitoring, performance tuning, index recommendations, and maintenance planning.
Leverages Python for implementation with support for Python 3.8+ environments and integration with Python-based workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Postgres MCP Pro Plus analyze the health of our production database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🔍 Comprehensive Database Analysis: Deep insights into schema structure, relationships, and performance
⚡ AI-Powered Optimization: Intelligent index recommendations using Database Tuning Advisor (DTA) and LLM methods
🩺 Advanced Health Monitoring: Multi-dimensional health checks with predictive analytics
🔒 Lock & Blocking Analysis: Real-time detection and resolution of query blocking and deadlocks
🧹 Smart Maintenance: Automated vacuum analysis with bloat detection and maintenance scheduling
📊 Performance Intelligence: Query performance analysis with resource usage optimization
🔐 Security Assessment: Comprehensive security analysis and recommendations
🐳 Docker Ready: Containerized deployment with Docker Compose support
Related MCP server: MCP PostgreSQL Operations
Tool Name | Description |
| List all schemas with ownership and type classification |
| Browse database objects (tables, views, sequences, extensions) by schema |
| Detailed object analysis including columns, constraints, and indexes |
| Execute SQL with safety controls (restricted/unrestricted modes) |
Tool Name | Description |
| Advanced execution plan analysis with HypoPG hypothetical index simulation |
| Identify slow and resource-intensive queries with performance metrics |
| AI-powered index recommendations from workload analysis (DTA/LLM) |
| Targeted index optimization for specific query sets (up to 10 queries) |
Tool Name | Description |
| Comprehensive health checks: indexes, connections, vacuum, sequences, replication, buffer cache, constraints |
| Advanced blocking analysis with lock hierarchy visualization and resolution recommendations |
| Comprehensive vacuum analysis with bloat detection and maintenance recommendations |
Tool Name | Description |
| Enterprise-grade database assessment with performance, security, and relationship analysis |
| Schema dependency mapping with visual relationship analysis and coupling metrics |
Enterprise-grade comprehensive database assessment
The get_database_overview tool provides multi-dimensional analysis:
📊 Schema Analysis: Complete structure with table relationships and dependency mapping
⚡ Performance Metrics: Query performance, index efficiency, and resource utilization patterns
🔐 Security Analysis: User permissions, role assignments, and security configuration assessment
💾 Storage Analysis: Table sizes, index bloat detection, and disk usage optimization
🩺 Health Indicators: Connection health, vacuum statistics, and system performance metrics
Configuration Options:
max_tables (default: 500): Maximum tables to analyze per schema for performance control
sampling_mode (default: true): Statistical sampling for large datasets to optimize execution time
timeout (default: 300): Maximum execution time with graceful timeout handling
Real-time lock contention detection and resolution
The get_blocking_queries tool features enterprise-grade capabilities:
🎯 Core Features:
Modern Detection: Uses PostgreSQL's pg_blocking_pids() function for accurate blocking identification
Lock Hierarchy Visualization: Complete blocking chains and process relationships
Comprehensive Metrics: Process details, wait events, timing, lock types, and affected relations
Intelligent Recommendations: Severity-based suggestions with specific optimization guidance
Production Ready: Designed for enterprise database monitoring and performance troubleshooting
📋 Analysis Output:
Process Information: PID, user, application name, client address, and connection details
Query Context: Full query text, execution timing, and resource consumption
Lock Details: Lock types, modes, affected database objects, and wait events
State Analysis: Process states, wait information, and blocking duration
Trend Analysis: Summary statistics and pattern recognition
Categorized Recommendations: 🚨 Critical, ⚠️ Warning, 💡 Optimization, 🎯 Hotspot alerts
🔧 PostgreSQL Compatibility:
Minimum: PostgreSQL 9.6+ (requires pg_blocking_pids() function)
Recommended: PostgreSQL 12+ (enhanced lock monitoring features)
Optimal: PostgreSQL 14+ (includes pg_locks.waitstart for precise wait timing)
Comprehensive maintenance planning with bloat detection
The analyze_vacuum_requirements tool provides:
📈 Bloat Analysis: Table and index bloat detection with severity assessment
⚙️ Autovacuum Configuration: Settings analysis and optimization recommendations
📊 Performance Impact: Vacuum operation performance analysis and bottleneck identification
🗓️ Maintenance Planning: Intelligent scheduling recommendations based on workload patterns
🚨 Critical Issue Detection: Immediate attention alerts for maintenance-related problems
⚡ Configuration Optimization: Tuning suggestions for vacuum parameters
Advanced dependency mapping and visualization
The analyze_schema_relationships tool offers:
🔗 Dependency Mapping: Complete inter-schema relationship visualization
📊 Coupling Analysis: Schema coupling metrics and isolation scoring
🎯 Impact Assessment: Change impact analysis for schema modifications
📈 Relationship Quality: Foreign key relationship quality and consistency scoring
🔍 Pattern Detection: Common anti-patterns and architectural recommendations
AI-powered index recommendations with advanced algorithms
Database Tuning Advisor (DTA) Features:
🧠 Pareto Optimization: Multi-objective optimization balancing performance and storage
📊 Workload Analysis: Pattern recognition from pg_stat_statements data
💰 Cost-Benefit Analysis: Storage budget constraints with performance impact assessment
🎯 Query-Specific Tuning: Targeted optimization for specific query sets
⏱️ Time-bounded Analysis: Anytime algorithm with configurable runtime limits
LLM-Powered Optimization:
🤖 Intelligent Analysis: Natural language understanding of query patterns
📝 Contextual Recommendations: Human-readable explanations with implementation guidance
🔍 Advanced Pattern Recognition: Complex query pattern detection and optimization
PostgreSQL 9.6+ (PostgreSQL 12+ recommended, 14+ optimal)
Python 3.8+
Optional: HypoPG extension for hypothetical index analysis
Create a .env file in the project root:
DATABASE_URI=postgresql://username:password@localhost:5432/database_name# Start the MCP server (default: stdio transport, unrestricted mode)
./start.sh
# Start in read-only mode for safer analysis
./start.sh --access-mode restricted
# Start with SSE transport for web integration
./start.sh --transport sse --sse-port 8099
# Start SSE server accessible externally
./start.sh --transport sse --sse-host 0.0.0.0 --sse-port 8099
# Show all available options
./start.sh --help# Start with Docker Compose
docker-compose up -d
# View logs
docker-compose logs -f postgres-mcp# Terminal 1: Start the MCP server with SSE transport
./start.sh --transport sse --sse-port 8099
# Terminal 2: Start the MCP Inspector (opens web interface)
./start-inspector.shThe MCP Inspector provides:
Interactive Tool Testing: Test all database analysis tools with a web UI
Parameter Exploration: Discover tool capabilities and configuration options
Real-time Results: View formatted analysis results in a user-friendly interface
Documentation: Built-in tool documentation and usage examples
Unrestricted Mode (Default):
Full SQL execution capabilities
Database modification operations
Complete administrative access
Restricted Mode (Recommended for analysis):
Read-only operations with safety controls
SQL injection protection
Timeout enforcement (30s default)
Safe for production analysis
# Show help and configuration options
./start.sh --help
# Start with default settings (stdio, unrestricted)
./start.sh
# Start in production-safe mode
./start.sh --access-mode restricted
# Start web server for HTTP/SSE integration
./start.sh --transport sse --sse-port 8099# Comprehensive health analysis (via MCP client)
analyze_db_health --health-type all
# Specific component checks
analyze_db_health --health-type index,vacuum,buffer
# Performance optimization workflow
get_top_queries --sort-by resources
analyze_workload_indexes --method dta --max-index-size-mb 1000
get_blocking_queriespostgres-mcp/
├── 🔧 server.py # MCP server & tool registration
├── 📊 database_health/ # Multi-dimensional health monitoring
├── ⚡ explain/ # Query execution plan analysis
├── 🎯 index/ # AI-powered index optimization
├── 📈 top_queries/ # Performance query analysis
├── 🔒 blocking_queries.py # Lock contention analysis
├── 🔍 database_overview.py # Comprehensive assessment
├── 🗺️ schema_mapping.py # Relationship visualization
├── 🧹 vacuum_analysis.py # Maintenance optimization
└── 🛡️ sql/ # SQL execution frameworkIndex Health: Invalid, duplicate, bloated, and unused index detection
Connection Health: Connection utilization and capacity analysis
Vacuum Health: Transaction wraparound and maintenance monitoring
Sequence Health: Sequence exhaustion and overflow protection
Replication Health: Lag monitoring and slot management
Buffer Health: Cache hit rate optimization for tables and indexes
Constraint Health: Invalid constraint detection and remediation
Database Tuning Advisor (DTA):
Pareto-optimal index selection algorithm
Multi-query workload optimization
Budget-constrained recommendation engine
Time-bounded analysis with anytime approach
LLM-Powered Analysis:
Natural language query pattern understanding
Contextual optimization recommendations
Human-readable explanations and guidance
Advanced pattern recognition capabilities
✅ Comprehensive Tool Analysis: Detailed analysis document with improvement recommendations
✅ Enhanced Readability: Streamlined code formatting across all modules
✅ Robust Error Handling: Improved None value handling in vacuum analysis
✅ Advanced Visualizations: Enhanced blocking queries analysis with detailed recommendations
✅ Human-Readable Outputs: Refactored analysis tools for better text presentation
✅ Schema Relationship Mapping: New schema dependency analysis and visualization
✅ Docker Integration: Complete containerization with Docker Compose support
✅ Vacuum Analysis Tool: Comprehensive maintenance recommendations and bloat detection
Modular Design: Enhanced component separation and reusability
Async Optimization: Improved performance with better async patterns
Safety Framework: Comprehensive SQL execution safety controls
Error Recovery: Robust error handling and graceful degradation
Performance Scaling: Optimized for large database analysis
Enhanced Startup Scripts: Flexible configuration with comprehensive validation and help system
Database Tools Analysis: Comprehensive analysis of all tools with improvement recommendations
Tool Improvements Roadmap: Priority-based enhancement roadmap (if available)
Technical Implementation: Detailed code documentation and API references
Custom Health Checks: Add domain-specific health monitoring
Plugin Architecture: Extend with custom analysis tools
Integration APIs: Connect with external monitoring systems
Custom Visualizations: Add specialized reporting and dashboards
SQL Injection Protection: Comprehensive input sanitization
Access Mode Controls: Restricted/unrestricted operation modes
Timeout Enforcement: Configurable query timeout protection
Parameter Validation: Robust input validation and sanitization
Error Handling: Secure error reporting without information leakage
Use restricted mode for production analysis
Configure appropriate timeout values for large operations
Monitor resource usage during analysis operations
Implement regular health checks for proactive monitoring
Review security configurations and user permissions regularly
MIT License
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose whether the tool is read-only, requires special permissions, or has any side effects. It only describes the checks but lacks safety and behavioral context.
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 front-loaded with the main purpose and uses a bulleted list for clarity. While slightly verbose, it is well-structured and each sentence provides value.
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 tool with a single optional parameter and no output schema, the description adequately covers what the tool does and the available health checks. It could mention output format or prerequisites, but it's reasonably complete.
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 has 100% coverage with a description listing valid values. The tool description adds significant meaning by explaining each health check option (index, connection, etc.), which goes beyond the schema's minimal description.
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 'Analyzes database health' and lists specific health checks, making the tool's purpose very explicit. It distinguishes itself from siblings like analyze_query_indexes by focusing on overall database health rather than specific query or index analysis.
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 guidance on how to use the optional health_type parameter, including default behavior and valid values. However, it does not explicitly contrast this tool with sibling tools or specify when to use it over alternatives.
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 |
|---|---|---|---|
| queries | Yes | List of Query strings to analyze | |
| max_index_size_mb | No | Max index size in MB | |
| method | No | Method to use for analysis | dta |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It fails to disclose if the tool is read-only, what happens on invalid input, authentication needs, or output format. The only behavioral hint is the 10-query limit, leaving significant gaps.
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 sentence that is front-loaded with the verb and resource, containing no filler or redundant information. Every word contributes to clarity.
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 moderate complexity (3 parameters, no output schema), the description covers the core purpose and the 10-query limit. However, it does not explain what 'recommend optimal indexes' means in practice (e.g., output format, whether it returns DDL), which is a notable gap for a recommendation 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 baseline is 3. The description adds value by specifying the 'up to 10' constraint for the queries parameter, which is not present in the schema's description. This enhances the semantic understanding beyond the schema alone.
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: analyze a list of SQL queries (up to 10) and recommend optimal indexes. This distinguishes it from siblings like analyze_workload_indexes, which likely targets entire workloads.
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 via the 'up to 10' constraint, suggesting it's for ad-hoc analysis of a small query set, but it does not explicitly state when to use this tool versus alternatives like analyze_workload_indexes or explain_query. No exclusion criteria 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.
Analyze schema relationships and dependencies with visual representation
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'visual representation', hinting at output format, but doesn't specify what that entails (e.g., graph, diagram, text), whether it's read-only or has side effects, or any performance or permission requirements. This leaves significant gaps for a tool with potential complexity in analysis.
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, efficient sentence that directly states the tool's function. It's front-loaded with the core purpose and avoids unnecessary words, though it could be slightly more structured by elaborating on the 'visual representation' aspect to enhance clarity without losing 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 has 0 parameters and no output schema, the description is minimally complete but lacks depth. It hints at output ('visual representation') but doesn't detail what that means, and with no annotations, it fails to cover behavioral aspects like safety or performance. For an analysis tool, this leaves the agent with insufficient context to fully understand its use.
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 0 parameters, with 100% schema description coverage, so there's no need to compensate for undocumented inputs. The description doesn't add parameter details beyond the schema, but with no parameters, a baseline of 4 is appropriate as it avoids confusion and aligns with the empty input structure.
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 as 'Analyze schema relationships and dependencies with visual representation', specifying the verb 'analyze' and the resource 'schema relationships and dependencies'. It distinguishes from siblings like 'list_schemas' or 'get_object_details' by focusing on analysis rather than listing or retrieval, though it doesn't explicitly differentiate from other analysis tools like 'analyze_db_health'.
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 prerequisites, context, or exclusions, and with siblings like 'list_schemas' and 'analyze_db_health', there's no indication of when this specific analysis tool is preferred over others for understanding schema structures.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comprehensive vacuum analysis with maintenance recommendations and bloat detection
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'analysis' implies a read-only operation, the description doesn't explicitly state whether this is a safe read operation or if it has any side effects. It mentions 'maintenance recommendations' but doesn't clarify if these are just suggestions or if any actions are taken. For a tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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, efficient sentence that communicates the core functionality. It's appropriately sized for a tool with no parameters. While it could potentially be more specific about what 'comprehensive' entails, the description doesn't waste words and gets straight to the point.
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 complexity of database analysis tools and the lack of both annotations and output schema, the description is insufficient. It doesn't explain what format the analysis results will take, what 'bloat detection' specifically means, or what kind of maintenance recommendations are provided. For a tool that presumably returns detailed analysis results, the description should provide more context about the output format and scope.
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 0 parameters with 100% schema description coverage, so there's no parameter documentation burden. The description appropriately doesn't discuss parameters since none exist. The baseline for 0 parameters is 4, as there's no need to compensate for missing 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 states the tool performs 'comprehensive vacuum analysis' with 'maintenance recommendations and bloat detection', which gives a general sense of purpose. However, it doesn't clearly distinguish this from sibling tools like 'analyze_db_health' or 'analyze_query_indexes' - all seem to be analysis tools for database optimization. The description lacks a specific verb+resource combination that would differentiate it from similar analysis tools.
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. With multiple analysis tools available (analyze_db_health, analyze_query_indexes, analyze_schema_relationships, analyze_workload_indexes), there's no indication of when vacuum analysis is appropriate versus other types of database analysis. No prerequisites, exclusions, or alternative recommendations are mentioned.
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 |
|---|---|---|---|
| max_index_size_mb | No | Max index size in MB | |
| method | No | Method to use for analysis | dta |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of disclosure. It states the tool 'recommends' indexes but does not clarify whether it is read-only, what permissions are needed, or if it modifies the database. The output format or side effects are not mentioned.
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 with no wasted words. It is front-loaded with the key action. However, it could be slightly more structured by including the output or usage hints.
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 lack of output schema, the description does not explain what the recommendation looks like (e.g., list of indexes, DDL statements). The tool is moderately complex with sibling tools, but the description leaves gaps about the output and scope of analysis.
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 coverage is 100% with both parameters having descriptions (method enum and max index size). The tool description does not add any additional meaning beyond what the schema already provides, so a 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 verb 'analyze' and 'recommend' along with the resource 'frequently executed queries' and 'optimal indexes'. It effectively distinguishes this tool from siblings like 'analyze_query_indexes' (which likely focuses on individual queries) and 'get_top_queries' (listing without recommendations).
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 workload-level index analysis but does not explicitly state when to use this tool versus alternatives such as 'analyze_query_indexes' or 'get_top_queries'. No when-not or exclusion conditions are mentioned.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fails to disclose critical behavioral traits. With no annotations, the description should clarify that executing arbitrary SQL can modify or delete data, pose security risks, or require elevated permissions. The vague 'Execute any SQL query' leaves the agent unaware of potential destructive side effects.
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 extremely concise (4 words), which is appropriate for a simple tool. However, it sacrifices necessary detail, making it less useful. The structure is acceptable but would benefit from a brief mention of scope or limitations.
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 high potential for side effects (executing any SQL), the description is dangerously incomplete. It lacks information about return values, error handling, isolation level, or whether modifications are committed. Without an output schema or annotations, the description must compensate, but it fails to do so.
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 covers 100% of parameters, but the description adds no meaning beyond 'SQL to run.' The default value 'all' is unexplained and potentially misleading. The description should specify that the parameter expects a complete SQL statement, possibly including constraints like semicolons or transaction boundaries.
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 action and resource, but is overly generic. It does not distinguish from sibling tools like explain_query or analyze_db_health, which also interact with SQL queries. A more specific purpose (e.g., 'Execute arbitrary SQL statements on the connected database') would improve clarity.
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. For example, it does not caution against using it for read-only analysis when explain_query might be safer. There is no mention of prerequisites or conditions (e.g., 'Use only if you need to modify data; otherwise prefer read-only tools').
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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden for behavioral disclosure. It does not mention that the 'analyze' parameter actually runs the query, which is a critical behavioral trait. The schema covers this but the description itself adds no 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?
Single sentence that efficiently conveys the core purpose and one key output detail (cost estimates). No superfluous 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?
Lacks explicit output schema information; the description gives a general sense of output but could be more complete about the exact format. Given the sibling tools, more differentiation could improve completeness.
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 schema already thoroughly documents all parameters. The tool description adds no additional parameter meaning, meeting the baseline for high coverage.
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 explains execution plans with cost estimates, using a specific verb and resource. It distinguishes from siblings like execute_sql, though could be more explicit about when to use.
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 on when to use this tool versus the alternatives such as execute_sql or analyze_query_indexes. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comprehensive blocking queries analysis with lock information, hierarchy, and recommendations
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions 'comprehensive blocking queries analysis,' it doesn't describe what this entails operationally—such as whether it requires specific database permissions, if it's read-only or has side effects, how it handles large datasets, or what the output format looks like. For a tool with zero annotation coverage, this is insufficient.
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, efficient sentence: 'Get comprehensive blocking queries analysis with lock information, hierarchy, and recommendations.' It's front-loaded with the core purpose and includes key details without unnecessary elaboration. Every word earns its place, making it highly concise and well-structured.
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 complexity implied by 'comprehensive analysis' and the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'blocking queries analysis' means in practice, what the recommendations entail, or how the results should be interpreted. For a tool that likely returns detailed database diagnostics, this leaves too much ambiguity for effective use.
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 0 parameters, and the schema description coverage is 100%, so there's no need for parameter documentation in the description. The baseline for this scenario is 4, as the description appropriately doesn't waste space on non-existent parameters, though it doesn't add value beyond the schema (which already fully covers the lack of parameters).
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: 'Get comprehensive blocking queries analysis with lock information, hierarchy, and recommendations.' It specifies the verb ('Get') and resource ('blocking queries analysis') with additional details about what the analysis includes. However, it doesn't explicitly differentiate from sibling tools like 'analyze_db_health' or 'get_top_queries,' which prevents a score of 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. With sibling tools like 'analyze_db_health,' 'get_top_queries,' and 'execute_sql,' there's no indication of when this specific blocking queries analysis is appropriate, what prerequisites might exist, or when other tools should be used instead. This lack of contextual guidance is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comprehensive database overview with performance and security analysis
| Name | Required | Description | Default |
|---|---|---|---|
| max_tables | No | Maximum number of tables to analyze per schema | |
| sampling_mode | No | Use statistical sampling for large datasets | |
| timeout | No | Maximum execution time in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Get' implies a read operation, the description doesn't address critical behavioral aspects like whether this is a heavy operation (given performance analysis), whether it requires specific permissions, potential impact on database performance, or what the output format looks like. The mention of 'comprehensive' analysis hints at scope but lacks operational details.
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, efficient sentence that clearly communicates the core purpose. Every word earns its place - 'comprehensive' sets scope, 'database overview' specifies the resource, and 'performance and security analysis' clarifies the analysis dimensions. There's no wasted verbiage or redundancy.
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 tool that performs 'comprehensive database overview' with performance and security analysis, the description is insufficient. There's no output schema, and with no annotations, the description doesn't address what information is returned, how extensive the analysis is, whether this is a resource-intensive operation, or how it differs from similar analysis tools. The agent lacks critical context for proper tool invocation and result interpretation.
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 has 100% description coverage, providing clear documentation for all three parameters (max_tables, sampling_mode, timeout). The description doesn't add any meaningful parameter semantics beyond what's already in the schema - it doesn't explain how these parameters affect the 'comprehensive overview' or their practical implications. This meets the baseline for high schema coverage.
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: 'Get comprehensive database overview with performance and security analysis'. It specifies the verb ('Get') and resource ('database overview') with additional scope ('performance and security analysis'). However, it doesn't explicitly differentiate from sibling tools like 'analyze_db_health' or 'get_object_details', which prevents a perfect score.
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. With multiple sibling tools focused on database analysis (e.g., analyze_db_health, analyze_query_indexes), there's no indication of what makes this tool distinct or when it should be preferred over others. This leaves the agent without context for tool selection.
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 |
|---|---|---|---|
| schema_name | Yes | Schema name | |
| object_name | Yes | Object name | |
| object_type | No | Object type: 'table', 'view', 'sequence', or 'extension' | table |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose any behavioral traits beyond the basic purpose (e.g., read-only, required permissions, side effects). Minimal 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 a single sentence, which is concise. However, it could be more precise by specifying what 'detailed information' includes. Still, no wasted words.
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 no output schema and no description of what 'detailed information' entails (columns, constraints, etc.), the description is incomplete for a details tool. Complexity is low, but more context is needed.
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 coverage is 100% with parameter descriptions that are minimal but sufficient. The description adds no additional meaning beyond the schema. Baseline 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 uses a specific verb 'Show' and resource 'detailed information about a database object'. It clearly distinguishes from siblings like list_objects (which likely lists objects) and analyze_* tools.
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 explicit when-to-use or alternative guidance is provided, but the tool's purpose is straightforward enough. A score of 4 reflects the lack of explicit guidelines despite the clear 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 |
|---|---|---|---|
| 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 |
| limit | No | Number of queries to return when ranking based on mean_time or total_time |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions reliance on the pg_stat_statements extension, which is a key dependency, but does not state whether the operation is read-only, requires special permissions, or has side effects. The term 'reports' implies read, but more detail would improve 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 a single sentence that conveys the core purpose without redundancy. It is appropriately concise and front-loaded, wasting no words.
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 no output schema, the description should explain what the tool returns (e.g., list of queries with metrics). It omits this, leaving the agent uncertain about output format. It also does not clarify what 'resource-intensive' means (e.g., which metrics). The description is insufficient for a tool with 2 parameters and no output 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%, so the baseline is 3. The tool description does not add any information about parameters beyond what the schema already provides. The schema itself is clear, but the description misses the opportunity to explain how limit and sort_by interact or give examples.
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 reports slowest or most resource-intensive queries using pg_stat_statements, which distinguishes it from siblings like analyze_query_indexes or execute_sql. The verb 'reports' and resource 'queries' with specific scope make the purpose unambiguous.
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 on when to use this tool versus siblings. The description implies usage for top queries but does not explicitly state when not to use it or which alternative to choose (e.g., analyze_query_indexes for index analysis). The agent must infer context from the tool name alone.
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 |
|---|---|---|---|
| schema_name | Yes | Schema name | |
| object_type | No | Object type: 'table', 'view', 'sequence', or 'extension' | table |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility for behavioral disclosure. It only states 'List objects' without indicating read-only nature, idempotency, authentication needs, or any side effects.
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 very concise at five words, front-loaded with the verb and resource. While it lacks detail, it is not verbose and every word serves a purpose.
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 too minimal for this simple tool. It does not specify what 'objects' includes (tables, views, etc.) or what the output contains. Without an output schema, the agent lacks sufficient context to fully understand the tool's return value.
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 coverage is 100% with each parameter having a description. The tool description adds no additional meaning beyond what the schema already provides, so 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 'list objects' and the scope 'in a schema'. It is specific enough to understand the tool's purpose, but it does not explicitly differentiate from sibling tools like 'list_schemas' or 'get_object_details'.
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. It does not mention exclusions, prerequisites, or provide context for selection among the listed sibling tools.
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 | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. As a simple read-only listing, the description is adequate but does not explicitly state it is non-destructive or clarify return behavior (e.g., returns schema names only).
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?
Single sentence, clearly front-loaded with verb and resource, no wasted words.
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 zero-parameter, read-only listing tool without output schema, the description is complete. It sufficiently informs the agent of its function.
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?
Tool has 0 parameters and schema description coverage is 100% (empty). No parameter information needed; baseline score 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?
Description clearly states 'List all schemas in the database' with a specific verb (List) and resource (schemas). It inherently distinguishes from sibling tools that list other entities like relations or objects.
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 on when to use this tool versus alternatives such as list_relations or list_objects. The description does not provide context or exclusions.
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.
v1.0.0analyze_db_healthanalyze_query_indexesanalyze_schema_relationshipsanalyze_vacuum_requirementsanalyze_workload_indexesexecute_sqlexplain_queryget_blocking_queriesget_database_overviewget_object_detailsget_top_querieslist_objectslist_schemasScored across 13 tools
Most tools have distinct purposes, but there is some overlap between analyze_query_indexes and analyze_workload_indexes, both focusing on index recommendations, which could cause confusion. However, their descriptions clarify that one analyzes specific queries while the other analyzes frequently executed queries, helping to differentiate them.
The naming follows a consistent verb_noun pattern (e.g., analyze_db_health, execute_sql, list_schemas) with minor deviations like get_blocking_queries and get_database_overview using 'get' instead of 'list' or 'analyze'. Overall, the pattern is predictable and readable.
With 13 tools, the count is well-scoped for a Postgres database management server, covering analysis, execution, and listing functions. Each tool appears to serve a specific purpose without feeling excessive or insufficient for the domain.
The tool set provides comprehensive coverage for Postgres database management, including health analysis, query optimization, schema exploration, and SQL execution. There are no obvious gaps; it supports CRUD-like operations and lifecycle management through tools like execute_sql and various analysis functions.
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Comprehensive PostgreSQL documentation and best practices, including ecosystem tools
Generate, fix, explain and run read-only SQL on PostgreSQL, MySQL and SQL Server
