MCPg - Production-grade PostgreSQL MCP Server

Overview Schema Source Related Servers Discussions Admin

Translate NL to SQL

translate_nl_to_sql

Read-only

Turn natural-language questions into validated, read-only SQL queries for PostgreSQL, with optional execution and safety checks.

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)

Input Schema

TableJSON Schema

Name	Required	Description
`schema`	Yes
`execute`	No
`database`	No	Optional: target a configured secondary (read-only) database by name; omit for the primary. Call list_databases to see the configured ids.
`max_rows`	No
`provider`	No
`question`	Yes
`table_filter`	No
`explain_preflight`	No

Output Schema

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

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.5/5.0

Behavior5/5

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

The description goes far beyond the readOnlyHint annotation by detailing the safety allowlist shared with run_select, rejection of writes/DDL/multi-statement input, the LLM return contract, the effect of execute=true, and the provider priority fallback. This gives an agent a precise model of what happens before, during, and after invocation without contradicting the annotations.

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 description is front-loaded with the purpose, then layers safety, return values, filter behavior, and provider routing. It is dense but each sentence carries useful information. The provider list appears twice in slightly different forms, which adds minor redundancy, but the overall structure is readable and scannable.

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 a complex NL2SQL tool with 8 parameters, the description covers the critical behavioral context: read-only enforcement, safety allowlist, provider selection, table filtering, return shape, and an explicit example. The output schema exists, so return-value details need not be repeated. Minor gaps remain around `max_rows` and `explain_preflight`, but defaults and naming make them low-risk.

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?

With schema description coverage at only 13%, the description does substantial compensating work by explaining `execute`, `table_filter`, `provider`, and showing a full example. It leaves `max_rows`, `explain_preflight`, and `schema` largely unexplained in prose, though their names and defaults give reasonable hints. This is strong compensation but not complete.

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 opening sentence states a specific verb and resource: 'Translate a natural-language question into a read-only PostgreSQL query against `schema`.' It clearly identifies the tool's core function, distinguishes it from SQL-based query tools like run_select, and clarifies the read-only nature. The example further anchors exactly what a call looks like.

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?

The description gives clear context for when the tool is appropriate: when a natural-language question needs translation to SQL, with optional execution. It also provides routing guidance for the provider parameter and points to get_server_info for discovering configured providers. It does not explicitly contrast with alternatives or state when NOT to use it, but the intended use case is well conveyed.

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

Deploy Server