Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt

Use this file to discover all available pages before exploring further.

Public Preview Cursor by Anysphere is a Code OSS-based editor with built-in AI features. The Wherobots extension installs from the Open VSX Registry, but the MCP Server and Agent Skills must be configured manually. Cursor uses its own mcp.json schema (mcpServers, not servers), so follow the Cursor-specific steps below to install the MCP Server and Agent Skills.

​
Component Overview

Wherobots’ Agentic Tools consist of the following components that work together to provide our agentic experience:
Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution.
Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors.
Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation.

​
Why use Wherobots’ agentic tools?

Wherobots’ agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way.
The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console.
Describe a geospatial task (e.g. “find buildings within 500m of this point”) and the MCP Server returns optimized Spatial SQL using WherobotsDB’s ST functions, spatial joins, and indexing patterns.
Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal.
Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct wherobots CLI commands, valid MCP tool calls, and accurate notebook code on the first try.

​
Before you start

Prior to installing the Wherobots VS Code extension, make sure you have:
  • Cursor installed.
    • Active Cursor subscription in order to select the model used by your Agent within Cursor.
  • A Wherobots Account within a Community, Professional, or Enterprise Organization. See Create a Wherobots Account.
    Organization Availability: Available to all Wherobots Organization Editions.
  • Node.js installed (for running npx skills when installing Agent Skills).

​
Install the extension

Run the following command in your terminal: 
cursor --install-extension Wherobots.wherobotsjobsubmit
Or install from the Open VSX Registry. The Wherobots extension depends on the Jupyter extension from ms-toolsai. If Cursor prompts that it cannot activate the extension because of a missing Jupyter dependency, click Install and Reload.
Cursor dialog prompting to install the Jupyter dependency and reload

​
Configure the extension

After installation, set your API key to connect to Wherobots Cloud.
These steps apply to VS Code, Cursor, Windsurf, Kiro, Positron, Antigravity, Trae, VS Codium, and other Code OSS editors. All use the same Command Palette and extension settings.
1

Open the Command Palette

To open the Command Palette, click the search bar at the top of your editor and type >wherobots:.Command Palette
You can also press ⌘ + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux.
2

Set your API key

  1. If you don’t have an API key yet, click Wherobots: Generate API Key on Wherobots Cloud to create one.
  2. Click Wherobots: Set API Key and enter your existing or newly created Wherobots API key when prompted, then press Enter.
API keys are stored securely in your editor’s Secret Storage.

​
Verify the installation

To confirm the extension is installed and configured correctly:
1

Open the Command Palette

To open the Command Palette, click the search bar at the top of your editor and type >wherobots:.Command Palette
You can also press ⌘ + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux.
2

Confirm available commands

Type Wherobots to see the available extension commands. At this point, you should see commands including:
  • Wherobots: Set API Key
  • Wherobots: Create Workspace
  • Wherobots: Submit Job
  • Wherobots: Refresh Workspaces
  • Wherobots: Open Settings
  • Wherobots: Install Jupyter Extension

​
Apply the extension to all profiles (optional)

If you use multiple Cursor profiles, right-click the Wherobots - Spatial AI Coding Assistant entry in the Extensions view and select Apply Extension to all Profiles so the extension is available in every profile.
Cursor extension context menu with Apply Extension to all Profiles highlighted

​
Configure the MCP Server

The Wherobots MCP Server enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries. Cursor expects a project-level .cursor/mcp.json file with an mcpServers object.
1

Open Tools & MCPs in Cursor Settings

Open the Command Palette (⌘ + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux), type Cursor Settings: Tools & MCPs, and press Enter.Under Installed MCP Servers, click Add Custom MCP. Cursor opens (or creates) .cursor/mcp.json in your project root.
Cursor Settings Tools & MCPs empty state with Add Custom MCP button
2

Add the Wherobots MCP server

Paste the following into .cursor/mcp.json, replacing <YOUR_WHEROBOTS_API_KEY> with your Wherobots API key, then save the file.
{
  "mcpServers": {
    "wherobots-mcp-server": {
      "url": "https://api.cloud.wherobots.com/mcp/",
      "headers": {
        "x-api-key": "<YOUR_WHEROBOTS_API_KEY>"
      }
    }
  }
}
Cursor requires the top-level key mcpServers (plural, camel-case) and does not accept the VS Code–style servers key or the "type": "http" field. If the file has either, Cursor will show “Invalid config: mcpServers must be an object” in Settings.
Cursor editing .cursor/mcp.json
3

Reload and confirm the server is enabled

  1. Open the Command Palette and select Developer: Reload Window.
  2. Return to Cursor Settings > Tools & MCPs and confirm that wherobots-mcp-server is listed, has a green status dot, and lists its tools (for example, list_catalogs_tool, list_tables_tool, describe_table_tool, execute_query_tool, search_documentation_tool) plus prompts and a get_version resource.
wherobots-mcp-server enabled in Cursor Settings Tools & MCPs
The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See Configure MCP server settings.

​
Install Agent Skills

Agent Skills give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices. The Wherobots skill pack is distributed via the skills CLI.
1

Run the skills installer

From a terminal in your project root, run:
npx skills add -g wherobots/agent-skills
The installer clones the Wherobots skills repository and launches an interactive wizard.
2

Select the Wherobots skills

When prompted with Select skills to install, press Space to toggle each skill and Enter to confirm. Select all three:
  • wherobots-develop — guidance for writing Wherobots jobs and using the SDK/CLI.
  • wherobots-explore — catalog discovery and spatial query generation via the MCP server.
  • wherobots-usage — interface decision matrix, auth setup, and scheduled-job patterns.
skills CLI select skills prompt
3

Select Cursor as a target agent

On the Which agents do you want to install to? screen, make sure Cursor is selected under Universal (it is included by default). You can optionally add other agents from the Additional agents list (for example, Claude Code at ~/.claude/skills).Press Enter to continue.
skills CLI agent selection prompt showing Cursor in the Universal list
4

Review and confirm installation

The installer prints an installation summary and security risk assessments (Gen, Socket, Snyk). When prompted Proceed with installation?, type Yes and press Enter.

​
Verify your setup

  1. Open a New Agent chat in Cursor (the chat panel on the right).
  2. Confirm Agent is selected as the chat mode.
  3. Ask a test question, for example:
    List the available tables in wherobots_pro_data
  4. If everything is configured, Cursor’s agent calls search_documentation_tool, list_catalogs_tool, list_databases_tool, and list_tables_tool on wherobots-mcp-server and returns the catalogs, databases, and tables in your Organization.
    Cursor agent listing tables in wherobots_pro_data using MCP tools
  5. Re-open Cursor Settings → Tools & MCPs and confirm wherobots-mcp-server shows a green dot with all tools enabled.

​
Pin the extension for easy access

If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the Create Workspace button.
Create Workspace button in the Wherobots sidebar
To pin the Wherobots extension to the sidebar:
1

Pin the extension

Right-click the Activity Bar (the vertical icon bar on the left side of your editor).A menu will appear showing all available extensions.
2

Select the extension

To pin the extension, find Wherobots in the list and click on it to ensure it’s checked.
Wherobots extension checked in the Activity Bar
Now you’ll have easy access to the extension in your editor’s sidebar.

​
Troubleshooting

​
Invalid config: mcpServers must be an object or JSON syntax error

Cursor validates .cursor/mcp.json against its own schema and will display these errors in Cursor Settings → Tools & MCPs when the file is malformed. Common causes:
  • Missing the outer { ... } wrapper around the config — the JSON parser fails with “End of file expected.”
  • Using the VS Code key "servers" instead of Cursor’s "mcpServers".
  • Including a "type": "http" field — Cursor does not use it.
Re-paste the snippet from Configure the MCP Server exactly as shown, save the file, and reload the window.

​
Next steps

Browse Your Data

Browse catalogs, schemas, and tables in the Data Hub sidebar.

AI-Assisted Notebooks

Create and connect local notebooks to remote Wherobots compute.

Submit Job Runs

Submit Python scripts as Wherobots job runs from your editor.

MCP Server Best Practices

Common tasks, example prompts, and cost considerations for the MCP Server.