Skip to main content
Glama
Sign In
MCPg - Production-grade PostgreSQL MCP Server

MCPg - Production-grade PostgreSQL MCP Server

by devopam
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Run PGQ

run_pgq
Read-only

Execute SQL/PGQ SELECT ... GRAPH_TABLE queries and return graph rows, capped by max_rows with truncation indication for PostgreSQL 19+.

Instructions

Execute a SQL/PGQ SELECT ... GRAPH_TABLE query and return the rows. The query must be a single SELECT (or WITH ... SELECT) statement that references GRAPH_TABLE — anything else is refused at the boundary (use run_select for non-graph reads). max_rows caps the result set; when the cap is hit, truncated=true. Requires PG 19+. Returns an object with columns (list of column names from the query's COLUMNS (...) clause), rows (list of dicts keyed by those columns), row_count, and truncated (bool).

Example: run_pgq(query="SELECT * FROM GRAPH_TABLE (org_chart MATCH (e:Employee)-[:REPORTS_TO]->(m:Manager) COLUMNS (e.name AS employee, m.name AS manager))", max_rows=50)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "run_pgq"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYes
databaseNoOptional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected.
max_rowsNo

Output Schema

NameRequiredDescriptionDefault
rowsYes
columnsYes
row_countYes
truncatedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.8.4
    • changedInput schema / properties / database / description
      Previous value: -"Optional: target a configured secondary (read-only) database by name; omit for the primary. Call list_databases to see the configured ids."New value: +"Optional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected."
  2. First observedv0.6.8

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond readOnlyHint/openWorldHint it discloses real behavior: boundary-level refusal of non-conforming statements, server version gating (PG 19+), and that `max_rows` produces a `truncated=true` signal rather than an error. The return-shape sentence partially duplicates the output schema, but the truncation and validation semantics are genuinely additive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core constraint and alternative in the first two sentences, then adds truncation, version requirement, return shape, and a single worked example. Dense but every sentence carries information an agent needs to call it correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be re-explained, and the description still covers validation, version gating, and truncation. The remaining gap is sibling routing against `run_cypher` and the secondary-database override, which matters for a tool with a `database` parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33%: `query` and `max_rows` carry no schema descriptions, and only `database` does. The description compensates for `max_rows` (cap semantics plus truncation) and constrains `query` (must contain GRAPH_TABLE), but says nothing about the `database` targeting parameter or the 200-row default, so the gap is only partly closed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: execute a SQL/PGQ `SELECT ... GRAPH_TABLE` query and return rows. It immediately differentiates itself from the non-graph sibling by name (`run_select`), so an agent can route correctly without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit acceptance condition (must be a single `SELECT` or `WITH ... SELECT` referencing `GRAPH_TABLE`, anything else refused) and a named alternative (`run_select` for non-graph reads). It omits `run_cypher`, the other obvious graph-query sibling, and does not say when to prefer Cypher over PGQ.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools