Watch a 10-minute demo
This video demonstrates catalog exploration, data introspection, and natural language Q&A with the MCP server in Wherobots Cloud. It also shows how to use the MCP server to generate and validate a Jupyter notebook for a large-scale spatial join.
To run a generated notebook yourself, start a runtime in Wherobots Cloud and click Upload Files in JupyterLab.
Authentication methods
The Wherobots MCP Server supports two authentication methods:- OAuth (Claude Code, OpenCode, Codex, Cursor, Kiro, Claude, and ChatGPT): When you connect for the first time, your MCP client opens a browser window where you sign in to Wherobots and select your organization. OAuth is the default on these tools’ setup pages.
- API key (CI, scripts, and editors that don’t support OAuth): Send your Wherobots API key in an
x-api-keyheader, for example in themcp.jsonfile of other Code OSS editors. Claude Code, OpenCode, Codex, Cursor, and Kiro also accept an API key.
Wherobots: Sign In (OAuth) or Wherobots: Set API Key, and configures the MCP Server for you in VS Code.
Before you start
Before using this feature, ensure that you have the following required resources:-
A Wherobots Account, including one in a trial Organization. For more information, see Create a Wherobots Account.
- Both Admin and User roles have access to MCP Server in Wherobots Cloud.
The Wherobots MCP server is hosted inus-west-2. When used, MCP clients communicate with this service.If you need the MCP server to be hosted in alternative regions, please file a request at support@wherobots.com.Using the MCP Server with the most advanced versions of AI models like Claude Sonnet, Claude Opus, or GPT Codex is recommended for optimal performance.
Set up the MCP server
For step-by-step setup instructions for your editor, terminal, or chat app, see Get Started with Agentic Development. It covers VS Code, Cursor, Kiro, Claude Code, OpenCode, Codex, Claude, ChatGPT, and other Code OSS editors.Available tools
The Wherobots MCP Server exposes these tools:How queries run
SQL queries from the MCP Server run as background jobs on a SQL session in Wherobots Cloud:- Submit:
submit_read_querystarts the query and waits up to about 20 seconds. A query that finishes in that time returns its results directly. - Poll: If the query is still running,
submit_read_queryreturns aquery_id. Your AI assistant callsget_query_resultswith that ID until the query finishes. - Fetch: Once the query succeeds,
get_query_resultsreturns the rows.
cancel_query.
If no SQL session is running, the query starts one. A cold SQL session can take several minutes to start, so the first query can stay in the polling step for several minutes. Later queries use the running session until it shuts down after a period of inactivity.
Limits
The following limits apply to every MCP client:-
SQL that writes:
submit_read_queryruns only read-only SQL. Two more tools run SQL that writes, limited to what your Wherobots account can write:submit_write_queryruns statements that only add:CREATE TABLE,CREATE TABLE AS SELECT,CREATE VIEW,CREATE SCHEMA, andINSERT INTO. ACREATEthat setsLOCATIONorOPTIONSgoes throughsubmit_destructive_query.submit_destructive_queryruns every other statement, including the ones that can delete, overwrite, or replace:DROP,TRUNCATE,DELETE,UPDATE,MERGE,ALTER,INSERT OVERWRITE, andCREATE OR REPLACE.
submit_read_queryas read-only,submit_write_queryas not read-only, andsubmit_destructive_queryas destructive. - Response size: Query results are capped by a byte budget per response. For large results, ask for aggregates, fewer columns, or filtered rows.
- Query time limit: A query stops after 30 minutes, including the time a SQL session takes to start. A client that sends its own query timeout, such as the VS Code Extension with Mcp Server Query Timeout set, uses that timeout in place of the 30-minute default. Your AI assistant can also set a limit for a single query, up to a maximum that Wherobots sets and the query tools list. A limit your AI assistant sets takes precedence over the client’s timeout.
Cost
- You are only billed for MCP server usage when you execute a query on Wherobots from the MCP server. The charges come from the SQL Session runtime that the query starts.
- A SQL Session starts on your Organization’s default runtime, or on the runtime your client sets.
- SQL Sessions terminate after 5 minutes of inactivity.
- Query execution contributes to Spatial Unit (SU) consumption and appears in Usage History as SQL Session usage.
- If your AI assistant is GitHub Copilot, its requests count toward your Copilot usage limits. For more information, see Requests in GitHub Copilot in the GitHub Documentation.
Stop the MCP Server
MCP server charges come from the SQL Session runtime that a query starts, and the SQL Session shuts down after a period of inactivity. You don’t need to stop the MCP server to end those charges. To stop a query you no longer need, ask your AI assistant to cancel it withcancel_query.
You can still stop the MCP server when you are finished, for example to disconnect your editor from Wherobots. To stop the MCP server in VS Code:
- Open the Command Palette (
Cmd+Shift+Pon Mac,Ctrl+Shift+Pon Windows/Linux). - Type and select MCP: List Servers.
- Select the name of your server from the list.
- Click Stop Server.

