MCPg - Production-grade PostgreSQL MCP Server

Overview Schema Source Related Servers Discussions Admin

Translate NL to SQL

translate_nl_to_sql

Read-only

Converts a natural-language question into a read-only PostgreSQL query for a selected schema, with optional safe execution after allowlist validation.

Instructions

Translate a natural-language question into a read-only PostgreSQL query against schema. The LLM provider (anthropic / openai / gemini / deepseek / qwen / openrouter / perplexity, plus any operator-declared custom OpenAI-compatible provider) sees a compact brief of the schema (tables, columns, foreign keys) and is instructed to return JSON with sql and explanation. When execute=true, the generated SQL goes through the SAME safety allowlist as run_select before running — writes / DDL / multi-statement input are rejected even if the model produced them. Returns the SQL, model rationale, and (when executed) rows / columns / row_count. table_filter narrows the brief to a known subset when the question is clearly scoped. provider, when supplied, selects which configured LLM provider to call (use this to route between the configured vendors per-call when multiple are configured); when omitted, MCPg uses the default (MCPG_NL2SQL_PROVIDER, otherwise the first available in preference order anthropic → openai → gemini → deepseek → qwen → openrouter → perplexity). Call get_server_info to see which providers are configured.

Example: translate_nl_to_sql(question='top 10 customers by revenue last month', schema='public', execute=true)

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": {
      "question": "<question>",
      "schema": "<schema>"
    },
    "name": "translate_nl_to_sql"
  }
}

Input Schema

Name	Required	Description
`schema`	Yes
`execute`	No
`database`	No	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.
`max_rows`	No
`provider`	No
`question`	Yes
`table_filter`	No
`explain_preflight`	No

Output Schema

Name	Required	Description	Default
`sql`	Yes
`rows`	Yes
`error`	Yes
`model`	Yes
`columns`	Yes
`refused`	No
`executed`	Yes
`provider`	Yes
`row_count`	Yes
`tokens_in`	No
`tokens_out`	No
`explanation`	Yes
`refusal_reason`	No
`schema_context`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.4Nov 5, 2026

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."

Changed2 schema fields changedv0.8.2Sep 7, 2026

addedOutput schema / properties / schema_context

Added value: +{
+  "title": "Schema Context",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "sql",
-  "explanation",
-  "model",
-  "provider",
-  "executed",
-  "rows",
-  "columns",
-  "row_count",
-  "error"
-]New value: +[
+  "sql",
+  "explanation",
+  "model",
+  "provider",
+  "schema_context",
+  "executed",
+  "rows",
+  "columns",
+  "row_count",
+  "error"
+]

Changed2 schema fields changedAug 4, 2026

addedOutput schema / properties / tokens_in

Added value: +{
+  "default": 0,
+  "title": "Tokens In",
+  "type": "integer"
+}

addedOutput schema / properties / tokens_out

Added value: +{
+  "default": 0,
+  "title": "Tokens Out",
+  "type": "integer"
+}

Changed3 schema fields changedJul 9, 2026

addedInput schema / properties / explain_preflight

Added value: +{
+  "default": true,
+  "title": "Explain Preflight",
+  "type": "boolean"
+}

addedOutput schema / properties / refusal_reason

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Refusal Reason"
+}

addedOutput schema / properties / refused

Added value: +{
+  "default": false,
+  "title": "Refused",
+  "type": "boolean"
+}

First observedv0.6.8Jul 6, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial operational context beyond that: writes/DDL/multi-statement output is rejected by the same allowlist as run_select even if the model emits it, the provider preference order is spelled out (MCPG_NL2SQL_PROVIDER then anthropic → ... → perplexity), and it describes what is returned (SQL, rationale, and rows/columns/row_count when executed). This is exactly the mutation-safety and credential/routing information an agent needs.

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?

The first sentence front-loads the purpose and the safety/execution paragraph follows logically, with the provider enumeration and the example at the end. It is dense but nearly every clause carries information; the long provider list and parenthetical asides add some bulk but not filler.

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?

For an 8-parameter, LLM-backed tool with an output schema already documenting return values, the description covers the risky behavior (allowlist, rejection of writes), provider selection, and scoping well. The remaining shortfall is the undocumented max_rows default and explain_preflight toggle, which matter for controlling cost/output size.

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 description coverage is very low (13%), so the description must carry the load. It does explain provider (default resolution and routing), table_filter (narrows the schema brief), and execute (triggers the allowlist check plus execution), and it includes a worked example tying question/schema/execute together. However max_rows and explain_preflight are never mentioned, and database is only covered by the schema itself, leaving meaningful gaps.

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 opens with a specific verb and resource ('Translate a natural-language question into a read-only PostgreSQL query against `schema`') and names the downstream artifact (JSON with `sql` and `explanation`). It also distinguishes itself from the sibling `run_select` by explaining that generated SQL passes through the same allowlist, so an agent can tell the two apart without opening a 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 states the core trigger (an NL question needing SQL), when to set execute=true, when to use table_filter ('when the question is clearly scoped'), and how to pick a provider per-call. It also routes the agent to get_server_info to discover configured providers. It stops short of explicitly saying 'use run_select instead if you already have SQL text', so it's strong but not fully exhaustive.

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

Deploy Server