> ## 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.
# Set Up Wherobots in Other Code OSS Editors
> Install the Wherobots VS Code Extension in Windsurf, Positron, Antigravity, Trae, or VS Codium and manually configure the MCP Server and Agent Skills for AI-assisted geospatial development.
Public PreviewDraft
The editors on this page are based on Code OSS. The Wherobots VS Code Extension installs in each of them, but the MCP Server and Agent Skills must be configured manually. 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](https://windsurf.com/) | Code OSS-based editor by Cognition AI with AI-powered development features | `windsurf` |
| [Positron](https://positron.posit.co/) | Code OSS-based editor by Posit designed for data science workflows | `positron` |
| [Antigravity](https://antigravity.google/) | Code OSS-based editor by Google | `antigravity` |
| [Trae](https://www.trae.ai/) | Code OSS-based editor by ByteDance with AI-powered development features | `trae` |
| [VS Codium](https://vscodium.com/) | Community-driven, freely-licensed distribution of VS Code | `codium` |
> [!NOTE]
>
> 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](https://docs.wherobots.com/support.md) for assistance.
## Component Overview
Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience:
> **MCP Server**
>
> Connects your AI assistant to Wherobots Cloud for catalog exploration, documentation search, read-only Spatial SQL queries, and workload and Spark execution details.
> **Agent Skills**
>
> Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors.
> **Wherobots CLI**
>
> 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.
> **Explore your spatial catalog conversationally**
>
> 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.
> **Generate Spatial SQL without memorizing functions**
>
> Describe a geospatial task (e.g. "find buildings within 500m of this point") and your AI assistant writes Spatial SQL with WherobotsDB's ST functions, using the table schemas and documentation that the MCP Server provides, then runs it on Wherobots Cloud.
> **Submit and monitor Wherobots jobs from your editor**
>
> 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.
> **Get Wherobots-aware AI assistance**
>
> 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
* One of the editors above installed.
* A **Wherobots Account**. See [Create a Wherobots Account](https://docs.wherobots.com/get-started/wherobots-cloud/create-account.md).
> [!NOTE]
>
> **Organization Availability:** Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise).
* An AI assistant in your editor (for AI-assisted features). In Windsurf, that's an active Windsurf AI subscription; in the other editors, an AI assistant extension.
* [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`).
## Install the extension
Run the command for your editor in your terminal:
```bash Windsurf theme={"system"}
windsurf --install-extension Wherobots.wherobotsjobsubmit
```
```bash Positron theme={"system"}
positron --install-extension Wherobots.wherobotsjobsubmit
```
```bash Antigravity theme={"system"}
antigravity --install-extension Wherobots.wherobotsjobsubmit
```
```bash Trae theme={"system"}
trae --install-extension Wherobots.wherobotsjobsubmit
```
```bash VS Codium theme={"system"}
codium --install-extension Wherobots.wherobotsjobsubmit
```
Or install from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit).
> [!TIP]
>
> If your editor prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload**.
### Configure the extension
After installation, connect to Wherobots Cloud by signing in from your browser (OAuth) or setting an API key.
> [!TIP]
>
> These steps apply to VS Code, Cursor, Windsurf, [Kiro](https://kiro.dev/), 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:`.
> [!TIP]
>
> You can also press ⌘ + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**.
**2. Sign in to Wherobots**
Click `Wherobots: Sign In` to start the OAuth flow. A browser window opens for you to sign in to Wherobots and select your Organization; when you're done, return to your editor.
To sign out at any time, run `Wherobots: Sign Out` from the Command Palette.
> [!NOTE]
>
> **Prefer an API key?** Click `Wherobots: Set API Key` and enter your existing or newly created [Wherobots API key](https://docs.wherobots.com/get-started/wherobots-cloud/api-keys.md) when prompted, then press Enter. If you don't have a key yet, click `Wherobots: Generate API Key on Wherobots Cloud` to create one first.
### 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:`.
> [!TIP]
>
> You can also press ⌘ + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**.
**2. Confirm available commands**
Type **Wherobots** to see the available extension commands.
At this point, you should see commands, including:
* `Wherobots: Sign In`
* `Wherobots: Sign Out`
* `Wherobots: Set API Key`
* `Wherobots: Create Workspace`
* `Wherobots: Submit Job`
* `Wherobots: Refresh Workspaces`
* `Wherobots: Open Settings`
* `Wherobots: Install Jupyter Extension`
## Configure the MCP Server
Where you add the MCP Server depends on the editor:
| Editor | Where to add the MCP Server |
| - | - |
| Positron | The **MCP: Add Server** command, as described in [Positron and VS Codium](#positron-and-vs-codium). See [Posit's Positron example](https://docs.posit.co/rspm/admin/ai/mcp.html). |
| VS Codium | The **MCP: Add Server** command, if your build has it, as described in [Positron and VS Codium](#positron-and-vs-codium). 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 [Windsurf and Antigravity](#windsurf-and-antigravity) and the [Windsurf MCP documentation](https://docs.devin.ai/desktop/cascade/mcp). |
| Antigravity | `mcp_config.json`, which you open from the agent panel: **...** > **MCP Servers** > **Manage MCP Servers** > **View raw config**. See [Windsurf and Antigravity](#windsurf-and-antigravity) and the [Antigravity MCP documentation](https://antigravity.google/docs/mcp). |
| Trae | Trae's MCP settings. See the [Trae MCP documentation](https://docs.trae.ai/ide/model-context-protocol). |
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.
### Positron and VS Codium
The [Wherobots MCP Server](https://docs.wherobots.com/develop/mcp/mcp-server-overview.md) enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries. Configure it manually:
**1. Add the MCP server**
Open the **Command Palette** (⌘ + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux).
1. Type **MCP: Add Server** and select it.
2. Select **HTTP (HTTP or Server-Sent Events)** as the server type.
3. Enter the URL: `https://api.cloud.wherobots.com/mcp/`
4. Enter a name for the server (e.g., `wherobots-mcp-server`).
**2. Add your API key**
Your `mcp.json` file opens automatically. Add a `headers` object with your Wherobots API key:
```json theme={"system"}
"servers": {
"wherobots-mcp-server": {
"url": "https://api.cloud.wherobots.com/mcp/",
"type": "http",
"headers": {
"x-api-key": ""
}
}
}
```
Save the file.
**3. Reload your editor**
Open the **Command Palette** and select **Reload Window**.
> [!NOTE]
>
> The extension's MCP settings, such as query timeout, runtime size, and cloud region, don't apply to an MCP server that you configure by hand in `mcp.json`. See [Extension Settings](https://docs.wherobots.com/develop/vscode-extension/settings.md).
### Windsurf and Antigravity
Windsurf and Antigravity read `mcp_config.json`, which 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:
```json theme={"system"}
{
"mcpServers": {
"wherobots-mcp-server": {
"serverUrl": "https://api.cloud.wherobots.com/mcp/",
"headers": {
"x-api-key": ""
}
}
}
}
```
If the file already lists other servers, add the `wherobots-mcp-server` entry inside the existing `mcpServers` object. Save the file.
## Install Agent Skills
[Agent Skills](https://docs.wherobots.com/develop/agent-skills.md) give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices.
```bash theme={"system"}
npx skills add -g wherobots/agent-skills
```
If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the **Create Workspace** button.
The Wherobots extension sidebar showing the Create Workspace button. Specific UI details vary by editor.
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.
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.
## Verify installation
1. Open your AI assistant's chat panel (Cascade in Windsurf).
2. Select **Agent** as the chat mode (if available).
3. Ask a test question:
```text wrap theme={"system"}
List the catalogs in my Wherobots Data Hub
```
4. If successful, the assistant will call `list_catalogs_tool` and display your available tables.
5. 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**.
## Next steps
> **[Browse Your Data](https://docs.wherobots.com/develop/vscode-extension/integrate-your-data.md)**
>
> Browse catalogs, schemas, and tables in the Data Hub sidebar.
> **[AI-Assisted Notebooks](https://docs.wherobots.com/develop/vscode-extension/notebooks.md)**
>
> Create and connect local notebooks to remote Wherobots compute.
> **[Submit Job Runs](https://docs.wherobots.com/develop/vscode-extension/jobs.md)**
>
> Submit Python scripts as Wherobots job runs from your editor.
> **[MCP Server Best Practices](https://docs.wherobots.com/develop/mcp/mcp-server-usage.md)**
>
> Common tasks, example prompts, and cost considerations for the MCP Server.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.