Local MCP server

Connect Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor or VS Code to Querylab.io. Your AI tool can explore BigQuery schemas, check SQL, estimate costs and run queries through the desktop app, within limits you set.

Querylab.io Desktop provides a local MCP (Model Context Protocol) server. A connected AI tool uses your Querylab.io session to work with BigQuery. The project it bills, its cost limits and the approval of writes are handled in the app.

Connect an AI tool

1. Open the desktop app and connect to your BigQuery project.
2. Open Settings → MCP.
3. Find your AI tool and click Install. The first installation turns on AI tools can connect automatically.
4. Complete any installation prompt in the AI tool.

For Claude Code, Codex and Gemini CLI, installation can include MCP + skills: the connection plus instructions that help the AI use Querylab.io’s BigQuery tools. The status shows which form is installed. If plugin installation fails, Install MCP only lets you install just the connection; an existing MCP-only installation can be upgraded later.

Try it

In your connected AI tool, ask:

Use Querylab.io to find the tables in my project and show me their columns. Don’t run a query yet.

Then try a query workflow:

Write a SELECT query for this table, validate it and estimate its cost before running it.

The tools can search schemas, sample tables, validate SQL, estimate query costs, explain routing, suggest optimizations, look up BigQuery documentation and run queries. Supply SQL directly from your conversation or project files. Available data and query execution depend on the project and permissions in your Querylab.io session.

Tools

Searching descriptions

A table search also matches table and column descriptions. A search for revenue after refunds finds a table whose description says so, even if no table name contains those words. Each result says whether the name or a description matched, and shows the matching text.

Descriptions are searched only for tables whose details Querylab.io has already saved, for example tables you or the AI tool have opened. Nothing is fetched for the search, because an account can hold thousands of tables. The result lists how many tables were not searched and in which datasets, so the AI tool knows a missing match is not proof. Asking for the columns of a table saves its details, and the next search covers it.

Approvals and the MCP tab

Reads run as soon as the AI tool asks: schema searches, samples, checks, cost estimates and SELECT queries. Your AI tool’s own permission prompt is where you approve those. The limits below still apply.

Writes wait for you by default. When write access is on and an AI tool sends INSERT, UPDATE, DELETE, MERGE or a schema change, Querylab.io shows a card with the SQL, the kind of change, the table and the project it runs in. Choose Run, Reject, or Open in a new tab to run it yourself. With no answer, the request is rejected after about ten minutes.

You do not have to answer quickly. The AI tool’s own call ends after about 25 seconds with a request id instead of a result, and the tool comes back for the answer with get_approval_result — every AI tool gives up on a call of its own after a minute or so, so a card held open longer than that used to leave it with a dead call. Nothing runs until you choose, and a card you answer minutes later still reaches the tool that asked. The card looks and behaves the same either way.

Taking the statement over

Open in a new tab answers neither Run nor Reject: it hands the statement to a query tab you drive. The tab opens with the route the AI tool asked for, nothing runs until you run it, and the AI tool is told its call did not run and that you took it over. The log records the decision as You opened it in a new tab. It is on the write card and on the limit card below.

How you know something is waiting

A call that waits comes back to the AI tool with a link that opens the request in Querylab.io. The link only opens it. The decision stays in the app, where the statement, the table it changes and the bytes it bills are on screen.

Outside the window:

• The MCP button in the header shows how many requests wait.
• The tray icon, which is the menu bar item on macOS, lists them. Show in Querylab.io opens one and Reject says no to it. Approve is offered only for a question about sharing rows, because its line says everything the answer needs: how many rows, and whether they go to the AI tool or to a file. A write and a lifted limit are answered on their card.
• Settings → Notifications → MCP approvals sends a system notification. It is on by default.

Running one call above a limit

An AI tool that is stopped by a limit can ask you to lift it for that one call. Every refusal for a cost cap, the daily limit, write access, a dataset rule or the project and routing settings tells it so.

When it asks, a card appears under Waiting for you with the AI tool’s own reason, the statement, and a line for each limit it would lift: the GB it wants to bill against your cap, how much of today’s limit is left, the rows it wants over your row limit, the statement it wants to run, or the dataset it wants to read or change. Choose Allow once, Don’t run it, or Open in a new tab to run the statement yourself.

Allow once runs that one call with exactly those limits lifted and nothing else. Here too the AI tool may have stopped waiting on its first call and come back for the answer; what you choose is what it gets. A write runs without a second Run or Reject card only when one of the lines on the card named that write, with the statement and the table it changes. Nothing is saved: the next call is held to your saved limits again, and a restart clears anything in flight. With no answer the request is rejected on the same ten-minute clock as a write.

A dataset you set to No access can only be asked for when the AI tool’s own SQL names it. Anything else it runs into in such a dataset, a table behind a view for instance, is refused without being named, so the rule never tells an AI tool what is in there.

The row limit can be lifted to 10,000 rows at most, however many the AI tool asks for. After Don’t run it the same request is refused if the AI tool asks again, even reworded, and at most three requests can wait at once.

An AI tool cannot ask for a statement Querylab.io never runs for AI tools, for a dataset list it could not read, or for your Share query results setting. Those stay in Settings → MCP.

The Write approval setting changes which writes wait. With Ask for schema changes only, INSERT, UPDATE, DELETE and MERGE run as soon as the AI tool sends them, and CREATE, ALTER, DROP and TRUNCATE still wait. With Don’t ask, no write waits. The log marks a write that ran this way as Ran without approval (setting).

The MCP activity tab

The cards are at the top of this tab, under Waiting for you. Click the MCP button in the header to open it. Below them the tab is, from the top:

• MCP is on and the port. Clicking the status turns the server off and back on. Other settings and limits opens Settings → MCP.
• Running now, while a call is working.
• the summary strip: four limits over four totals.
• one panel with a Log tab and an Activity tab. The time range (today, 7, 30 or 90 days) and the filters for client, tool and status sit beside those tabs and govern both, so the chart draws the calls the log lists. The totals in the strip are the whole range, filters or no filters.

The summary strip. The top row is what AI tools are allowed to do right now, whoever set it. Each reading is also where that limit is changed: click one and its editor opens over it, with the explanation under the field.

The bottom row is what the chosen range did: Queries run, Data billed (what BigQuery charged for, with a count of finished queries that report no billed figure), Cost, and Blocked or failed (with how many of those Querylab.io’s own limits turned away).

The Log tab lists every call with its time, client, tool, status, route, data, cost, rows and duration. Click a call to see the rest beside the log: the full SQL, the parameters the AI tool sent, the job, the approval decision and the error. Open SQL in a new tab copies the query into the editor, and Open job shows the BigQuery job.

The log opens filtered to execute_query, request_limit_increase and get_approval_result, the calls that spend money or wait for you. Clear the tool filter to see every call.

The Activity tab charts calls, data billed or cost per day, stacked by AI tool.

The log keeps 90 days on this computer. Settings → MCP → Activity history → Clear history deletes it for all accounts, and leaves today’s usage and the daily limit as they are.

Where AI tools run their queries

AI tools never use the project, limit or routing of the query tab you have open. They use the settings in Settings → MCP:

The daily limit counts what each query is estimated to scan when it starts, and replaces the estimate with the billed amount when the query ends. Queries that run at the same time, or that are still running, count too. Settings shows how much was used today and how much of it is held for queries still running. If the saved count cannot be read, AI tool queries are refused until you click Start today’s count from zero.

estimate_cost tells the AI tool whether a query fits within these limits before it runs, and get_limits reports the limits themselves with today’s numbers, so the AI tool can plan a query instead of finding out by being refused.

Limits and access

These settings are in Settings → MCP. They apply to connected AI tools only. Prism AI inside the app keeps its own behavior. They are saved on this device and stay after you sign out.

Write access

With write access off, a connected AI tool can only run one SELECT per call. Turn it on to allow INSERT, UPDATE, DELETE and MERGE, or also CREATE, ALTER, DROP and TRUNCATE.

By default every write waits on a card in the MCP activity tab that says it changes data and names the target table. The card says CREATE OR REPLACE or DROP ... CASCADE when the statement has them. The maximum GB per query and the daily limit are checked again when you click Run.

Write approval

Ask for each write is the default. Ask for schema changes only lets data changes run at once and keeps the card for schema changes; with write access set to data changes only, nothing is asked. Don’t ask runs every allowed write as soon as the AI tool sends it. Nothing else loosens: write access, dataset rules, the maximum GB per query and the daily limit all apply before the statement runs, and a write that breaks one is refused. The in-app Prism AI is not affected.

Scripts and several statements in one call are always refused. So are CALL, EXPORT DATA, LOAD DATA, EXECUTE IMMEDIATE, GRANT, REVOKE, transactions, and changes to row access policies, reservations or connections.

Dataset rules

A rule is a pattern and an access level. The pattern is project.dataset, and * matches any text inside one name, for example my-project.* or *.staging_*. The most specific rule wins. When two rules are equally specific, the stricter one wins. All other datasets covers everything no rule matches.

The tables a query touches come from BigQuery’s own dry run, so views, wildcards and default datasets are resolved before the rule is checked. A refusal names the dataset and the rule that blocked it, and nothing else about what is inside. Datasets with no access are also left out of counts in search_schema.

Project-wide INFORMATION_SCHEMA views show metadata for every dataset. To block them, add a rule for project.INFORMATION_SCHEMA.

If the saved rules cannot be read, every dataset is blocked until you save new rules.

Sharing results

Settings → Prism AI → Share Query Results Preview also applies to connected AI tools. Row counts, column names and types, and the reason code of a failed query reach the AI tool whatever you choose.

When rows are not shared automatically, the error text of a query that fails while running is withheld. It can contain values from your rows, such as Bad int64 value: '[email protected]'. The AI tool gets BigQuery’s reason code and location, and a note that the text is withheld. You can read the full error in the editor.

Large results and long queries

execute_query can write the full result to a file instead of putting rows in the conversation. Ask your AI tool for the result as a file when it is more rows than fit in context.

• The file is a CSV in the app’s data folder on your computer. The AI tool gets the path, the schema, the row count and a preview of the first rows: 20, or fewer when Max rows returned to AI tools is lower.
• The file stops at Max rows written to a file. It can also stop earlier: after about 50 seconds of writing, or at 900 MiB for one file. All result files together are limited to 5 GiB on disk. Whenever a file is cut, the reply says so.
• Files older than 24 hours are deleted the next time the app starts or saves a file.
• A file counts as sharing rows, so the sharing setting above decides whether it is allowed.

If a query is still running after about 35 seconds, execute_query returns a job id instead of waiting. The query keeps running on BigQuery and is billed as usual. The AI tool calls get_job_result with that id to wait longer and read the result, and cancel_job to stop it. Both work only for jobs that Querylab.io started for that client, for about six hours at most and not after the app restarts. Its estimate counts toward the daily limit from the start. When Querylab.io sees the job has ended, which happens when the AI tool asks about it, the estimate is replaced with the billed amount. A job nobody asks about again keeps counting at its estimate for the rest of the day.

When Querylab.io is closed

Connecting an AI tool never starts Querylab.io. The tool list is answered without the app. When the AI tool makes its first call and Querylab.io is closed, the call starts the app in the background and waits up to 30 seconds. That first call is slower. You may still have to sign in. On Windows the window may come to the front.

On macOS, closing the last window hides Querylab.io instead of quitting it, so the MCP server keeps answering and nothing has to start it again. The menu bar icon brings the window back, and Quit Querylab.io there, or Cmd+Q, really quits. On Windows the app still ends with its last window.

Settings → MCP → Start Querylab.io when an AI tool uses it controls automatic start and is on by default. Turning off AI tools can connect also stops automatic start. Turn this setting off too if you want to be sure an AI tool never starts the app. When automatic start is off, or the app cannot be found, the AI tool gets a message that says why. After a start that failed, later calls fail quickly for 30 seconds instead of trying again.

Connection and data

The MCP connection runs on your computer. BigQuery queries use the app’s connected project; a local MCP connection does not make BigQuery execution local. Rows, schema information and descriptions returned to the AI tool can be sent to its model provider as part of the conversation. Use the limits above to decide what can leave.

For running bq or Python against Querylab.io’s on-device SQL engine, use the separate Local BigQuery REST API. To use a CLI as the model provider inside Prism AI, see CLI integration.

Repair or disconnect

• Not detected: install or open the AI client, then refresh its status in Settings.
• Needs repair: click Repair to update the connection, for example after moving or reinstalling Querylab.io.
• Claude Desktop does not connect: quit it before installing or repairing the connection, then reopen it.
• Cursor or VS Code is still waiting: finish the installation in that app, then refresh the status in Querylab.io.
• Disconnect one client: click Uninstall. For VS Code, remove the querylab entry from the configuration file shown in Settings.
• Disable all external connections: turn off AI tools can connect.