Set Up Wherobots in Your Editor

Public Preview The Wherobots VS Code Extension runs in VS Code and other Code OSS editors. In VS Code, it configures the MCP Server and includes Agent Skills for you. In other editors, you install the extension the same way, then add the MCP Server and Agent Skills yourself once. For what each Wherobots component does, see What each component does. To use Wherobots from a terminal agent or a chat app instead, see Set Up Wherobots in an AI Assistant.

Before you start

You need:

A Wherobots Account. See Create a Wherobots Account.
Organization Availability: Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise).
One of the editors below, with an AI assistant for the AI-assisted features:

Editor	Requirements
VS Code	Visual Studio Code 1.93 or later, and an active GitHub Copilot subscription.
Cursor	Cursor, and Node.js with npm to install Agent Skills with `npx`.
Kiro	Kiro. For plans, see Kiro Pricing.
Other Code OSS editors	Windsurf, Positron, Antigravity, Trae, or VS Codium; an AI assistant (in Windsurf, an active Windsurf AI subscription; in the others, an AI assistant extension); and Node.js with npm to install Agent Skills with `npx`.

Set up your editor

Choose your editor. Each tab covers installing the extension, signing in, connecting the MCP Server and Agent Skills, and opening your editor’s agent chat.

VS Code
Cursor
Kiro
Other Code OSS editors

Install the extension

Run the following command in your terminal:

code --install-extension wherobots.wherobotsjobsubmit

Or install from the Visual Studio Marketplace.If VS Code prompts you to install a missing dependency extension (e.g., Jupyter), click Install and Reload.

Open the Command Palette (⌘ + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux) and run Wherobots: Sign In. A browser window opens for you to sign in to Wherobots and select your Organization; when you’re done, return to your editor.

Prefer an API key? Run Wherobots: Set API Key and enter your existing or newly created Wherobots API key when prompted, then press Enter. If you don’t have a key yet, run Wherobots: Generate API Key on Wherobots Cloud to create one first.

To confirm the extension is installed, type Wherobots in the Command Palette. You should see its commands, including Wherobots: Create Workspace, Wherobots: Submit Job, and Wherobots: Open Settings. To sign out at any time, run Wherobots: Sign Out.

MCP Server and Agent Skills

The extension configures the Wherobots MCP Server and includes Agent Skills in VS Code. No manual setup is needed.The extension also exposes optional settings for the MCP server, including query timeout, runtime size, and cloud region. See Extension Settings.

Open the agent chat

Open GitHub Copilot Chat via View > Chat.
Select Agent as the chat mode from the dropdown at the top of the chat panel.
Select an advanced model (Claude Opus, Claude Sonnet, GPT Codex, or Gemini Pro) for best results.

Then verify your setup.

Cursor installs the extension from the Open VSX Registry, and you add the MCP Server and Agent Skills yourself. Cursor uses its own mcp.json schema (mcpServers, not servers).

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 — Cursor prompts to install the Jupyter dependency and reload the window after installing the Wherobots extension.

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 — Right-click the Wherobots extension in the Extensions view and select Apply Extension to all Profiles.

Add the MCP Server

Cursor expects a project-level .cursor/mcp.json file with an mcpServers object.

Open the Command Palette, 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 with the Add Custom MCP button before any server is configured.
Paste the following into .cursor/mcp.json, then save the file:
{ "mcpServers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/" } } }
When you first use the MCP server, Cursor starts an OAuth flow: a browser window opens for you to sign in to Wherobots and select your organization.
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 shows “Invalid config: mcpServers must be an object” in Settings.

Editing .cursor/mcp.json in Cursor. The file must be wrapped in an outer object and use mcpServers.
Open the Command Palette and select Developer: Reload Window.
Return to Cursor Settings > Tools & MCPs and confirm that wherobots-mcp-server is listed, has a green status dot, and lists its 16 tools (for example, list_catalogs_tool, list_tables_tool, describe_table_tool, submit_query_tool, get_query_status_tool, get_query_results_tool, search_documentation_tool) plus prompts and a get_version resource. For the full list, see Available tools.
wherobots-mcp-server listed in Cursor Settings with its tools, prompts, and resource enabled.

Alternative: Use an API key instead of OAuth

Add a headers object with your Wherobots API key:

{
  "mcpServers": {
    "wherobots-mcp-server": {
      "url": "https://api.cloud.wherobots.com/mcp/",
      "headers": {
        "x-api-key": "<YOUR_WHEROBOTS_API_KEY>"
      }
    }
  }
}

Install Agent Skills

The Wherobots skill pack is distributed through the skills CLI.

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.
When prompted with Select skills to install, press Space to toggle each skill and Enter to confirm. Select all three: wherobots-develop, wherobots-explore, and wherobots-usage.
The skills installer prompts you to select which Wherobots skills to install.
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.
Choose which agents receive the skills. Cursor is included in the Universal list.
The installer prints an installation summary and security risk assessments (Gen, Socket, Snyk). When prompted Proceed with installation?, type Yes and press Enter.

Open the agent chat

Open a New Agent chat in Cursor (the chat panel on the right) and confirm Agent is selected as the chat mode. Then verify your setup.

Kiro installs the extension from the Open VSX Registry. You then enable MCP in Kiro’s settings, add the MCP Server to an mcp.json file that uses Kiro’s mcpServers schema, and import Agent Skills.

Install the extension

Run the following command in your terminal:

kiro --install-extension Wherobots.wherobotsjobsubmit

Or install from the Open VSX Registry.If Kiro prompts you to install a missing dependency extension (e.g., Jupyter), click Install and Reload.

In Kiro, you can also open the Command Palette by clicking the search bar at the top of the editor and typing >wherobots.

Enable MCP support

Kiro connects to MCP servers only after MCP is enabled.

Press ⌘ + , on macOS or Ctrl + , on Windows/Linux to open Settings, and make sure the following are enabled:
- wherobotsjobsubmit.mcpServerEnabled
- kiroAgent.configureMCP
Kiro Settings showing wherobotsjobsubmit.mcpServerEnabled and kiroAgent.configureMCP both turned on.
In Kiro’s Command Palette, search for kiro: open MCP Config.

Add the MCP Server

Kiro stores MCP configuration in mcp.json using a mcpServers object, at one of two levels:

Config level	File path & When to use
User Config	`~/.kiro/settings/mcp.json` — Applies to every Kiro workspace; use when you want the Wherobots MCP server available globally.
Workspace Config	`.kiro/settings/mcp.json` (project root) — Applies only to the current workspace; use when projects need different API keys or server configurations.

These steps use the User Config. To use the Workspace Config instead, create .kiro/settings/mcp.json in your project root with the same content.

In the same MCP Settings view, click Open User MCP Config (JSON), or run Kiro: Open User MCP Config (JSON) from the Command Palette. Kiro opens ~/.kiro/settings/mcp.json.
Choose between the User Config and Workspace Config tabs in the Kiro MCP config editor.
Paste the following into mcp.json, replacing YOUR_WHEROBOTS_API_KEY with your Wherobots API key. If the file already contains other servers, add the new entry alongside them.
{ "mcpServers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/", "headers": { "x-api-key": "YOUR_WHEROBOTS_API_KEY" } } } }
Kiro requires the top-level key mcpServers and does not accept the VS Code-style servers key or the "type": "http" field. Using either produces an “Error loading powers config: Unexpected token” message in the Output panel.
Save the file. Kiro detects the change and may add disabled, autoApprove, and disabledTools fields to the entry.
Open the Output panel (⌘ + Shift + U) and look for the following message in the Kiro - MCP Logs output stream:
[info] [wherobots-mcp-server] Successfully connected and synced tools and resources for MCP server
If you see this message, the server is connected and ready to use.

Import Agent Skills

Kiro imports skills directly from GitHub through the Agent Steering & Skills panel in the sidebar. Install all three Wherobots skills: wherobots-develop, wherobots-explore, and wherobots-usage.

Click the Kiro icon in the Activity Bar, open the AGENT STEERING & SKILLS section, and click + to add a new skill.
Type Agent Skills in the search bar that appears, and select either Global agent skills or Project-specific agent skills from the dropdown.
Click Import skill from GitHub. A dialog opens where you can paste the URL of the skill’s GitHub repository.

For each URL below, copy the URL, paste it into Kiro’s import dialog, and press Enter:

https://github.com/wherobots/agent-skills/tree/main/.agents/skills/wherobots-develop

https://github.com/wherobots/agent-skills/tree/main/.agents/skills/wherobots-explore

https://github.com/wherobots/agent-skills/tree/main/.agents/skills/wherobots-usage

After each import, Kiro downloads the SKILL.md file and adds the skill to the AGENT STEERING & SKILLS section.

Confirm that all three skills appear under AGENT STEERING & SKILLS in the sidebar.
The Kiro sidebar showing wherobots-develop, wherobots-explore, and wherobots-usage installed under Agent Steering & Skills.

Open the agent chat

Check the MCP SERVERS section in Kiro’s sidebar. You should see wherobots with Connected (16 tools) and a list of tools including list_catalogs_tool, list_tables_tool, and search_documentation_tool. For the full list, see Available tools.
The MCP SERVERS section in Kiro's sidebar showing the wherobots MCP server connected.
Open a New Session chat panel. When the agent calls a Wherobots tool, you may be prompted to Trust or Run the tool call.
Kiro's agent calling list_catalogs_tool to list available Wherobots catalogs.

Then verify your setup.

The extension installs from the Open VSX Registry in each of these editors, and you add the MCP Server and Agent Skills yourself. Installing the extension and Agent Skills works the same way in every editor; where you add the MCP Server differs by editor.

Editor	Description	CLI command
Windsurf	Code OSS-based editor by Cognition AI with AI-powered development features	`windsurf`
Positron	Code OSS-based editor by Posit designed for data science workflows	`positron`
Antigravity	Code OSS-based editor by Google	`antigravity`
Trae	Code OSS-based editor by ByteDance with AI-powered development features	`trae`
VS Codium	Community-driven, freely-licensed distribution of VS Code	`codium`

Using a Code OSS editor not listed here? Follow these steps and substitute your editor’s CLI command.

These instructions are a preliminary adaptation of the standard VS Code Extension within the Windsurf, Positron, Antigravity, Trae, or VS Codium environment. Users may encounter steps that require manual adjustment. Should you experience any technical difficulties, please contact Wherobots Support for assistance.

Install the extension

Run the command for your editor in your terminal:

windsurf --install-extension Wherobots.wherobotsjobsubmit

positron --install-extension Wherobots.wherobotsjobsubmit

antigravity --install-extension Wherobots.wherobotsjobsubmit

trae --install-extension Wherobots.wherobotsjobsubmit

codium --install-extension Wherobots.wherobotsjobsubmit

Or install from the Open VSX Registry.If your editor prompts you to install a missing dependency extension (e.g., Jupyter), click Install and Reload.

Add the MCP Server

Each editor needs the same two values: the server URL, https://api.cloud.wherobots.com/mcp/, and an x-api-key header with your Wherobots API key. Where you add them depends on the editor:

Editor	Where to add the MCP Server
Positron	The MCP: Add Server command, as described below. See Posit’s Positron example.
VS Codium	The MCP: Add Server command, if your build has it, as described below. Otherwise, the MCP settings of your AI assistant extension.
Windsurf	`mcp_config.json`, which you open from the Cascade panel: the … menu, then Open MCP config file in the MCPs section. See the Windsurf MCP documentation.
Antigravity	`mcp_config.json`, which you open from the agent panel: … > MCP Servers > Manage MCP Servers > View raw config. See the Antigravity MCP documentation.
Trae	Trae’s MCP settings. See the Trae MCP documentation.

Positron and VS Codium:

Open the Command Palette, type MCP: Add Server, and select it.
Select HTTP (HTTP or Server-Sent Events) as the server type.
Enter the URL https://api.cloud.wherobots.com/mcp/ and a name for the server (e.g., wherobots-mcp-server).

Your mcp.json file opens. Add a headers object with your Wherobots API key, then save the file:

"servers": {
  "wherobots-mcp-server": {
    "url": "https://api.cloud.wherobots.com/mcp/",
    "type": "http",
    "headers": {
      "x-api-key": "<YOUR_WHEROBOTS_API_KEY>"
    }
  }
}

Open the Command Palette and select Reload Window.

Windsurf and Antigravity: mcp_config.json uses an mcpServers object and a serverUrl field instead of the servers object and url field of VS Code’s mcp.json. Add the Wherobots server inside the existing mcpServers object if the file already lists other servers, then save the file:

{
  "mcpServers": {
    "wherobots-mcp-server": {
      "serverUrl": "https://api.cloud.wherobots.com/mcp/",
      "headers": {
        "x-api-key": "<YOUR_WHEROBOTS_API_KEY>"
      }
    }
  }
}

Install Agent Skills

Run the following command in your terminal:

npx skills add -g wherobots/agent-skills

Open the agent chat

Confirm the server appears in the editor’s list of MCP servers. In Positron and VS Codium, open the Command Palette and run MCP: List Servers. In Windsurf, check the MCPs section of the Cascade panel’s … menu. In Antigravity, open Manage MCP Servers.
Open your AI assistant’s chat panel (Cascade in Windsurf) and select Agent as the chat mode, if available.

Then verify your setup.

Verify your setup

In your editor’s agent chat, ask a test question:

List the catalogs in my Wherobots Organization

If everything is configured, the assistant calls a Wherobots MCP tool such as list_catalogs_tool and returns the catalogs available in your Organization, including wherobots_open_data, wherobots_pro_data, and any private catalogs.

Screenshot showing the MCP server catalogs response

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 — The Wherobots extension sidebar showing the Create Workspace button. Specific UI details vary by editor.

To pin the Wherobots extension to the sidebar:

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.

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 — The Activity Bar context menu with the Wherobots extension checked. Specific UI details vary by editor.

Now you’ll have easy access to the extension in your editor’s sidebar.

Troubleshooting

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

Cursor validates .cursor/mcp.json against its own schema and displays 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, which Cursor does not use.

Re-paste the snippet from the Cursor steps exactly as shown, save the file, and reload the window.

Kiro: MCP: Browse MCP Servers results in an error

Kiro does not implement the VS Code workbench.mcp.browseServers command. Running MCP: Browse MCP Servers from the Command Palette displays “command ‘workbench.mcp.browseServers’ not found”. This does not mean the MCP server is broken.

Kiro error dialog showing the workbench.mcp.browseServers command not found — Kiro error dialog: 'command workbench.mcp.browseServers not found' after running MCP: Browse MCP Servers.

To verify the server is working, check the MCP SERVERS section in Kiro’s sidebar for a green Connected status, check Output → Kiro - MCP Logs for the “Successfully connected” message, or ask the test question in chat.

Kiro: Error loading powers config: Unexpected token

This error appears in the Output panel and as a notification when mcp.json contains invalid JSON or uses the wrong schema. Common causes:

Using the VS Code key "servers" instead of Kiro’s "mcpServers".
Including a "type": "http" field, which Kiro does not use.
Missing the outer { ... } wrapper, or a trailing comma.

Re-paste the snippet from the Kiro steps exactly as shown, save the file, and check the Output panel for a successful connection.

Kiro: MCP is currently disabled

If you see a banner saying “MCP is currently disabled. To start using MCP, please enable it in the settings.”, follow the Enable MCP support step in the Kiro tab to turn on MCP in Kiro’s settings.

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.

Workspaces & Usage

Create, start, stop, and manage notebook workspaces.

MCP Server Best Practices

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

Install the CLI

Submit jobs and access the full Wherobots API from your terminal.

Start here

Notebooks

Editors and AI assistants

VS Code extension

MCP server and agent skills

dbt

Apache Airflow

Storage management

Deployment and monitoring

Set Up Wherobots in Your Editor

Before you start

Set up your editor

Verify your setup

Pin the extension for easy access

Troubleshooting

Next steps

Browse Your Data

AI-Assisted Notebooks

Submit Job Runs

Workspaces & Usage

MCP Server Best Practices

Install the CLI

​Before you start

​Set up your editor

​Verify your setup

​Pin the extension for easy access

​Troubleshooting

​Next steps

Browse Your Data

AI-Assisted Notebooks

Submit Job Runs

Workspaces & Usage

MCP Server Best Practices

Install the CLI

Before you start

Set up your editor

Verify your setup

Pin the extension for easy access

Troubleshooting

Next steps