Text to SQL MCP Server: How to Design One for Good Reports
How should you design a text to SQL MCP server so an LLM writes good SQL reports? Short answer: give the model a read-only connection, a small set of tools, a written description of your schema, and a rule that every query states its assumptions. Then make the report answer a question, not dump rows.
Most bad SQL from an LLM is not a model problem. The model guessed. It guessed which table holds revenue, whether deleted users count, and what "last month" means. Your server design decides how much guessing is left.
Below are five design rules, each paired with a free item on our shelf that does that part of the job. We did not run any of them. Accuracy numbers: not measured.
Quick answer
| Design rule | Why it matters | Item to start with |
|---|---|---|
| Read-only, one project | A wrong query can't change data | Supabase MCP Server |
| Few, named tools | The model picks the right tool more often | Docker MCP gateway |
| A schema document | The model stops inventing joins | Database Schema Design |
| Stated assumptions | You can see the guess before you trust it | SQL Query Explainer |
| A report shape | Rows become a finding with a caveat | Data Analysis Standard |
How we picked
The top Google results for this search explain why text to SQL is hard and compare it with MCP. None of them shows a build order or names tools you can open today. We read the full file of every database item on the shelf and kept the ones that map to one design rule and have a real screenshot from the author.
1. Start read-only and scoped to one project
Supabase MCP Server connects your Supabase project to Claude, Cursor and other AI clients. It can manage tables, fetch config and query data.
For reports, you want less than that. The README shows a URL with project_ref=<project-ref>&read_only=true&features=database,docs. That gives the model one project, no tools that change data, and only the database and docs groups. The README also asks you to read Supabase's security notes before you connect.
2. Give the model fewer tools
Every extra tool is one more wrong choice. Docker MCP gateway runs each server in its own container and keeps secrets in Docker Desktop instead of env vars.
The useful part for SQL is the tool allowlist. You can switch single tools on or off with docker mcp profile tools <profile-id> --enable <server>.<tool> and --disable. Keep a "reporting" profile with only the read and schema tools. You need Docker Desktop 4.59 or later with MCP Toolkit turned on.
3. Write down the schema the model will read
Table names are not enough. The model needs to know that deleted_at IS NULL means active, which column is the time zone safe timestamp, and which queries the tables were built for.
Database Schema Design produces that document: an entity diagram, table definitions with notes per column, an index strategy, and an "access patterns" section with the real queries each table serves. Point your server at the finished file as a resource, or paste it into the system prompt. The file itself says a schema without query patterns can't be checked for correctness.
4. Make every query show its assumptions
SQL Query Explainer has a Write mode that turns a plain question into SQL with inline comments. It asks you to confirm the dialect and the table and column names. Without a schema, it says it states its assumptions instead of inventing them.
Every answer ends the same way: a one-line business summary, the gotchas for this query (NULLs, join fan-out, time zone traps), and a small SELECT you can run to check the result. Build that last step into your server's prompt. A report query with no check query should not ship.
5. Turn the result into a report
Rows are not a report. Data Analysis Standard gives the model four questions to answer every time: what changed, why, so what, and now what.
Its output format asks for the time period, the data source, a confidence level with a reason, and a line called "What this analysis does NOT tell us". It also warns against calling a correlation a cause. That is the guardrail most SQL report bots skip.
A simple build order
- Connect read-only to one project (step 1).
- Cut the tool list to read and schema tools (step 2).
- Write the schema document and load it as context (step 3).
- Require a check query with every report query (step 4).
- Wrap the answer in the four-question report (step 5).
For more database and data servers, browse the MCP servers shelf.
FAQ
What is a text to SQL MCP server? An MCP server that lets an AI client turn a plain-English question into SQL and run it against your database.
Should the LLM write SQL or call fixed tools? For repeat reports, fixed tools are safer. For new questions, let it write SQL, read-only, with a check query.
How do I stop the model inventing columns? Give it a schema document with column notes and access patterns, and ask it to state assumptions.
Is it safe to connect an LLM to a production database? Start read-only and scoped to one project. Supabase's URL supports both.