pii-safe-db-mcp

Run read-only SQL

query

Read-only

Run a single read-only SQL statement against PostgreSQL; results are capped at 200 rows and PII columns/text patterns are masked with stable tokens, enabling safe aggregate analysis.

Instructions

Run a single read-only SQL statement (SELECT / WITH / SHOW / DESCRIBE / EXPLAIN) against postgres. Results are capped at 200 rows. PII is masked before results are returned: columns recognised as PII (email, phone, name, address, Aadhaar, PAN, card numbers, passwords...) are replaced with stable tokens like <EMAIL_3f9a1c2b7d> (same input → same token, so you can still GROUP BY / COUNT DISTINCT / compare), and PII patterns found inside other text columns are masked too. Prefer aggregates (COUNT, GROUP BY) over pulling raw rows. Use ? (MySQL) or $1 (Postgres) placeholders with params.

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": {
      "sql": "<sql>"
    },
    "name": "query"
  }
}

Input Schema

Name	Required	Description	Default
`sql`	Yes	A single read-only SQL statement.
`params`	No	Bind parameters for placeholders.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 7, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=true, and the description is fully consistent with that while adding substantial behavior the agent could not otherwise know: a 200-row result cap, PII masking of recognised columns into stable tokens, the fact that tokens are deterministic so GROUP BY / COUNT DISTINCT still work, and masking of PII patterns embedded in free-text columns.

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

Conciseness4/5

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

Front-loaded with purpose, statement whitelist, and row cap before the masking detail, and each sentence carries operational information. The PII sentence is long and parenthetical-heavy but every clause (stable tokens, grouping still possible, text-column masking) changes how an agent would write its query.

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

Completeness5/5

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

There is no output schema, yet the description covers result size, the shape of masked values, and parameter binding, which is everything needed to write a correct call. For a two-parameter query tool with only a readOnlyHint annotation, this is complete.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it by explaining placeholder syntax ('? ' or '$1') and binding them through `params`, which the schema's generic 'Bind parameters for placeholders' does not specify. The only gap is that the MySQL-style `?` hint conflicts with the Postgres-only framing.

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?

The description gives a specific verb plus resource ('Run a single read-only SQL statement') and enumerates the permitted statement classes (SELECT / WITH / SHOW / DESCRIBE / EXPLAIN) against postgres. That scope statement, combined with the single-statement constraint, makes it easy to tell apart from list_tables and describe_table, which only introspect 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?

It gives real usage direction: keep to one statement, prefer aggregates over raw rows, and bind values via placeholders rather than inlining. It stops short of explicit routing ('use list_tables/describe_table instead of querying information_schema'), so the when-not-to-use case is only implied.

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

Deploy Server