Connect Query Streams to Claude and ask questions about your databases in plain language. Claude reads your schema, your saved queries and your Semantic Intelligence model live, runs read-only SQL through your Network Agent, and never sees a database password. Your AI client asks; the Network Agent, its partner inside your network, does the heavy lifting where the data lives. This guide covers claude.ai, Claude Desktop, ChatGPT and Claude Code, plus every other MCP client.
Short version. Install the Network Agent next to your database once (a few minutes) and add a connector. Then open the Query Streams listing in Anthropic’s Connectors Directory, click Connect, approve the permissions on the Query Streams consent screen, and ask Claude “What databases do I have access to?” Claude can only see data an Agent serves: skip the Agent and it will tell you there are no connectors.
Before you start
You need four things. If you found Query Streams from inside Claude, the Agent and a connector are the two you still have to set up.
A plan that includes MCP
MCP is on every plan, including Free. Your plan sets how many keys or connected apps you can hold, how many calls a minute your AI client may make and how many rows one query returns, and whether the Analytic toolset is included. What each plan includes.
A Network Agent that is online
The agent is the small service that sits next to your database and makes one outbound connection to Query Streams. New account? Install it now from my.querystreams.com/download, a few minutes on Windows, macOS or Linux. If your team already runs queries in the Portal, Excel or Google Sheets, it’s installed.
At least one connector
A connector is a database or API source registered in the Portal. Claude sees every connector your account can see, subject to the permissions you grant.
MCP access on your user
Org creators and owners have MCP access automatically. Other users need an admin to tick MCP next to their name in Account → Access Control.
How it works
Claude never connects to your database. It talks to the Query Streams MCP server in our cloud, which relays each request over the single outbound connection your Network Agent already holds open. The agent runs the query locally and streams the rows back the same way. Requests and results flow both directions over that one agent-initiated channel, so nothing needs to be opened on your firewall.
OAuth, scopes, audit, rate limits
one outbound TLS connection
Three properties fall out of that design:
- No credentials in Claude. Your database connection string lives on the agent. Claude holds only an OAuth grant or an MCP key, both of which you can revoke from the Portal in one click.
- Read-only, enforced at the agent. Only
SELECT,WITHandEXPLAINstatements are accepted. The check happens on your side of the connection, not in the cloud and not in Claude. - Everything is logged. Every tool call appears in the MCP page’s Activity tab and every query in Query History, attributed to the user who connected.
Connect your AI client
The MCP page in the Portal (Streams → Live → MCP) has four tabs: Connections, Context, Tools and, for admins, Activity. On Connections, the Connect an AI client button opens a four-step guide: How will your AI client connect?, Pick your AI client, Set it up and Check the connection. There are two ways in. Chat apps approve from the app and need no key. Developer tools use an MCP key. Both reach the same server and the same tools.
Option A: claude.ai, Claude Desktop and ChatGPT (approve from the app, no key)
Listed in the Anthropic Connectors Directory. Query Streams is an approved connector: claude.ai/directory/query-streams. Open the listing, click Connect and approve; no server URL needed. Adding it by URL is the fallback for Claude organizations that restrict directory connectors.
- Open the Query Streams listing and click Connect. The connector syncs to your Claude account, so Claude Desktop shows it under + → Connectors. Can’t see the listing? Your organization may restrict directory connectors: in Settings → Connectors click Add custom connector, name it Query Streams, paste
https://mcp.querystreams.com/mcp, then in a chat click +, choose Query Streams and click Connect. - A new browser tab opens the Query Streams consent screen. Sign in if asked, pick the organization, review the permissions (see below), and click Approve connection.
- Back in Claude you’ll see Connected to Query Streams. The first time Claude uses a tool it asks permission. Choose Always allow so it can work without prompting on every call.
The connector is tied to your Claude account, not one device, so it appears in the Claude mobile apps and Claude Desktop automatically. Manage or revoke it any time from the Portal’s MCP → Connections tab.
ChatGPT. Add Query Streams from the app itself: for now that means turning on developer mode in ChatGPT’s settings and creating the connection there, then clicking Sign in with Query Streams and approving on the same consent screen. The Portal guide shows the current ChatGPT steps; an official ChatGPT listing is on the way.
Not the same as “Add marketplace”. In Claude Desktop the in-chat + → Browse connectors → Add marketplace option wants a git repository for plugin marketplaces, not an MCP server URL. Use the listing’s Connect button, or Settings → Connectors → Add for the URL route.
Option B: Claude Code, Cursor and other developer tools (MCP key)
Developer tools authenticate with a key you generate in the Portal and pass in the X-MCP-Key header.
- Sign in at my.querystreams.com, open MCP and click Connect an AI client. Choose Use a key in a config file and pick your tool.
- Click Generate a key for your tool. Name it after the tool and machine, such as claude-code-laptop, keep Read and Run queries, and choose an expiration. You can reveal and copy the key again later from the Connections tab. Keys look like
qsmcp_followed by 43 characters. - Set it up shows the ready-to-paste config for Cursor, VS Code, Windsurf, Zed, JetBrains, Gemini CLI, Codex CLI, Continue, Cline and more, with your key already filled in. For Claude Code it is one command:
claude mcp add --transport http querystreams https://mcp.querystreams.com/mcp --header "X-MCP-Key: qsmcp_PASTE_KEY_HERE" - Check the connection waits for the first call from that key and says Connected.
To verify at any time, ask “What Query Streams connectors do I have?” The client should call qs_list_connectors, and the key’s Last used time on the Connections tab updates within seconds.
Permissions
Whether you connect by OAuth or by key, access is controlled by three scopes. The consent screen shows them; a key is created with them.
| Scope | What Claude can do | When to grant it |
|---|---|---|
| read | List connectors and agents, browse schema, read Semantic Intelligence descriptions and the stored column profiles and relationships, list saved queries and alert rules. | Always. Everything else builds on it. |
| analyze | Profile a table or discover implicit relationships live on the Network Agent, and queue a Semantic Intelligence run. Without it, your AI client does not see the tools that start a Semantic Intelligence run. | Recommended. This is what lets Claude understand the shape of your data before writing joins. |
| execute | Shown as Run queries (read-only). Run read-only SQL and saved queries and stream rows back; hold results and run the follow-up and analysis tools over them. | For anyone who should get answers, not just browse structure. Leave it off for a browse-only key. |
A connected app can be limited to specific connectors when you approve it; a generated key reaches every connector in the organization. Revoking a grant or key takes effect within about five minutes. Admins can see every active grant and key for the organization on the Connections tab.
What your AI client can do once connected
Your AI client sees the Query Streams tools and picks the right one for your question; you never call them yourself. The Portal’s Tools tab lists every tool and mode, what each does, and which your plan includes.
For a question about your data, Query Streams guides your AI client through four steps: list your connectors, read the database’s tables, read the columns of each table it will query, then run a read-only query. Reading the columns first is what keeps it from guessing names. On every plan, Free included:
Map your data
List connectors, databases and agents. Read the schema tree for any database with table and column descriptions, semantic types, sample values, enum labels, and both declared and discovered relationships.
Profile and explore
Profile a table to see real value distributions before writing a filter. Discover joins between tables that have no foreign keys declared.
Run read-only SQL
Write and run read-only SQL in the right dialect for the connector. A 60-second timeout by default, up to five minutes; your plan sets how many rows one query returns.
Saved queries, federated and alerts
Run your organization’s saved, parameterized queries with new values; federated queries that span several sources come back already joined. Read alert rules and their recent firings, and propose a new rule in dry-run mode.
The Analytic toolset
On paid plans the Network Agent does the groundwork where your data lives: it measures, profiles, holds and analyzes results, so your AI client walks into each question with the context already prepared and spends its attention on the thinking. The Free plan works as it always has, with standard results. The full walk-through is in Analyse your data with your AI client.
Context management
Personal Core and up. Size a result before reading it (shape): columns, row estimate and token cost, no rows. Walk a large database area by area (schema levels). Keep answers inside a token budget, with only the columns and text cell lengths it needs.
Result analysis
Personal Core and up. A profile of the whole result instead of rows. Held results, with labels, answer follow-ups such as “break it down by region” or “the next 50 rows” with no second database query. Data freshness and changed-since read only what is new.
You stay in control. The Context tab sets the defaults: the text cell limit, the schema view for large databases, result size and the analysis defaults, and shows what your AI client receives. It also lists the results each Agent is holding. Each key can override the defaults, every call is on the Activity tab, and an admin can turn Local analysis off for an Agent under Data → Data Agents.
What your plan includes
MCP is on every plan, including Free, and the Free plan never expires.
| Plan | Keys per user | Keys per organization | Calls per minute | Rows per query | Analytic toolset | Held results |
|---|---|---|---|---|---|---|
| Free | 1 | 1 | 30 | 1,000 | Standard results | None |
| Personal Core | 1 | 1 | 60 | 2,500 | Context management, Result analysis | 15 minutes, 128 MB |
| Personal Plus | 1 | 1 | 90 | 5,000 | Context management, Result analysis | 15 minutes, 128 MB |
| Business Core | 2 | 3 | 120 | 10,000 | Context management, Result analysis, Deeper analysis | 60 minutes, 512 MB |
| Business Plus | 3 | 5 | 150 | 25,000 | All three | 60 minutes, 512 MB |
| Business Max | 5 | 10 | 240 | 50,000 | All three | 60 minutes, 512 MB |
| Enterprise Core | 5 | 25 | 300 | 100,000 | All three | 8 hours, 4,096 MB |
| Enterprise Plus | 8 | 50 | 450 | 100,000 | All three | 8 hours, 4,096 MB |
| Enterprise Max | 10 | 100 | 600 | 100,000 | All three | 8 hours, 4,096 MB |
A connected app counts as a key. On every plan, any one key also runs at most 10 queries a minute. Rows per query is the most rows one query returns to your AI client; asking for more returns your plan’s limit and says so, never an error. A held result is kept for follow-up questions up to the plan’s time and size, within what the Agent’s computer can spare. Every plan side by side: pricing.
Why Semantic Intelligence matters here
Every response Claude receives is tagged with which of three tiers it came from, and Claude adjusts how much it trusts what it sees.
| Tier | What Claude sees | Result |
|---|---|---|
| Semantic Intelligence | Descriptions for every table and column, semantic types, enum labels, sample values, fact and dimension classification, declared and discovered joins. | Claude writes production-quality SQL on the first try and explains the data in your business terms. |
| Captured schema | Table and column names, types, primary keys, indexes, declared foreign keys. | Claude works, but has to infer meaning from names and may need a follow-up question. |
| Live schema | The database isn’t in the connector’s capture selection, so structure is read live from the catalog on each request. | Queries still run. Claude explores with sample selects when it needs more. |
If a database matters to your team, run Semantic Intelligence on it once. For large databases, scope the run to the tables your queries actually use. How Semantic Intelligence works →
Example prompts
Start with something you already know the answer to. Then ask follow-ups; Claude keeps the context.
What databases and tables do I have access to, and which of them have Semantic Intelligence?Maps your connectors and tells you where answers will be strongest. Show me how customers relate to orders in the sales database, and profile the order status column.Uses relationships and column profiling. Claude will show you the actual status codes and what they mean. Run the saved query “Monthly revenue by region” for the second quarter of this year.Runs a trusted saved query with parameters instead of inventing its own SQL. Top 10 products by revenue in the last 90 days. Then break that down by channel.Ad-hoc SQL in the connector’s dialect, then a follow-up on the same thread. On plans with Result analysis the follow-up can come from the held result, with no second query. Which alert rules are configured, and did any of them fire this week?Reads alert rules and their recent state.Tips for better answers
- Use a Claude Project. Attach the Query Streams connector to a Project and put your business rules in the project instructions: which database to use by default, which saved queries are the official definitions, naming conventions. Claude still reads the schema live, so the instructions stay short.
- Save the queries you consider canonical. Claude reaches for saved queries first, so “active customers” means what your team says it means.
- Grant the analyze scope. Profiling a column before filtering on it is the difference between guessing a status code and using the right one.
- Ask for a chart. claude.ai renders charts from the rows Claude gets back.
What it costs
MCP itself has no separate fee on any plan. Two things are metered:
- Data volume. Query results returned to Claude count against the same data-realm budget your Excel, Google Sheets, Portal and Nova usage share. Over MCP they are measured as every byte delivered to Claude — results, schema reads and held-result pages, before any transport compression — because an AI client receives them uncompressed; spreadsheet, Portal and API results count the compressed result your Network Agent delivers. A failed reply never counts. Keep exploratory questions small; on plans with Context management, asking Claude to size a result first (mode: shape) avoids pulling rows it does not need.
- Semantic Intelligence runs. Queuing an analysis through Claude bills AI credits to your organization, exactly as running it from the Portal does. Claude asks before it does this.
Troubleshooting
| What you see | What it means | Fix |
|---|---|---|
| Claude says there are no connectors, or no Network Agent | Your account has no Agent running yet, or the Agent has no data source added. | Install the Agent from my.querystreams.com/download, add a connector under Data → Data Agents → Add connector, then ask again. |
| Claude shows no Query Streams tools | The connector was added but not connected from a chat, or the OAuth approval was never completed. | Open a chat, click +, choose Query Streams, Connect, and finish the consent screen. |
MCP_KEY_REQUIRED or 401 | No key or grant reached the server. For key clients this is usually a copy-paste error such as a trailing newline, or the key in the wrong header. | Re-copy the key into the X-MCP-Key header. For claude.ai, reconnect from the + menu. |
MCP_TOKEN_EXPIRED | The OAuth token has expired after an idle period. | Claude normally refreshes on its own. If not, disconnect and reconnect the connector. |
MCP_KEY_REVOKED or MCP_USER_DISABLED | The key was revoked, or MCP access was switched off for your user. | Generate a new key, or ask an admin to re-enable MCP on Account → Access Control. |
MCP_SCOPE_REQUIRED | The grant or key lacks the scope for that action, most often execute (Run queries). | Reconnect and approve the missing scope, or generate a key that includes it. |
MCP_PLAN_LAPSED | Your organization’s subscription has lapsed. | The MCP page in the Portal shows the current plan state and the way forward. |
MCP_AGENT_NOT_CONNECTED | The Network Agent that owns the connector isn’t connected right now. | Check Data Agents in the Portal. Start the agent service on its host. |
MCP_CONNECTOR_NOT_ALLOWED | The connected app was limited to specific connectors when it was approved, and this isn’t one of them. | Reconnect the app and approve broader access on the Query Streams consent screen. |
MCP_DATABASE_NOT_CAPTURED | The database isn’t in the connector’s schema-capture selection, so there is no Semantic Intelligence or stored relationships to read. Queries still work. | Add the database to the capture selection on the connector in the Portal, then optionally run Semantic Intelligence. |
MCP_RATE_LIMITED | Too many calls per minute for your plan. | Wait a moment. Heavy sessions benefit from Semantic Intelligence, which lets Claude answer in fewer calls. |
MCP_QUERY_TIMEOUT | The query ran past its timeout, 60 seconds by default. | Ask Claude to add a filter or a lower row limit, or raise timeout_seconds up to 300. |
MCP_OUTPUT_TOO_LARGE | The result was too big to hand to your AI client in one response. | Ask for fewer columns or rows. On plans with Context management, ask it to size the result first. |
MCP_FEATURE_NOT_INCLUDED | “Your plan does not include Context management”, Result analysis or Deeper analysis; or the tool is switched off for this key or organization. | Ask your AI client to carry on without it, move up a plan, or ask an admin to switch the tool on. |
MCP_RESULT_EXPIRED | The held result is not held any more: it expired, was released (sometimes early, to make room for a newer result) or the Agent restarted. | Ask your AI client to run the query again with hold. |
MCP_WINDOW_BUDGET | The Agent cannot keep a result of that size right now, or a follow-up needs more memory than it allows for held results. | Release a held result, or narrow the query with a filter or fewer columns. |
MCP_AGENT_ANALYSIS_DISABLED | Held results and analysis are switched off on that Agent, or for that connector. | Ask an admin to turn on Local analysis for the Agent on the Data Agents page, or allow analysis on the connector. |
MCP_WINDOW_SQL_REJECTED | A follow-up was not one read-only SELECT over the held result’s tables, or it named a column the result does not have. | Ask for one SELECT over that result, using its column names. |
MCP_AGENT_VERSION_TOO_OLD | The Agent needs an update before it can shape, profile, hold or analyze results. | Update the Agent from Data → Data Agents. Plain queries keep working meanwhile. |
| A query fails on a column or table name | Your AI client guessed a name instead of reading the table first. | Usually nothing. The error it receives lists the table’s real columns, or tables with a similar name, so it can correct the query on its next try. If it keeps guessing, ask it to read the table’s columns first. |
| Read-only violation | The SQL contained something other than SELECT, WITH or EXPLAIN. | By design. Writes are never accepted through MCP. |
Still stuck? Email [email protected].
Security and privacy
- Claude receives schema metadata, Semantic Intelligence descriptions including sample values, and the results of queries you ask for. With the Analytic toolset it often receives a size estimate, a profile or a held-result answer instead, and the full result stays with the Agent. What it receives is transmitted to the AI provider you chose to connect, under that provider’s terms.
- Query Streams does not receive or store your Claude conversation.
- OAuth grants and keys are per user and per organization. An admin can see and revoke every grant and key from the MCP page.
- Full details are in our Privacy Policy and Terms of Service.
Frequently asked questions
Do I need to open a port or run a VPN?
No. The agent makes one outbound TLS connection on port 443. If outbound HTTPS works, MCP works.
Can Claude change my data?
No. The agent accepts only read statements. Claude can queue a Semantic Intelligence run and propose an alert rule in dry-run mode; both write to Query Streams metadata, never to your database.
Which other AI tools work?
Anything that speaks MCP: ChatGPT, Cursor, Claude Code, Windsurf, Zed, VS Code Copilot, JetBrains AI, Gemini CLI, Codex CLI, Continue, Cline and more. The Portal’s Connect an AI client guide has a ready-made config for each.
What is a held result?
On plans with Result analysis, your AI client can ask the Agent to keep a complete result for a while. Follow-up questions, such as a breakdown by region or the next page of rows, are then answered from that copy with no second database query. How long and how large a held result may be grows with the plan.
Which plans include the Analytic toolset?
Context management and Result analysis come with Personal Core and up; Deeper analysis with Business Core and up. The plan table has the details.
Does this change the Free plan?
No. The Free plan works as it always has, with standard results.
Does it work with several organizations?
Each grant or key is bound to one organization. Connect once per organization you need.
What’s the difference between this and Nova?
Nova is the assistant built into the Query Streams Portal and shares the same Semantic Intelligence model. Use Nova when you want answers inside Query Streams; use MCP when you want your data inside Claude alongside everything else you do there.
Connector-specific guides
Each guide walks through the same connection with examples for that source.
Databases: Microsoft SQL Server · PostgreSQL · MySQL · MariaDB · Oracle · Snowflake · Google BigQuery · SQLite · Microsoft Access · DuckDB · Supabase
APIs: Stripe · Shopify · HubSpot · Google Ads · Google Analytics 4 · Google Search Console · ShipStation · iTick
Folders of files and logs (the Agent scans a folder and turns the files into tables): File System · CSV Folder · Parquet Folder · Excel Folder · SQLite Folder · JSONL Folder · Multi-record CSV · Machine Logs · Web Server Logs · Container Logs · Application Logs · System Logs · Custom Logs
Hosted databases (managed PostgreSQL, MySQL, MariaDB and SQL Server, reached by the Agent over TLS): Neon · Amazon RDS · Azure Database for PostgreSQL · Azure Database for MySQL · Azure SQL · Google Cloud SQL · Google AlloyDB · DigitalOcean Managed Databases · Aiven · Crunchy Bridge · Heroku Postgres · Render · Railway · Fly.io Postgres · Vultr Managed Databases · OVHcloud Managed Databases · Scaleway Managed Databases · OCI Database with PostgreSQL · MySQL HeatWave · IBM Cloud Databases for PostgreSQL · MariaDB SkySQL · Xata · Timescale Cloud · PlanetScale Postgres · Prisma Postgres · Koyeb · Nile
Connect Claude to your data
Install the Agent once, a few minutes. After that, connecting Claude is one click: no key, no config file, no VPN. Read-only by design.
Install the Agent Open the MCP page How MCP works
English 
Spanish 
German 
French 
Portuguese 
Japanese 
Korean 
Chinese 
Italian 
Dutch 
Indonesian 
Polish