Query PostgreSQL with Claude or Cursor via MCP.
Ask plain-English questions about your Postgres data — joins, aggregations, schema introspection, query performance — without exposing connection strings to the AI vendor or opening firewall ports on your network.
Ask Nova, get SQL + charts
Meet Nova Database REST APIOne key per partner. No credentials shared.
Build an API AutomationScheduled sync to 6+ platforms
Explore API to SQLQuery APIs with SQL, no code
Explore AI Database MCPClaude, Cursor, ChatGPT & Grok talk to your data
Connect AIQuery Streams is a secure, real-time data integration platform that brings every database and SaaS API in your account into Claude, Cursor, ChatGPT, and Grok — through a single MCP key with no firewall changes. This guide walks through wiring up the PostgreSQL connector specifically, so your AI tool can answer plain-English questions about orders, customers, products, and any other Postgres data — joins, aggregations, schema exploration, query performance — without you copy-pasting CSV exports out of pgAdmin or DBeaver. Learn more at QueryStreams.com and sign up for free to start asking your AI tool real Postgres questions.
What Query Streams MCP gives you for PostgreSQL
Other “PostgreSQL MCP” servers on the open-source landscape connect the AI tool directly to a Postgres connection string. That works, but it pushes a database password (or an IAM token) into your AI client’s config, scopes the AI tool to only that one Postgres cluster, and gives you no audit trail of what the AI actually asked. Query Streams MCP solves a wider problem: one key, every connector, full audit trail, and the AI tool never holds your Postgres credentials.
Zero inbound firewall holes
The Network Agent opens a single outbound encrypted cloud link to Query Streams. Your AI client connects to the cloud, never to your Postgres host. No port to open, no IP to allowlist, no VPN, no Postgres listener exposed to the public internet.
One key, every connector
The same MCP key reaches every database and SaaS API your account has connected. Add a Stripe or Snowflake connector tomorrow and the AI tool sees it next to your Postgres tables without re-keying.
Schema Intelligence baked in
The AI sees AI-curated descriptions, semantic types, enum value lists, and discovered foreign keys for every Postgres column — not just bare information_schema output. It writes accurate SQL on the first try, even on legacy schemas with cryptic column names.
Read-only enforced at the agent
Even a hallucinating LLM can’t issue DELETE, UPDATE, or TRUNCATE through Query Streams MCP. The Network Agent rejects anything that isn’t SELECT, WITH, or EXPLAIN before Postgres ever sees the SQL.
Per-key rate limits
Default 60 requests per minute and 10 execute calls per minute, configurable per key. A runaway AI tool-call loop hits a token bucket, not your Postgres connection pool or your AWS RDS bill.
How it works without opening firewall ports
The Query Streams Network Agent is a small program you install once on a machine that can reach your PostgreSQL cluster (any laptop, on-prem server, EC2 instance, Azure VM, or cloud VM in the same VPC as your Postgres). It dials one outbound TLS link to the cloud and runs SQL against Postgres over the local network using the standard Postgres protocol — nothing inbound, nothing exposed, and the AI tool never sees your Postgres connection string. How the outbound-only architecture works →
AI Client
Cursor, Claude,
ChatGPT, Grok
QS MCP Server
Streamable HTTP
X-MCP-Key auth
Network Agent
On your network
Cloud link out
PostgreSQL
Connection string
held by the agent
The MCP key you give Cursor or Claude is scoped (read / analyze / execute), revocable at any time, and rate-limited per-key. The AI tool calls these MCP tools to do its work:
pattern_key with optional parameter overrides.Why Schema Intelligence makes Query Streams MCP different
Most “MCP for Postgres” servers in the open-source landscape hand your AI tool the same information_schema Postgres hands a stranger. Column names. Data types. Maybe a primary key. The LLM is left to guess what status_id = 3 means, what usr_eml stores, or whether line_items.order_id actually joins to orders.id (no foreign key was ever declared either way). That’s why the first SQL most LLMs write against a bare schema is wrong — not because the LLM is bad, but because it doesn’t have the data it needs to be right.
Query Streams MCP returns that same schema enriched with what we call Schema Intelligence (SI) — AI-curated metadata that’s generated by running profiling queries against your actual Postgres data before the AI client ever asks. When SI is enabled on a connector and database, every schema tool the AI calls (qs_get_connector_schema, qs_get_table_schema, qs_profile_table, qs_get_relationships) returns the bare schema plus six layers of curated knowledge. The LLM stops guessing.
To make this concrete, here is what the AI client gets back from a single qs_get_table_schema call against a typical Postgres e-commerce schema (orders, line_items, customers, products) — first without Schema Intelligence, then with it.
The six layers Schema Intelligence adds
Each layer addresses a class of question the LLM would otherwise guess at. The opt-in SI profiling pass runs read-only against your Postgres data without changing your schema or writing to your database, and refreshes incrementally when your schema changes. what Schema Intelligence adds and how it stays current →
AI-curated descriptions
Plain-English purpose for every database, schema, table, and column — generated once, refreshed when your schema changes. Confidence-scored; user-authored descriptions always win.
one row per checkout.”
Table classifications
Each table tagged FACT (transactional events), DIM (descriptive reference), or LOOKUP (small code maps), plus a business domain — sales, hr, seo, finance, support, and 14 more.
customers [DIM, domain:customers]
Semantic types per column
Eighteen types — currency, email, date_iso, status_code, percentage, ranking_position, identifier, url, person_name, and more. The AI generates dialect-correct Postgres SQL appropriate to each type.
created_at: date_iso
Sample values from real data
Random rows surfaced to the LLM so it recognises patterns no schema can show — formatting conventions, encoded values, abbreviation styles, and the actual shape of your strings.
‘QS-027-AMBER’]
Enum detection with distributions
Low-cardinality columns (50 or fewer distinct values, at most 5% of rows unique) mapped to their full value list with row counts. The AI never guesses casing or spelling.
| refunded (6%) | pending (4%)
Implicit foreign-key discovery
Cross-table data overlap analysis finds joins that aren’t declared as DDL constraints. Stored alongside formal FKs with confidence scores, returned by qs_get_relationships.
(98% overlap, conf 0.95)
Same prompt, different SQL
The proof is in the SQL the AI tool actually writes. Same Cursor session, same Claude model, same prompt — “What were the top 5 products by revenue in the last 30 days?” Without Schema Intelligence the LLM has to guess. With it, the LLM knows.
si_recommendation block telling the AI exactly what it’s missing — including a one-call option to enable SI mid-conversation via qs_request_si_analysis. Your AI client can offer to trigger an SI run on the spot (“would you like me to enable Schema Intelligence on this database first? It runs through your Network Agent in the background and will dramatically improve my answers”). Run time scales with table count: a small database under 100 tables completes in around 10 minutes; a typical mid-size database (a few hundred tables) finishes in 15–25 minutes; a large enterprise database with 1,500+ tables can take 45–60 minutes for a full scan. Subsequent refreshes after schema changes are incremental and much faster than the first run. Schema Intelligence is opt-in. We just don’t think you’ll want to opt out.
MCP not for you? Try Nova AI instead.
Skip the JSON config entirely: Nova AI is built into the Query Streams web portal and asks the same plain-English questions across your PostgreSQL connector — “top 10 customers by lifetime value,” “orders that haven’t shipped in over 7 days” — plus every other connector on your account, with the same agent, read-only enforcement, and Schema Intelligence, and no MCP plumbing.
Meet Nova AIPrerequisites
Before you start, make sure you have:
- A free Query Streams account at my.querystreams.com.
- The Query Streams Network Agent installed on a machine that can reach your PostgreSQL cluster — see Download the Query Streams Agent.
- A PostgreSQL connector configured against the agent — see the existing connector setup guides for the connection string. The agent holds the Postgres password (or IAM credentials for managed Postgres); the AI tool never touches them.
- Any MCP-capable AI client. We’ll show Cursor, Claude Desktop, ChatGPT, and Grok in this guide; if you use Windsurf, Zed, Continue, Cline, VS Code Copilot, Codex, or Goose, the config block is essentially the same.
- Five minutes.
Drop it into your AI client
One JSON snippet for Cursor, Claude, ChatGPT, or Grok. Same key everywhere.
Ask a question
“What were our top 10 customers by lifetime value?” — the AI calls the right tools, you get the answer.
Step 1: Generate an MCP key in Query Streams
Sign in to Query Streams and open the MCP page (or sign in first at my.querystreams.com and click MCP in the left navigation). Click Generate key, give the key a recognizable name (something like cursor-laptop or claude-desktop), and pick the scopes you want this key to have:
read— the AI can browse connectors and read schema. Required for everything else.analyze— the AI can profile tables and discover relationships (sample values, distributions, semantic types). Optional but strongly recommended for Postgres work, where understanding the shape of your data matters when the LLM is generating joins.execute— the AI can actually run SQL. Without this, the AI is read-only against schema metadata only.
For a typical “let Claude analyse my Postgres data” workflow, all three scopes are appropriate. For a key you’re handing to a teammate or a less-trusted client, drop execute and let them browse only. You can revoke any key at any time from the same page; the AI client will see MCP_KEY_REVOKED on its next call and stop working immediately. There’s no propagation delay.
Copy the key now — Query Streams shows it once, then stores only a hash. If you lose it, generate a new one. The key looks like qsmcp_ followed by 48 random characters and is what your AI client sends in the X-MCP-Key request header.
Step 2: Add Query Streams MCP to your AI client
The configuration is the same shape across every MCP-capable client — an MCP server entry pointing at https://mcp.querystreams.com with your key in the X-MCP-Key header. Pick your client below.
// Edit ~/.cursor/mcp.json { "mcpServers": { "querystreams": { "url": "https://mcp.querystreams.com", "headers": { "X-MCP-Key": "qsmcp_PASTE_KEY_HERE" } } } }
// Settings → Developer → Edit Config { "mcpServers": { "querystreams": { "url": "https://mcp.querystreams.com", "headers": { "X-MCP-Key": "qsmcp_PASTE_KEY_HERE" } } } }
// Settings → Apps & Connectors → Add MCP Server URL https://mcp.querystreams.com Auth header X-MCP-Key Header value qsmcp_PASTE_KEY_HERE // Requires a paid ChatGPT plan // (Plus / Pro / Team / Enterprise).
// Grok → Settings → Tools { "mcp_servers": [{ "name": "querystreams", "url": "https://mcp.querystreams.com", "auth_header": "X-MCP-Key", "auth_value": "qsmcp_..." }] }
Restart your AI client. On its next start it will discover the eight Query Streams MCP tools listed above and surface them in its tool palette. In Cursor and Claude Desktop you can verify by typing “list connectors” — the AI should call qs_list_connectors and return your PostgreSQL connector along with anything else you have configured.
Step 3: Ask the AI a PostgreSQL question
You don’t write SQL — the AI does. You ask a question, the AI picks the right MCP tool, the agent runs the query against your Postgres database, and the answer comes back as text plus tables. Three example prompts to try first:
customers to orders to line_items, computes SUM(qty * unit_price) per customer, and returns the top 10 by lifetime value. You’ll see the result table inline, plus a written interpretation — which customers are concentrated in which products or regions, repeat-purchase patterns, average order size — that the AI inferred from the data.orders.status to filter to 'paid' orders that have a NULL shipped_at and a created_at older than NOW() - INTERVAL '7 days'. The result is a focused list with order id, customer email, total, and days-since-paid — usually the AI sorts by oldest first and flags the most concerning ones, which are fulfillment-team escalations rather than rounding errors. You can drill in by asking “why is order 4821 still pending?” and the AI will pull the relevant rows.DATE_TRUNC('month', o.created_at) and date arithmetic, and will typically follow up with “want me to chart this by week?” or “want to see the same comparison split by acquisition channel?” if you have those columns in another table. Conversational; you don’t need to reset context between questions.The first time the AI calls a tool, your client may pop up a confirmation prompt asking you to approve the tool call — that’s MCP’s standard consent flow, not anything Query Streams adds. Approve once and the AI proceeds with the rest of the conversation freely. You can revisit the consent at any time in your client’s settings.
Honest billing notice: MCP usage is charged on uncompressed bytes
Query Streams’ Excel add-in, Google Sheets add-on, web Query Builder, and Nova AI all run over our compressed cloud link — we measure and bill compressedBytes against your data realm. The MCP transport (Streamable HTTP per the official MCP spec) does not reliably support compression end-to-end across every client and intermediate proxy, so we measure and bill uncompressedBytes for MCP traffic.
- What this means: a 1 MB Postgres result set costs ~1 MB of your data realm when fetched via MCP, vs. ~150–250 KB via Excel / Sheets / Nova / the Query Builder. A 10,000-row aggregate query that lands as ~2 MB of JSON over MCP would have been ~300–400 KB of LZ4-compressed bytes through the Excel / Sheets / Nova / Query Builder clients. Same data, different transport, different billable size.
- What this isn’t: a markup or a punishment for using MCP. We pass through actual bytes shipped. The other clients are cheaper because compression works reliably on those transports; we don’t punish you for the protocol choice, but we have to be transparent about the cost shape.
- What you can do: for very large recurring queries (e.g. 100K+ row exports), prefer the Excel / Sheets / Nova path. For interactive AI tool calls (the typical 100–5,000 row Postgres response that fits in an LLM context), MCP is the right choice and the cost difference is in cents.
Frequently asked questions
Do I need to open ports or run a VPN to use this? +
https://mcp.querystreams.com from the public internet — if outbound HTTPS works on the agent host, MCP works. See how the outbound-only connection works →
Which AI tools can I use with Query Streams MCP? +
Can I revoke an MCP key? +
/mcp page, per-org via plan settings, and platform-level), none of which need a database password rotation or agent restart. More on MCP key security →
How is MCP usage billed against my data realm? +
compressedBytes); MCP runs over Streamable HTTP, which doesn’t reliably support compression end-to-end through every client and proxy, so we bill uncompressedBytes. A 1 MB Postgres result returned to Excel typically costs ~150–250 KB of your data realm; the same 1 MB result returned to Cursor over MCP costs ~1 MB. We’re transparent about it because we’d rather you know up front than be surprised at the end of the billing cycle.
Does Query Streams MCP work with my managed PostgreSQL on AWS RDS, Azure Database for PostgreSQL, or Google Cloud SQL? +
How does this differ from running an open-source PostgreSQL MCP server myself? +
event_logs, and the same data-realm billing pipeline you already use — none of which a direct MCP gives you.
What happens if the AI tries to write or delete data? +
qs_run_query call is parsed by a hardcoded read-only validator that allows only SELECT, WITH, and EXPLAIN statements; anything else returns READONLY_VIOLATION and never reaches PostgreSQL. The validator runs in the agent process on your network, not in the cloud, so a compromised cloud surface couldn’t bypass it. (You can layer a Postgres-side READ ONLY role on top if you want belt-and-suspenders — the agent’s validator is independent of whatever Postgres role you’ve configured.)
Can I see what the AI actually asked? +
event_logs with the org, user, key, scope, latency, and result code. The org-admin can answer “who used MCP last week, which connector, and what did they ask?” with a single query. Note that we log the tool name and metadata, not the SQL text or returned rows — those flow through the cloud link and never land in cloud logs. If you want full SQL audit, enable database-side audit on the underlying engine; for Postgres specifically that’s pgaudit or your existing query-log pipeline.
Do I have to run Schema Intelligence to use Query Streams MCP? +
(connector, database) pair, and MCP works fine without it. The AI gets bare schema (types, primary keys, formal foreign keys, indexes) and writes basic queries. With SI enabled, the AI gets six additional layers of curated metadata: (1) AI-curated descriptions on every database, table, and column; (2) table classifications (FACT for transactional events, DIM for descriptive reference, LOOKUP for small code maps) plus a business domain tag (sales, hr, seo, finance, support, and 14 more); (3) a semantic type on every column (currency, email, date_iso, status_code, percentage, ranking_position, identifier, url, person_name, and 9 more) that drives dialect-correct Postgres SQL generation; (4) sample values from your real data so the LLM recognises patterns no schema can show; (5) enum detection with full value distributions for low-cardinality columns; and (6) AI-discovered foreign keys based on cross-table data overlap, surfaced through qs_get_relationships. Without SI, every schema-tool response also carries an si_recommendation block listing exactly what’s missing for the call — the AI can read this and offer to trigger SI mid-conversation via qs_request_si_analysis. Run time scales with table count: a small database under 100 tables completes in around 10 minutes; a typical mid-size database (a few hundred tables) finishes in 15–25 minutes; a large enterprise database with 1,500+ tables can take 45–60 minutes for a full scan. SI runs through your Network Agent against your data (never in the cloud), never writes to your database, never changes your schema, and refreshes incrementally when your schema changes — so subsequent runs after you add or alter tables are much faster than the first one. The end-to-end effect: with SI enabled, your AI client writes correct SQL on the first try far more often than it does against any “MCP for X” server that just hands the LLM information_schema.
What if I add another connector later, like Stripe or PostgreSQL? +
qs_list_connectors picks it up automatically). One config block buys your whole account, present and future. Why one key covers every connector →
Do I have to set up MCP just to chat with my data? +
Get started
Connect your AI tool to your PostgreSQL data in five minutes.
One MCP key reaches PostgreSQL, every other database, and every API connector in your Query Streams account — with full audit trail, per-key rate limits, and zero firewall changes. Claude, Cursor, ChatGPT, and Grok all work out of the box.
Related guides: Download the Query Streams Agent | Database Connector Setup | All MCP Server guides | Nova AI text-to-SQL
Category: MCP Server
Tags: mcp, claude, cursor, postgresql, postgres, postgres-mcp, ai
Meta Description: Connect Postgres to Claude or Cursor via Query Streams MCP. Outbound-only, read-only, 5-min setup.


