Skip to main content
The Wherobots Model Context Protocol (MCP) server helps you explore spatial data and generate geospatial SQL through natural language. For installation instructions, configure the MCP Server.
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.

​
Use cases for the MCP server

The MCP server is optimized for tasks such as:
Understand what datasets are available across your organization’s catalogs, databases, and tables.
Generate geospatial analysis workflows as ready-to-run notebooks.
Perform initial dataset analysis and assess data quality.
Get help writing and optimizing spatial SQL operations.
Receive guidance on geospatial concepts, functions, and best practices.

​
Common tasks

The MCP server excels at helping you understand and work with your spatial data through:
  • Schema Discovery: Prompt to understand table structures and relationships.
  • Query Optimization: Get suggestions for improving spatial query performance.
  • Best Practices: Receive guidance on spatial data analysis techniques based on your datasets and the Wherobots documentation.
For guidance on writing spatial SQL queries, including common pitfalls and complete examples, see Writing Effective Spatial Queries in Wherobots.
For a video walkthrough of the MCP server in action, see Video: Automating Geospatial Discovery and Query Generation.

​
Example prompts

​
Exploring Overture dataset schema

For example, you can ask about the details in a specific dataset, such as: Screenshot showing the MCP server dataset details response in Copilot Chat

​
Start a SQL session before longer work

Queries from the MCP server run on a SQL session in Wherobots Cloud. If no session is running, the first query starts one, and a cold SQL session can take several minutes to start. Later queries use the running session until it shuts down after a period of inactivity. To have the session running before longer work, start with a small query, for example:
“How many rows are in the Overture buildings table?”
While the session starts, the query runs as a background job:
  1. submit_query_tool waits up to about 20 seconds, then returns a query_id if the query is still running.
  2. Your AI assistant polls get_query_status_tool until the query finishes.
  3. Your AI assistant fetches the rows with get_query_results_tool.
For details, see How queries run.

​
Usage considerations

Consider the following best practices and limitations when using the Wherobots MCP server integration:
  • Models dictate query success: Performance improves significantly with the latest advanced AI models available in Copilot (for example, the latest version of Claude Opus, Gemini Pro, or GPT Codex models)
  • Read-only queries: The MCP server only runs read-only SQL, and query results are capped by a byte budget per response. See Limits.
  • Compute constraints: Queries run on your Organization’s default runtime unless your client sets a different one, and stop when they reach the query time limit.
    • VS Code Extension settings: If the Wherobots VS Code Extension configures your MCP server, you can change these values from Wherobots: Open Settings in the Command Palette. Edit wherobotsjobsubmit.mcpServerQueryTimeout to change the query timeout, wherobotsjobsubmit.mcpServerRuntimeId to use a larger runtime if queries stall, and wherobotsjobsubmit.mcpServerRuntimeRegion to change the region.
    • Clients configured by hand: The extension’s MCP settings don’t apply to MCP clients that you configure by hand, such as Claude Code, Codex, or Cursor.
  • Complex operations: Large-scale operations like planetary-scale analysis or isochrones may timeout.

​
Cost considerations

  • Professional, Innovation, and Enterprise Organizations
    • 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.
    • When executing queries on Wherobots from the MCP server, 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 will be categorized as SQL Session consumption.
  • Usage tracking: Query execution activity appears in Workload History as SQL Session usage.
  • Copilot requests: Usage counts toward your GitHub 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.