Provides tools for executing SQL queries, listing schemas, tables, and databases, describing table structure, and getting database connection status and statistics.
Click on "Install 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., "@PostgreSQL SSH MCP Server show me a list of all tables"
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.
A secure PostgreSQL MCP server with built-in SSH tunneling. Connect to databases through bastion hosts automatically — no manual ssh -L required.
Dual Transport — STDIO for Claude Desktop, Streamable HTTP for ChatGPT
SSH Tunneling — Built-in tunnel with auto-reconnect and TOFU (trust on first use)
Read-Only by Default — Safe for production; enable writes explicitly
OAuth Support — Auth0 integration for secure ChatGPT connections
Connection Pooling — Efficient resource management with configurable limits
Related MCP server: @pilat/mcp-datalink
Add to your Claude Desktop config:
Platform | Config Location |
macOS |
|
Windows |
|
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@zlash65/postgresql-ssh-mcp"],
"env": {
"DATABASE_URI": "postgresql://user:password@localhost:5432/mydb"
}
}
}
}DATABASE_URI="postgresql://user:pass@localhost:5432/mydb" npx @zlash65/postgresql-ssh-mcp-httpThen configure ChatGPT to connect to https://your-subdomain.example.com/mcp.
Note: ChatGPT requires HTTPS. Use a tunnel (ngrok, Cloudflare Tunnel) for local testing.
Tool | Description |
| Execute SQL with parameterized queries. Results capped by |
| Get EXPLAIN plans in text, JSON, YAML, or XML format. Supports ANALYZE. |
Tool | Description |
| List database schemas. Excludes system schemas by default. |
| List tables with row counts and sizes. Optionally include views. |
| Get columns, constraints, and indexes for a table. |
| List all databases with owner, encoding, and size. |
Tool | Description |
| Get pool stats, tunnel state, and connection info. |
| Show active connections from |
| Find queries running longer than a threshold. |
| Get PostgreSQL server version. |
| Get database size and largest tables. |
| Get vacuum/analyze stats and scan counts for a table. |
Variable | Required | Default | Description |
| Yes* | — | Full connection string (e.g., |
| Yes* | — | Database hostname |
| No |
| Database port |
| Yes* | — | Database name |
| Yes* | — | Database username |
| Yes* | — | Database password |
*Either DATABASE_URI or all individual connection variables are required.
Variable | Default | Description |
| Auto |
|
| — | Path to CA certificate bundle |
|
| Set |
Variable | Required | Default | Description |
| No |
| Set |
| Yes* | — | SSH server hostname |
| No |
| SSH server port |
| Yes* | — | SSH username |
| Yes** | — | Path to private key file |
| No | — | Passphrase for encrypted keys |
| Yes** | — | SSH password (alternative to key) |
| No |
| Verify host key against known_hosts |
| No |
| Auto-add unknown hosts (when strict is enabled) |
| No |
| Custom known_hosts file |
| No |
| Keepalive interval in milliseconds |
| No |
| Max reconnect attempts ( |
*Required when SSH_ENABLED=true
**Either SSH_PRIVATE_KEY_PATH or SSH_PASSWORD is required
Variable | Default | Description |
|
| Block data modifications. Set |
|
| Maximum rows returned per query |
|
| Query timeout in milliseconds |
|
| Maximum concurrent queries |
|
| Timeout for draining pool during reconnect |
Variable | Default | Description |
|
| HTTP server port |
|
| HTTP server bind address |
|
| Authentication mode: |
|
| Stateless mode (each request re-initializes) |
|
| Server instances for stateless mode |
|
| Session TTL for stateful mode |
|
| Session cleanup interval |
| — | Comma-separated allowed CORS origins ( |
| — | Comma-separated allowed Host headers |
Variable | Required | Description |
| Yes* | Auth0 tenant domain (e.g., |
| Yes* | Auth0 API identifier / audience |
| No | URL to API documentation (RFC 9728) |
*Required when MCP_AUTH_MODE=oauth
Guide | Description |
Claude Desktop and local development | |
HTTP server setup and configuration | |
Deploy to production with nginx and SSL | |
Complete Auth0 OAuth setup for ChatGPT |
docker build --target runtime -t postgresql-mcp .
docker run -e DATABASE_URI="postgresql://..." postgresql-mcpdocker build --target runtime-http -t postgresql-mcp-http .
docker run -p 3000:3000 -e DATABASE_URI="postgresql://..." postgresql-mcp-http# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Type check
npm run typecheck
# Lint
npm run lintDescribe a table (columns, constraints, indexes).
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Schema name (default: public) | public |
| table | Yes | Table name to describe |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states that it describes columns, constraints, and indexes, but does not mention that the operation is read-only, any required permissions, or potential side effects. The lack of behavioral context is a significant gap.
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 provides necessary information without excess. However, it is minimal and could benefit from slight expansion for 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 that an output schema exists (so return values are covered elsewhere) and the parameters are well-documented in the input schema, the description adequately covers the main aspects of the tool. It mentions columns, constraints, and indexes, which is sufficient for a describe 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?
Schema description coverage is 100%, with both parameters already described in the input schema. The description adds no additional meaning beyond what is in the schema, so baseline score 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 'Describe a table (columns, constraints, indexes)' clearly states the verb 'describe' and the resource 'table', and distinguishes the tool from siblings like list_tables (which only lists names) or execute_query (which runs arbitrary SQL).
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 does not provide explicit guidance on when to use this tool versus alternatives like list_tables or execute_query. Usage is implied by the purpose, but no when-to-use or when-not-to-use context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute SQL with optional parameters. Results are capped by MAX_ROWS and include a truncated flag.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL to execute | |
| params | No | Parameters for $1, $2, ... |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds value by mentioning results are capped by MAX_ROWS and include a truncated flag, but lacks disclosure on write capabilities or authorization needs. Since annotations are absent, description carries full burden but only partially meets it.
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?
Two concise sentences, front-loaded with the primary action, no fluff.
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?
Missing critical context like whether queries are read-only or can modify data, or any prerequisites. Output schema exists but description does not leverage it enough to inform the agent of full behavior.
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%, so parameters are well-documented. The description adds only the word 'optional' which does not enhance meaning beyond 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?
Clearly states 'Execute SQL' which specifies verb and resource. Does not explicitly distinguish from siblings like explain_query or describe_table, but the action is distinct enough.
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 or avoid this tool. Lacks mention of alternatives or context like read-only vs. modification queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return an EXPLAIN plan for a query. ANALYZE executes the query.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL query to explain | |
| analyze | No | Run EXPLAIN ANALYZE (executes the query). Limited in read-only mode. | |
| format | No | Output format for the execution plan | text |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that ANALYZE executes the query, a key behavioral trait. However, lacks details on side effects, authorization needs, or limitations (e.g., read-only mode noted in schema but not description). Without annotations, more context is expected.
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?
Extremely concise at two sentences with front-loaded main purpose. No redundant wording, every word earns its place.
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?
Covers core purpose and a critical side effect. However, missing context on when to use vs siblings, and no mention of format or analyze implications beyond execution. Given an output schema exists, return values are covered, but usage context is incomplete.
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 descriptions for all parameters. The description adds value by explaining the 'analyze' parameter's execution side effect, which is not fully captured in schema. For 'format' and 'sql', it relies on schema, which is adequate.
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 it returns an EXPLAIN plan for a query, using specific verb+resource. It distinguishes from sibling tools like execute_query by hinting at planning versus execution, though it does not explicitly differentiate.
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 over alternatives like execute_query or describe_table. No context about prerequisites or typical scenarios is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get connection status, pool stats, and tunnel state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It does not disclose behavioral traits like read-only nature, auth requirements, or side effects. Simply lists outputs without safety 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?
Single sentence, concise without waste. Front-loaded action verb. Could be slightly more structured but effectively brief.
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?
Output schema exists, so return details are covered. Tool is simple with 0 params, but description misses context like cost or prerequisites, especially given no annotations. Adequate but not thorough.
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?
No parameters exist; schema coverage is 100%. Description adds value by specifying the categories of returned data (status, stats, state), which is informative beyond the empty 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 clearly states the tool retrieves 'connection status, pool stats, and tunnel state' with a specific verb and resource. It distinguishes from siblings like list_active_connections by including pool and tunnel state.
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 guidance on when to use this tool versus siblings. Implied for general status checking, but lacks when-not-to-use or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get database size and largest tables.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of largest tables to return (default: 10) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose any behavioral traits such as side effects, permissions, or performance impact. Only states the action without safety 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?
Extremely concise and front-loaded single sentence with no wasted words; every part is informative.
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 only one optional parameter and an output schema exists, description covers the core behavior well. Could mention result format, but output schema likely handles that.
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 has 100% coverage for the limit parameter; description adds no additional meaning beyond what schema provides, so baseline score 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?
Description clearly states the verb 'Get' and resources 'database size and largest tables', distinguishing it from sibling tools like get_database_version or get_table_stats.
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; lacks context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get PostgreSQL server version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry behavioral transparency. The description is minimal and does not disclose traits like permissions needed, response format, or side effects. However, as a simple read-only query with no parameters, the behavior is straightforward, earning a middle score.
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 conveys the tool's purpose. There is no wasted text, and the structure is optimally front-loaded for quick parsing by an AI agent.
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 (no parameters) and the presence of an output schema, the description is nearly complete. It could explicitly mention the return type (e.g., 'returns a version string'), but the output schema likely covers that, making the description adequate.
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 schema coverage is 100%. The description adds no parameter details, which is acceptable. Baseline for no parameters is 4, and no additional information is needed beyond what the schema already conveys.
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 'Get PostgreSQL server version,' which is a specific verb-resource pair. It distinguishes itself from sibling tools that deal with tables, queries, databases, etc., making it easy to select for version retrieval.
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. Context signals indicate sibling tools like get_connection_status or list_databases, but the description does not explain when version retrieval is appropriate (e.g., for compatibility checks).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get table statistics (rows, vacuum/analyze, scan counts).
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Schema name (default: public) | public |
| table | Yes | Table name |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It fails to disclose whether the tool is read-only, requires authentication, or has any side effects. The description only lists stat types, missing 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 a single, focused sentence that front-loads the main purpose. Every word earns its place; no unnecessary 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?
Given the simple two-parameter tool and presence of an output schema, the description adequately conveys the tool's function. However, it could benefit from mentioning that stats are returned in a structured format or linking to related tools.
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 descriptions for both parameters (schema default and table name required). The description adds general context about returned stats but does not enhance parameter-specific meaning beyond what the schema provides.
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 retrieves statistics like rows, vacuum/analyze, and scan counts. It distinguishes from siblings like 'describe_table' and 'list_tables' by focusing on specific statistics rather than schema or table listing.
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 is implied by the name and description, but there is no explicit guidance on when to use this tool over alternatives like 'describe_table' or 'list_tables'. The context is clear but lacks when-not-to-use criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active connections from pg_stat_activity.
| Name | Required | Description | Default |
|---|---|---|---|
| includeIdle | No | Include idle connections in the listing |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only mentions the source view but does not state default behavior (excluding idle connections), performance impact, permissions required, or return format. The schema parameter description hints at idle filtering, but the main description lacks this detail.
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 key action. It is efficient but could benefit from slightly more detail without becoming verbose.
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 (1 parameter, output schema exists), the description provides the essential purpose but lacks usage guidance and behavioral transparency. It is minimally complete but has clear gaps.
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 a clear parameter description for 'includeIdle'. The main description does not add additional meaning beyond the schema, so baseline 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 'List', the resource 'active connections', and the source 'pg_stat_activity'. It distinguishes itself from sibling tools like 'list_long_running_queries' which focuses on long-running queries, and 'get_connection_status' which is about a specific connection's status.
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 does not explicitly provide guidance on when to use this tool versus alternatives. It implicitly suggests filtering out idle connections by default via the includeIdle parameter, but does not compare with siblings or mention prerequisites or context of use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List databases with owner, encoding, and size.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 states a read-only operation ('list'), but lacks details on performance, authorization needs, or pagination behavior. For a simple listing tool with no parameters, this is adequate but not rich.
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 key purpose and included fields. It is front-loaded and concise, though could be slightly more 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 tool has no parameters and an output schema exists, the description sufficiently states what the tool returns. However, it does not clarify scope (e.g., all databases or filtered) or any edge cases.
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 no parameters, and schema description coverage is 100% (trivially). Per guidelines, baseline is 4 for zero parameters. The description adds no further parameter semantics, which is acceptable.
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') and resource ('databases'), and specifies the fields returned ('owner, encoding, and size'). This clearly distinguishes it from sibling tools like list_tables or list_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?
No guidance on when to use this tool versus alternatives (e.g., list_tables or list_schemas). The description implies context but does not provide explicit usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List queries running longer than a threshold.
| Name | Required | Description | Default |
|---|---|---|---|
| minDurationSeconds | No | Minimum duration in seconds (default: 5) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits, but it only states the basic action. It does not explain what happens when no queries meet the threshold, whether system queries are included, or what the output list contains. This is a critical gap for a query listing tool.
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 but lacks necessary detail. It is front-loaded but too brief to be effective; every sentence should earn its place, and this one barely provides enough 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?
Given the presence of an output schema, the description could rely on it for return values, but it still fails to explain the purpose of the tool in the broader context (e.g., performance monitoring). The threshold concept is only implied, and the tool's integration with other database tools is not mentioned.
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 the parameter minDurationSeconds having a clear description and default. The tool description adds no extra meaning beyond the schema, so the baseline 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 queries') and the condition ('running longer than a threshold'), distinguishing it from other list tools like list_tables or list_active_connections. However, it could be more specific about the scope (e.g., 'on the current database') to fully differentiate from potential sibling 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 guidance is provided on when to use this tool versus alternatives like list_active_connections or execute_query. There is no mention of context (e.g., monitoring performance, troubleshooting) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List schemas (excludes system schemas by default).
| Name | Required | Description | Default |
|---|---|---|---|
| includeSystem | No | Include system schemas (pg_*, information_schema) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full disclosure burden. It reveals the key behavioral trait of excluding system schemas by default, but omits other potential behaviors such as permission requirements, error handling, or response format. The presence of an output schema partially compensates.
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 with no superfluous information. It efficiently conveys the tool's purpose and key default behavior.
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 listing tool with one optional parameter and an existing output schema, the description is largely complete. It covers the default filtering behavior, but could optionally mention that the output schema provides schema details.
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 already describes the 'includeSystem' parameter. The description adds value by explaining that system schemas are excluded by default, giving semantic context to the parameter's default and effect.
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 lists schemas, with the notable default exclusion of system schemas. This distinguishes it from sibling tools like list_tables (lists tables) and describe_table (describes a specific table).
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 explicit guidance on when to use this tool versus alternatives. It merely states its function, leaving the agent to infer appropriate usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tables in a schema with estimated row counts and sizes.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Schema name (default: public) | public |
| includeViews | No | Include views in the listing |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool returns estimated row counts and sizes, indicating a read operation. However, it does not mention any potential side effects or limitations, but for a listing tool this is acceptable.
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 effectively communicates the core functionality. It is front-loaded with the action and resource, though it could benefit from additional context like parameter roles.
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 (two optional parameters) and the presence of an output schema, the description is complete enough. It informs the agent of the tool's purpose and return content without requiring further elaboration.
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 both parameters. The description adds no additional meaning beyond what the schema provides, 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 it lists tables in a schema, distinguishing it from siblings like describe_table which details a single table. The addition of 'estimated row counts and sizes' further specifies the output, making 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 is provided on when to use this tool versus alternatives like describe_table or get_table_stats. The description lacks any context on use cases or exclusions, leaving the agent to infer from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clear, distinct purpose covering different aspects of PostgreSQL management: schema description, query execution, planning, connections, database info, stats, and monitoring. No overlaps or ambiguities.
All tool names follow a consistent verb_noun pattern with verbs like describe, execute, explain, get, and list. The naming is predictable and uniform.
With 12 tools, the server is well-scoped for its intended domain of PostgreSQL monitoring and management. Each tool earns its place without being excessive or sparse.
The tool set covers essential operations for database exploration and performance monitoring, including schema inspection, query execution, explain plans, and active query tracking. Minor gaps exist, such as lack of tools for modifying database objects or managing connections, but these are reasonable given the server's likely read-oriented purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Xata MCP server lets AI agents interact with your Xata projects, and Postgres database branches.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Butterbase MCP server — manage your backend: schemas, auth, functions, storage, RAG, deploys.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Zlash65/postgresql-ssh-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server