Skip to main content
The Wherobots Cloud Model Context Protocol (MCP) Server allows you to use AI assistants like GitHub Copilot to answer questions about the physical world. From your AI assistant, you can explore the schemas of your catalogs, generate and run Spatial SQL from natural language, search the Wherobots documentation, and inspect your workloads, their logs, and Spark execution details. The MCP server is ideal for exploratory data analysis, spatial query generation, and co-authoring production code alongside a human expert. For example prompts and troubleshooting, see MCP Server Best Practices and Usage.

​
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, 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.
    OAuth sign-in requires an existing Wherobots account. You cannot create a new account through the OAuth flow. If you don’t have an account yet, follow the instructions to create one at cloud.wherobots.com first.
  • API key (CI, scripts, and editors that don’t support OAuth): Send your Wherobots API key in an x-api-key header, for example in the mcp.json file of Kiro and other Code OSS editors. Claude Code, OpenCode, Codex, and Cursor also accept an API key.
The Wherobots VS Code Extension signs in with 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 in us-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 16 tools:

​
How queries run

SQL queries from the MCP Server run as background jobs on a SQL session in Wherobots Cloud:
  1. Submit: submit_query_tool starts the query and waits up to about 20 seconds. A query that finishes in that time returns its results directly.
  2. Poll: If the query is still running, submit_query_tool returns a query_id. Your AI assistant calls get_query_status_tool with that ID until the query finishes.
  3. Fetch: Your AI assistant retrieves the rows with get_query_results_tool.
To stop a query you no longer need, ask your AI assistant to cancel it with cancel_query_tool. 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:
  • Read-only SQL: The MCP Server only runs read-only SQL.
  • Response size: Query results are capped by a byte budget per response. For large results, ask for aggregates, fewer columns, or filtered rows.

​
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 with cancel_query_tool. 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:
  1. Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux).
  2. Type and select MCP: List Servers.
  3. Select the name of your server from the list.
  4. Click Stop Server.

​
Configure MCP server settings in the VS Code Extension

The Wherobots VS Code Extension exposes optional settings for the MCP server it configures, including query timeout, runtime size, and cloud region. See Extension Settings for the full reference and which MCP servers they apply to.