Connect Query Streams to Claude and ask questions about your databases in plain language. Claude reads your schema, your saved queries and your Schema Intelligence model live, runs read-only SQL through your Network Agent, and never sees a database password. This guide covers claude.ai, Claude Desktop 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. After that, Query Streams is in the Anthropic Connectors Directory. In claude.ai open Settings → Connectors → Browse connectors, find Query Streams, 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. What changes by plan is how many keys or connected apps you can hold and how many calls a minute Claude may make; Free allows one key or one connected app and 30 calls a minute.
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 Claude
There are two ways in. Chat apps use OAuth and need no key. Developer tools use an MCP key. Both reach the same server and the same tools.
Option A: claude.ai and Claude Desktop (OAuth, no key)
Listed in the Anthropic Connectors Directory. Query Streams is an approved connector: claude.ai/directory/query-streams. On claude.ai and in Claude Desktop you can connect it with one click from Browse connectors; no server URL needed. The custom-connector route below still works and is what to use if your Claude organization restricts directory connectors.
- On claude.ai open Settings → Connectors → Browse connectors, search for Query Streams and click Connect (or open the directory listing directly). In Claude Desktop the same option is under Settings → Connectors. Can’t see it? Your organization may restrict directory connectors: click Add custom connector instead, name it Query Streams and paste
https://mcp.querystreams.com/mcp. - Open any chat, click the + button by the message box, 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 → Connected Apps tab.
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 Settings → Connectors → Add.
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 → My Keys and click Generate key. Name it after the tool and machine, such as claude-code-laptop, and pick its scopes.
- Copy the key now. You can show and copy it again later from My Keys. Keys look like
qsmcp_followed by 43 characters. - For Claude Code, run:
claude mcp add --transport http querystreams https://mcp.querystreams.com/mcp --header "X-MCP-Key: qsmcp_PASTE_KEY_HERE" - For Cursor, VS Code, Windsurf, Zed, JetBrains, Gemini CLI, Codex CLI, Continue and Cline, open the MCP → Connect tab in the Portal. It shows a ready-to-paste config for each client with your key already filled in.
To verify, ask “What Query Streams connectors do I have?” The client should call qs_list_connectors and the key’s last used time updates on the My Keys tab 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 Schema Intelligence descriptions, list saved queries and alert rules. | Always. Everything else builds on it. |
| analyze | Profile tables (sample values, distributions, semantic types), discover implicit relationships, and queue a Schema Intelligence run. | Recommended. This is what lets Claude understand the shape of your data before writing joins. |
| execute | Run read-only SQL and saved queries and stream rows back. | 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 MCP page.
What Claude can do once connected
Claude sees a small set of tools. You never call them yourself; Claude picks the right one for your question. In plain terms:
Understand 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.
Use your saved queries
List your organization’s saved, parameterized queries and run them with different parameters. Federated queries that span several sources run server-side and return already-joined rows.
Run ad-hoc SQL
Write and run read-only SQL in the right dialect for the connector. Results default to 1,000 rows and a 60-second timeout, both adjustable.
Check alerts
List alert rules, see their current state and recent firings. Claude can propose a new rule in dry-run mode; a person arms it on the Alerts page.
Improve the model
Check Schema Intelligence coverage per database and, with your agreement, queue an analysis run so future answers are better.
Why Schema 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 |
|---|---|---|
| Schema 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 Schema Intelligence on it once. For large databases, scope the run to the tables your queries actually use. How Schema 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 Schema 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. 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. Because MCP runs over HTTP without end-to-end compression, it is measured in uncompressed bytes, so a 1 MB result costs about 1 MB, where the same result to Excel typically costs 150 to 250 KB. Keep
preview_limitsensible for exploratory questions. - Schema 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. | 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 key is restricted to specific connectors and this isn’t one of them. | Edit the key’s connector allowlist on My Keys, or use a different key. |
MCP_DATABASE_NOT_CAPTURED | The database isn’t in the connector’s schema-capture selection, so there is no Schema 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 Schema Intelligence. |
MCP_RATE_LIMITED | Too many calls per minute for your plan. | Wait a moment. Heavy sessions benefit from Schema 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 Claude in one response. | Ask for fewer columns or rows. Claude will usually suggest this itself. |
| 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, Schema Intelligence descriptions including sample values, and the results of queries you ask for. Those results are 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 Schema 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 MCP page has a ready-made config for each.
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 Schema 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