Provides PostgreSQL diagnostics and cluster management for Multigres clusters, including schema and object inspection, read-only SQL execution, query plans with hypothetical indexes, top-query analysis, index advice, health checks, cluster status, backup operations, and node log reading.
An MCP server for Multigres clusters. It gives an MCP client two groups of tools:
Postgres diagnostics through the Multigres gateway: schemas and objects, read-only SQL, query plans with hypothetical indexes, top queries, index advice and a health check. These follow the tools of postgres-mcp.
Cluster tools through multiadmin: cluster status, backups, node logs, and in the unrestricted mode switching the primary and starting or expiring backups.
The server is read-only by default. Write tools are registered only in the unrestricted mode.
It has been tested against a local Multigres Docker cluster built from commit 49e7a2f7d4fe (2026-11-02, PostgreSQL 17.7, two cells) on Linux with Docker Engine. Other setups have not been tested.
Each release has a multigres-mcp-<version>.mcpb file. It is an MCP Bundle: clients that install bundles ask for the settings under "Configuration" and run the server. It is also a zip file whose server/ directory holds binaries for Linux and macOS on amd64 and arm64 and for Windows on amd64, which any other client can run directly.
Related MCP server: postgres-mcp-server
Requires Go 1.26 or later.
git clone https://github.com/JoongHyuk-Shin/multigres-mcp
cd multigres-mcp
go build -o multigres-mcp ./cmd/multigres-mcpThe server talks MCP over standard input and output. ./multigres-mcp --help prints the options.
packaging/build-mcpb.sh builds the release bundle into dist/. It also needs jq, Node.js and openssl.
Every option can be given as a flag or as an environment variable. A flag wins over the variable.
Flag | Variable | Default | Meaning |
|
| none, required | Connection string of the Multigres gateway. |
|
| none | multiadmin HTTP address. The cluster tools are registered only when it is set. |
|
| none | Bearer token for multiadmin started with |
|
| none |
|
|
|
|
|
|
|
| Statement timeout for the SQL every tool sends. See "Things to know". |
Direct node connections reuse the user, password and database of --database-url and take the host and port from multiadmin.
In the local Docker cluster both nodes report the host localhost, while their Postgres ports are reachable only at the container's address. Find that address in the Multigres checkout with:
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$(docker compose ps -q multigres)"and pass it as --node-host-map localhost=<address>.
With Claude Code, for the local Docker cluster (replace 172.18.0.2 with the address found above):
claude mcp add multigres -e DATABASE_URI=postgres://postgres:postgres@localhost:15432/postgres -- /path/to/multigres-mcp --admin-url http://localhost:15000 --node-host-map localhost=172.18.0.2Other clients take the same command, arguments and environment in their server configuration, for example:
{
"mcpServers": {
"multigres": {
"type": "stdio",
"command": "/path/to/multigres-mcp",
"args": ["--admin-url", "http://localhost:15000", "--node-host-map", "localhost=172.18.0.2"],
"env": {
"DATABASE_URI": "postgres://postgres:postgres@localhost:15432/postgres"
}
}
}
}Tool | Mode | What it does |
| both | List the schemas. The |
| both | List the tables, views, sequences or extensions of a schema. |
| both | Columns, constraints and indexes of a table or view, or details of a sequence or extension. |
| both | Run one read-only statement ( |
| both | The plan of a query, optionally with |
| both | The slowest or most expensive queries, from |
| both | Index advice for the workload in |
| both | The same for up to 10 given queries. |
| both | Health checks: bloat, vacuum, locks, activity, waits, slow queries, missing indexes, cache, log, index health, sequences, replication and constraints. It starts with the statistics period of the node that answered. |
| both, needs | Cells, databases, the primary and replicas of each shard with LSN and lag, gateways, orchestrators, recent primary changes, and whether the connected user is a superuser. |
| both, needs | Backups of a shard. |
| both, needs | Run pgBackRest |
| both, needs | Status of a backup job. |
| both, needs | The end of a node's Postgres log, read over a direct connection to that node. |
| unrestricted | Run one statement that may change data or schema, committed if it succeeds. |
| unrestricted, needs | Ask Multigres to switch a shard's primary, then report the old and new primary and terms. Multigres may elect the same node again; the tool says so and does not retry. |
| unrestricted, needs | Start a backup and return its job id. |
| unrestricted, needs | Expire backups with the retention rules configured in the cluster. |
| unrestricted, needs | Turn automatic Postgres restarts on a node on or off. |
That is 14 tools in the restricted mode and 19 in the unrestricted mode, or 9 and 10 without --admin-url. diagnose and get_top_queries take an optional node to read one node directly instead of through the gateway, for example the old primary after a failover.
The restricted mode does not register any tool that can write. Writing SQL is a tool of its own, execute_write_sql, so a client permission given to execute_sql never covers a write, even after the server is restarted in the unrestricted mode.
Every statement that execute_sql, explain_query and analyze_query_indexes receive passes these checks. They do not rely on each other: checks 1, 3 and 4 each stop a write on their own.
It is parsed with the Multigres parser. It must be exactly one statement, the top statement must be SELECT, EXPLAIN of a SELECT, or SHOW, and the tree must not contain data-changing statements, SELECT INTO or locking clauses. Functions must be on an allow list (the postgres-mcp list with functions that have side effects removed), and a schema-qualified function must be in pg_catalog.
It is sent with the extended query protocol, which carries one statement only.
The read-only connection is opened with default_transaction_read_only=on.
It runs in BEGIN TRANSACTION READ ONLY, which is always rolled back.
search_path is pinned, and a statement that calls an unqualified function whose name also exists outside pg_catalog is not sent.
A statement timeout is set.
This covers the statements the model sends and the functions they call directly. The bodies of objects already in the database (views, functions, operators, policies) are trusted and not checked. Against a production database, connect as a read-only role as well. cluster_status shows whether the connected user is a superuser.
Multigres hands pooled Postgres connections from one client to the next. Within the same transaction, the server removes the hypothetical indexes and session advisory locks a tool call may have left on its connection. If that cleanup fails, it ends its own Postgres session rather than hand the state on. execute_write_sql rejects transaction control, session-level SET and RESET, multigres.* settings, hypopg functions, and statements that leave session state behind (temporary objects, PREPARE, LISTEN, DECLARE ... WITH HOLD, LOAD, DISCARD, DO). Session settings (set_config(..., false)) and the random seed (setseed) changed inside the body of a function or trigger are not removed and can reach the next client of that connection; like the other object bodies, they are trusted.
Direct node connections run fixed queries only, never SQL from the model.
The multiadmin address (in full and as host:port), the admin token and the database password are removed from tool results and error messages. The removal replaces text, so a password that is a common word is masked wherever that word appears. A password equal to the user or database name is not masked, because results show those names; the server prints a warning when it starts.
--sql-timeout defaults to 25s because the multipooler ends a transaction's connection when one statement runs past --connpool-user-reserved-inactivity-timeout (default 30s). To use a longer timeout, raise that pooler setting too.
The results of execute_sql and execute_write_sql end with a line naming the settings the server set for that call only (statement_timeout, lock_timeout, and for reads search_path), and the statement_timeout its own session had before. The gateway enforces statement_timeout itself without setting it on the node, so the node's pg_settings shows 0 for it while SHOW through the gateway answers with the gateway's value.
Cumulative statistics are kept per node. After a failover the new primary's statistics do not include what happened on the old primary. The tools that use statistics start with the period they cover; the node option of diagnose and get_top_queries reads another node.
Index sizes in the advice are hypopg estimates and ignore btree deduplication. On a column with many repeated values the estimate can be several times the real size (on 200,000 rows with 1,000 distinct values: 4,644,864 bytes estimated, 1,384,448 bytes real).
The gateway truncates the query text it keeps to --query-metrics-sql-max-bytes (default 4096) without a marker. Plans and index advice use the pg_stat_statements text or the full statement you give.
Statement texts from pg_stat_statements are shown in full. One very long statement can fill the 50,000-character result: diagnose then leaves out the rest of the slow query check and the checks after it, and get_top_queries leaves out the gateway part. The result says it was cut. Ask diagnose for the later checks by name, and get_top_queries for source: gateway.
VACUUM and CREATE INDEX CONCURRENTLY cannot run in a transaction, so execute_write_sql cannot run them.
Calls to multiadmin time out after 30 seconds, verify_backups after 10 minutes.
If execute_write_sql gets no reply to its COMMIT, it says it does not know whether the statement was committed. Check the data before sending it again.
go test ./...runs the unit tests. The integration and end-to-end tests have the build tag cluster and need a local Multigres Docker cluster with pg_stat_statements preloaded and hypopg installed. They switch the primary, drop and recreate the two extensions, and end sessions, so do not point them at a cluster you care about. They fail rather than skip when the cluster cannot be reached.
Start the cluster from a Multigres checkout:
git clone https://github.com/multigres/multigres
cd multigres
git checkout 49e7a2f7d4fe
MULTIGRES_PG_EXTRA_CONF="shared_preload_libraries = 'pg_stat_statements'" docker compose up -d --buildWait until docker compose ps shows the container as healthy, then install hypopg and create both extensions:
docker compose exec -u root multigres sh -c 'apt-get update -q && apt-get install -y -q --no-install-recommends postgresql-17-hypopg'
docker compose exec -e PGPASSWORD=postgres multigres psql -h localhost -p 15432 -U postgres -d postgres -c 'CREATE EXTENSION pg_stat_statements' -c 'CREATE EXTENSION hypopg'Then, in this repository, with MULTIGRES_MCP_TEST_NODE_HOST set to the container address from the docker inspect command above:
MULTIGRES_MCP_TEST_NODE_HOST=<address> go test -tags cluster -p 1 -count=1 -timeout 25m ./...-p 1 runs one package at a time, because the packages share the cluster's primary, extensions and connection pools. The tests use the gateway at localhost:15432, multiadmin at localhost:15000 and the node ports 25432 and 25433 of the Docker cluster; MULTIGRES_MCP_TEST_GATEWAY_URL and MULTIGRES_MCP_TEST_ADMIN_URL change the first two. test/facts-map.md maps the Multigres behaviour the design relies on to the test that checks it.
Apache License 2.0, see LICENSE. Parts adapted from postgres-mcp are under the MIT License, see THIRD_PARTY_NOTICES.md.
Recommend indexes for up to 10 given SELECT queries, by comparing planner costs with hypothetical indexes (hypopg). Nothing is created.
| Name | Required | Description | Default |
|---|---|---|---|
| queries | Yes | Up to 10 SELECT queries, with values or with $1-style placeholders | |
| max_index_size_mb | No | Size budget for all recommended indexes together, in MB (default 10000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond that: it explains that recommendations are derived by comparing planner costs using hypothetical indexes, and explicitly reassures 'Nothing is created.'
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 tight sentence with the core action and scope front-loaded, followed by the method and a key safety clarification. No wasted wording.
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 two-parameter analysis tool with rich annotations and no output schema, the description covers purpose, scope, method, and non-destructive behavior. It could say more about expected output format or query validity requirements, but the essentials are present.
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 both parameters are already documented. The description restates the query limit and SELECT-only constraint, but adds no new meaning for max_index_size_mb beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (recommend indexes) and constrains scope to up to 10 given SELECT queries, which distinguishes it from the workload-oriented sibling analyze_workload_indexes. It also names the mechanism (hypothetical indexes via hypopg).
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 'up to 10 given SELECT queries' scope clearly signals when this tool is appropriate rather than a workload-wide analysis. It does not explicitly name analyze_workload_indexes as the alternative, but the context is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recommend indexes for the current workload in pg_stat_statements, by comparing planner costs with hypothetical indexes (hypopg). Nothing is created.
| Name | Required | Description | Default |
|---|---|---|---|
| max_index_size_mb | No | Size budget for all recommended indexes together, in MB (default 10000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds real method context — planner-cost comparison using hypothetical indexes — and 'Nothing is created' reinforces non-destructiveness. However, it omits that the hypopg extension must be installed and says nothing about the cost/runtime of scanning the whole workload.
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 compact sentences, front-loaded with the action and resource, with the method and the no-write guarantee following. Nothing is wasted, though the method clause could be trimmed or the space spent on prerequisites.
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?
There is no output schema, so the description should convey what a recommendation looks like and what an agent gets back; it does not. For a workload-wide analysis tool, the absence of prerequisite and runtime notes leaves a moderate gap, though the safety story is complete via annotations.
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% and the single parameter already documents its meaning and default of 10000 MB. The description adds no interpretation of max_index_size_mb, such as how the budget is allocated across recommendations or what happens when it is exceeded, which is the baseline expectation when the schema does the work.
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?
Names a specific verb and resource: 'Recommend indexes for the current workload in pg_stat_statements'. The workload-level scope implicitly contrasts with the sibling analyze_query_indexes, and the hypopg method is stated, so an agent can tell what it does. It stops short of explicitly naming the single-query alternative.
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?
Scoping to 'the current workload in pg_stat_statements' implies when it applies, but there is no explicit when-to-use vs when-not or direct routing to analyze_query_indexes for single-query tuning or to get_top_queries for identifying candidates first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run health checks (bloat, vacuum, locks, activity, waits, slow queries, missing indexes, cache, log, index health, sequences, replication, constraints), after the statistics period of the node that answered.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | Run the checks on this node over a direct connection (cell/name, name, or primary); default is through the gateway | |
| checks | No | Checks to run, in any order (default all): bloat, vacuum, locks, activity, waits, slow_queries, missing_indexes, cache, log, index_health, sequences, replication, constraints |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful operational context about running after the statistics period of the answering node, though it does not discuss duration, permissions, or result shape.
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 and essentially one sentence. The long parenthetical check list duplicates schema content but remains readable and useful for scanning.
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 complex diagnostic tool with no output schema, the description lists the check categories but does not explain what results to expect or how the individual checks differ. It is sufficient to invoke, but not fully complete for interpreting a diagnostic run.
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 both the node and checks parameters are already documented in the schema. The description reinforces the available checks and default-all behavior but adds little semantic detail beyond the structured fields.
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?
Names a specific verb and resource: run health checks. The parenthetical list of check categories makes the tool's scope concrete and distinguishable from query-focused siblings, though it does not explicitly name alternatives.
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?
Provides a timing prerequisite: run after the statistics period of the node that answered. It does not state when to choose this tool over siblings such as get_top_queries or explain_query, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one read-only SQL statement (SELECT, EXPLAIN of a SELECT, or SHOW) through the Multigres gateway. The statement is checked before it is sent and runs in a read-only transaction that is always rolled back. Functions must be on the allow list.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | One SQL statement |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: a pre-flight check before the statement is sent, execution inside a read-only transaction that is always rolled back, and an allow-list requirement for functions. It does not mention row limits, timeouts, or result-size caps, which are meaningful behaviors for a SQL execution 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?
Three short sentences with no filler, and the most decision-relevant facts (read-only, allowed statement types) are front-loaded before the transactional and allow-list details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, full schema coverage, rich annotations, and no output schema to explain, the description covers what an agent needs to construct a valid call. The gap is operational: no statement timeout, row/result cap, or error-behavior guidance, which matters for a tool that can return large result sets.
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% and the single parameter is trivially described ('One SQL statement'), so the baseline would be 3. The description earns above baseline because it defines what 'one SQL statement' actually means here: a single statement only, restricted to SELECT/EXPLAIN-of-SELECT/SHOW, with functions drawn from an allow list.
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 gives a specific verb and resource ('Run one read-only SQL statement') and enumerates the accepted statement forms (SELECT, EXPLAIN of a SELECT, SHOW), so an agent knows exactly what will be executed. It does not name any sibling, even though explain_query and diagnose sit close to this space, so the differentiation is left implicit.
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 constrained rather than directed: the agent learns it may only submit read-only statements and allow-listed functions, which implicitly rules out DDL/DML. However, nothing tells the agent when to call execute_sql versus explain_query, get_top_queries, or the analyze_* siblings, which is the main routing decision it faces.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the execution plan of a SQL query with cost estimates. A query with $1-style placeholders (as in query statistics) is explained with a generic plan. Hypothetical indexes need the hypopg extension.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL query to explain | |
| analyze | No | Run the query to show real execution statistics; only for a SELECT that passes the read check, inside the time limit | |
| hypothetical_indexes | No | Hypothetical indexes to simulate with hypopg; they are removed before the call ends |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the description has a lower burden. It adds real context, namely the generic-plan behavior for placeholders and the hypopg dependency, but it never states that analyze=true actually runs the query, which is the most consequential behavioral trait here and is only in the schema.
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?
Three short sentences, front-loaded with the core action, then the two conditional gotchas. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three parameters, full schema coverage and no output schema, the description should say what the plan looks like when returned, for example a text plan versus structured rows, and confirm that analyze has side effects at execution. Those gaps matter because no output schema backs them up.
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 the baseline is 3. The description still adds meaning the schema does not: it explains how $1-style placeholders are handled for the sql param, and it names the hypopg extension requirement for hypothetical_indexes. Only the analyze parameter goes unaddressed.
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 a specific verb and resource: 'Show the execution plan of a SQL query with cost estimates.' That distinguishes it from execute_sql by implication, but it never names the siblings it competes with, such as analyze_query_indexes or diagnose, which also touch query performance.
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 only implied. The notes on $1 placeholders and on hypothetical indexes needing hypopg are useful conditional hints, but the description never says when to pick this over execute_sql or when to prefer the index-analysis siblings. There are no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show columns, constraints and indexes of a table or view, or details of a sequence or extension.
| Name | Required | Description | Default |
|---|---|---|---|
| object_name | Yes | Object name | |
| object_type | No | Object type: table, view, sequence or extension (default table) | |
| schema_name | Yes | Schema name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description contributes the useful fact that output is structural metadata per object type, but it is vague for sequences/extensions ('details') and says nothing about failure behavior for missing objects.
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 front-loads the retrieved fields and then branches by object type. No filler, no redundancy, nothing to trim.
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 three-parameter read tool with full annotation and schema coverage, the description covers what matters: what metadata comes back per object type. The only loose end is that 'details' for sequence/extension is not unpacked, but that is a minor gap rather than a blocking one.
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 all three parameters are already documented, including the object_type default of table. The description adds no syntax, casing, or qualification guidance beyond restating the object kinds, so it sits at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (show) and enumerates exactly what is retrieved for each object kind: columns, constraints and indexes for tables/views, and details for sequences/extensions. That distinguishes it clearly from list_objects, though it never names the sibling explicitly.
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 only implied: use this when you already know the object and want its structure, versus list_objects when you don't. There is no explicit when-to-use statement, no mention of prerequisites (e.g. that the object must exist), and no comparison to siblings like execute_sql or list_objects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the slowest or most resource-intensive queries from pg_stat_statements and from the query statistics each Multigres gateway keeps. The two sources cover different periods and are shown separately.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | Read pg_stat_statements on this node over a direct connection (cell/name, name, or primary); default is through the gateway | |
| limit | No | Number of queries when ranking by total_time or mean_time (default 10) | |
| source | No | both (default), pg_stat_statements, or gateway for the query statistics each Multigres gateway keeps | |
| sort_by | No | Ranking: total_time, mean_time, or resources for queries using more than 5% of any resource (default resources) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results come from two sources with different time coverage and are returned separately, which directly affects how an agent should interpret the output. It does not discuss pagination or result size limits, keeping it short of a 5.
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 sentences, zero filler, with the core purpose stated first and the interpretive caveat about differing time periods second. Nothing is repeated from the schema or annotations.
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 read-only, four-parameter reporting tool with full schema coverage and no output schema, this is close to complete — it explains what is reported and why two result sets appear. Minor gaps remain: the description does not characterize what a row contains (query text, timing, resource share) or clarify the gateway-vs-direct connection tradeoff implied by `node`.
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 all four parameters (node, limit, source, sort_by) are already well documented, and the baseline is 3. The description only adds the framing that the sources are shown separately, which reinforces the `source` parameter but adds no syntax, defaults, or edge-case detail 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?
The description names a specific verb and resource ("Report the slowest or most resource-intensive queries") and identifies two concrete data sources, pg_stat_statements and per-gateway query statistics. It implicitly distinguishes itself from siblings like explain_query or analyze_query_indexes by being a top-N ranking report rather than a plan or index analysis, though it never names those alternatives explicitly.
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 only implied: an agent can infer this is the tool for finding expensive queries, but there is no explicit "use this when X, use explain_query when Y" guidance. The note that the two sources cover different periods is helpful context but is not when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List objects in a schema.
| Name | Required | Description | Default |
|---|---|---|---|
| object_type | No | Object type: table, view, sequence or extension (default table) | |
| schema_name | Yes | Schema name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds no behavioral context of its own — nothing about what a returned "object" contains, whether results are paginated, or how object_type filtering affects output.
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 six-word sentence with no filler and the resource front-loaded. It is efficient, though it is arguably too terse to carry any routing or return-value 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?
For a simple, fully annotated, read-only listing tool this is minimally adequate: parameters are fully documented in the schema and the annotations establish safety. However, with no output schema present, the description could have said what is returned (names, types, counts), and it offers no sibling routing.
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 object_type documenting its enum-like values (table, view, sequence, extension) and its default. The description contributes nothing beyond this, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List objects") scoped to "a schema", which is unambiguous about what it does. It does not distinguish itself from siblings like get_object_details or list_schemas, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as list_schemas for schema discovery or get_object_details for inspecting a single object. Usage must be inferred entirely from the tool name.
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. The multigres schema is internal to Multigres.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds one genuinely useful behavioral note — that the multigres schema is internal — but never says whether to ignore it, exclude it, or avoid querying it, and says nothing about ordering or result size.
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 short sentences with zero filler, and the core purpose is front-loaded before the caveat about the internal schema.
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 tool with full annotation coverage, this is nearly complete; the only gap is that with no output schema the description could hint at what a listed schema looks like (name only, or name plus owner).
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 takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless tool 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?
States a specific verb and resource ('List all schemas in the database'), making the unit of retrieval unambiguous. It does not explicitly distinguish itself from the sibling list_objects, but the verb+resource pairing is specific enough that an agent can infer the difference.
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 'when' is only implied: you call it when you need to discover schemas. There is no explicit routing guidance versus list_objects or get_object_details, and no statement about prerequisites or typical next steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0analyze_query_indexesanalyze_workload_indexesdiagnoseexecute_sqlexplain_queryget_object_detailsget_top_querieslist_objectslist_schemasScored across 9 tools
The two index advisors are cleanly separated by input source (user-supplied SELECTs vs. pg_stat_statements workload), and read paths (list_schemas, list_objects, get_object_details) are distinct. Minor overlap exists between explain_query and execute_sql's EXPLAIN mode, and between get_top_queries and diagnose's slow-query/log checks, but descriptions make the intended split clear.
Nearly all tools follow a predictable snake_case verb_noun pattern (list_schemas, list_objects, get_top_queries, analyze_workload_indexes). The lone bare verb 'diagnose' is the only deviation, though it is still readable and distinct.
Nine tools is well-scoped for a read-only Postgres diagnostics/monitoring server, with no redundant entries and each tool earning its place. Nothing feels padded or missing at the count level.
The surface covers discovery, inspection, ad-hoc querying, plan explanation, index advising, and health checks — a solid lifecycle for a diagnostic (non-mutating) server. Gaps are minor: no direct access to server settings/pg_settings or explicit index list, though get_object_details and diagnose cover much of that indirectly.
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Comprehensive PostgreSQL documentation and best practices, including ecosystem tools
Managed Postgres MCP: projects, SQL, docs search, and storage buckets via OAuth.
Create, manage, and query your Google Cloud SQL resources.
