> ## 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.
# Configure Wherobots MCP Server
> Learn how to set up the Wherobots MCP server for geospatial data exploration and query generation.
The Wherobots Cloud **Model Context Protocol (MCP) Server** allows you to use AI assistants like
GitHub Copilot to answer questions about the physical world. This feature enables intelligent
catalog exploration, code generation and query execution directly in your development environment.
The MCP server is ideal for exploratory data analysis, spatial query generation, and co-authoring production code alongside a human expert.
For more information on using the MCP Server including common tasks and example prompts
see [MCP Server Best Practices and Usage](/develop/mcp/mcp-server-usage).
## Quickstart
Already familiar with adding MCP servers? Take a look at the Quickstart.
1. Run one of the following commands to install the extension, or install from the marketplace for your editor:
```bash VS Code theme={"system"}
code --install-extension wherobots.wherobotsjobsubmit
```
```bash Kiro theme={"system"}
kiro --install-extension Wherobots.wherobotsjobsubmit
```
```bash Cursor theme={"system"}
cursor --install-extension Wherobots.wherobotsjobsubmit
```
```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
```
If your editor prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload** to install it and reload the window. The Wherobots extension depends on other extensions that may not be pre-installed in all editors.
```markdown Visual Studio Marketplace theme={"system"}
https://marketplace.visualstudio.com/items?itemName=wherobots.wherobotsjobsubmit
```
```markdown Open VSX (Code OSS-based editors) theme={"system"}
https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit
```
2. Open your editor's **Command Palette** (`Cmd+Shift+P` on Mac, `Ctrl+Shift+P` on Windows/Linux).
3. Enter `Wherobots: Set API Key`.
4. Enter your [Wherobots API key](/get-started/wherobots-cloud/api-keys#create-an-api-key).
5. In VS Code, the extension automatically configures the MCP server. In Cursor and other Code OSS editors, use the **Manual Configuration** tab instead.
1. Create an [API key](/get-started/wherobots-cloud/api-keys#create-an-api-key) from Wherobots Cloud Console.
2. Open the **Command Palette** in VS Code (`Cmd+Shift+P` on Mac, `Ctrl+Shift+P` on Windows/Linux).
3. Type `mcp`.
4. Select **MCP: Add Server...**
5. Select **HTTP**.
6. Enter `https://api.cloud.wherobots.com/mcp/`
7. Click **Enter**
8. Enter your Wherobots API key in the `mcp.json`
9. Select **Global** or **Workspace**
You can verify that the MCP server is running by opening the Command Palette and selecting **MCP: List Servers**.
## Benefits
The **MCP Server** integration in Wherobots Cloud allows for:
* **Intelligent Catalog Exploration**: Discover and understand the schemas of your available datasets through natural language queries
* **Geospatial Query Generation**: Generate Spatial SQL queries using natural language
* **Conversational Exploration**: Query your spatial catalog with natural language to speed up preliminary data analysis.
### Watch a 10-minute demo
## Before you start
Before using this feature, ensure that you have the following required resources:
* An **Account** within a Professional or Enterprise Organization. For more information, see [Create a Wherobots Account](/get-started/wherobots-cloud/create-account).
* Both **Admin** and **User** roles have access to **MCP Server** in Wherobots Cloud.
* A Wherobots API key. For more information, see [API Keys](/get-started/wherobots-cloud/api-keys/).
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](mailto: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.
## Enable Wherobots MCP server in your editor
The [**Wherobots VS Code Extension**](https://marketplace.visualstudio.com/items?itemName=wherobots.wherobotsjobsubmit) Visual Studio Code (VS Code) extension automatically configures the Wherobots MCP server for you.
Installing the extension gives you the MCP server along with access to running local notebooks against Wherobots Runtime Compute and job submission.
The extension works with both VS Code and any Code OSS-based editor, including [Kiro](https://kiro.dev/), Cursor, Windsurf, Positron, Antigravity, Trae, VS Codium.
### Install the extension
Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=wherobots.wherobotsjobsubmit) or the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit) (for Kiro, Cursor, and other editors), or run one of the following commands:
```bash VS Code theme={"system"}
code --install-extension wherobots.wherobotsjobsubmit
```
```bash Kiro theme={"system"}
kiro --install-extension Wherobots.wherobotsjobsubmit
```
```bash Cursor theme={"system"}
cursor --install-extension Wherobots.wherobotsjobsubmit
```
```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
```
If your editor prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload** to install it and reload the window. The Wherobots extension depends on other extensions that may not be pre-installed in all editors.
```markdown Visual Studio Marketplace theme={"system"}
https://marketplace.visualstudio.com/items?itemName=wherobots.wherobotsjobsubmit
```
```markdown Open VSX (Code OSS-based editors) theme={"system"}
https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit
```
### Configure the extension
After installation, set your API key to connect to Wherobots Cloud.
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.
To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`.
You can also press ⌘ + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux.
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](/get-started/wherobots-cloud/api-keys/) 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:
To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`.
You can also press ⌘ + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux.
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`
The extension automatically configures the MCP server in VS Code with no additional manual configuration required. For Cursor and other Code OSS-based editors, use the [Manual Configuration](#enable-wherobots-mcp-server-in-your-editor) tab to set up the MCP server.
For more details on the extension's full capabilities, see [Install the Wherobots VS Code Extension](/develop/agentic-tools).
### Configure extension settings
The Wherobots VS Code extension exposes several optional settings that control MCP server and job submission behavior. To view them, open your editor's **Settings** (Cmd+, on Mac, Ctrl+, on Windows/Linux) and search for `@ext:Wherobots.wherobotsjobsubmit`.
Override the Wherobots API base URL. Affects both job submission and the MCP server. Leave empty to use the default production server.
Instance size for Wherobots job runs, selected from the available options. If not set, uses the organization's default instance type.
Enable or disable Jupyter integration. When enabled, running Wherobots workspaces appear as kernel options in the VS Code Jupyter kernel picker.
Enable or disable the Wherobots MCP server. When enabled, AI assistants like GitHub Copilot can use Wherobots tools.
Timeout in seconds for Wherobots MCP server queries. Leave unset to use the server default of 900 seconds (15 minutes).
Runtime size for Wherobots MCP server queries (e.g., `TINY`, `SMALL`, `MEDIUM`, `LARGE`). Controls the compute resources allocated. Leave empty to use the server default.
Cloud region for Wherobots MCP server queries (e.g., `AWS_US_WEST_2`, `AWS_US_EAST_1`). Leave empty to use the server default.
Cloud region for Wherobots job submission. If not set, uses the organization's region. Note: Some regions are Enterprise-only.
Cloud path (e.g., `s3://bucket/path/`) where Wherobots will store scripts when submitting jobs. If not set, uses the organization's default path.
Timeout in seconds for Wherobots Jobs. Default is 1 hour (3600 seconds).
Consider increasing **Mcp Server Runtime ID** when running queries against large datasets, and adjust **Mcp Server Query Timeout** if long-running spatial queries are timing out before completion.
### Use the MCP server
1. Open your editor's AI assistant (e.g. GitHub Copilot Chat in VS Code via **View > Chat**).
2. If you haven't already, start a new chat session.
3. Make sure you have **Agent** selected as the chat mode. You can select this from the dropdown menu at the top of the chat panel.
4. You can also select the **model** you wish to use alongside the MCP server from the adjacent dropdown. Quality of responses may vary between models.
Wherobots recommends using the latest versions of advanced models like Claude Opus, Claude Sonnet, Gemini Pro, or GPT Codex for optimal performance with the MCP server.
5. Ask a question to see if it interacts with the Wherobots service, for example:
> Show me the catalogs in my Organization
6. If successful, your AI assistant will confirm it is using the Wherobots MCP server (showing `Ran list_catalogs` or a similar tool) and display all of the available catalogs in your Organization.
The exact response will vary depending on the datasets within your Organization as well as the model used to query the MCP server.
At minimum, `wherobots_open_data` appears for Community Edition, and both `wherobots_open_data` and `wherobots_pro_data` for Professional and Enterprise Edition Organizations.
### Stop the MCP server
When you are finished asking Wherobots-related questions, it is important to stop the MCP server.
Stopping the server ensures that no additional charges are incurred from the MCP server and that resources are freed for other tasks.
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**.
This section covers how to manually add the Wherobots MCP Server to VS Code or any Code OSS-based editor.
1. Ensure your editor's AI assistant is signed in (e.g. GitHub Copilot in VS Code).
2. Open your editor's **Settings** (e.g., press `Cmd+,` on Mac).
3. In the search bar, type **mcp**.
4. Configure the following settings:
* **Chat Mcp Discovery:** **Enabled**
* **Chat > Mcp > Access:** **all**
* **Chat > Mcp > Autostart:** **newAndOutdated**
For more information on downloading, installing and using GitHub Copilot, see [GitHub Copilot for VS Code](https://code.visualstudio.com/docs/copilot/getting-started)
and [Get started with chat in VS Code](https://code.visualstudio.com/docs/copilot/chat/copilot-chat) in the VS Code Documentation.
### Add the MCP server
1. Open the VS Code **Command Palette** (e.g., press `Cmd+Shift+P` on Mac).
2. Type **MCP: Add Server** and select it from the list.
3. You will be prompted to "Choose the type of MCP server to add". Select **HTTP (HTTP or Server-Sent Events)**.
4. When prompted for the URL, enter the service URL: `https://api.cloud.wherobots.com/mcp/`.
5. When prompted, provide a **name for your MCP server** (e.g., "wherobots-mcp-server").
6. Your `mcp.json` file will open automatically after adding the server.
If not, you can open it manually by typing and selecting **>mcp: Open User Configuration** in the Command Palette.
7. Add a **`"headers"`** object containing your **`"x-api-key"`**, using your Wherobots API key as the value.
Copy and paste the following into your `mcp.json`, replacing the placeholders with your chosen MCP server name and Wherobots API key.
```json theme={"system"}
"servers": {
"": {
"url": "https://api.cloud.wherobots.com/mcp/",
"type": "http",
"headers": {
"x-api-key": ""
}
}
}
```
8. **Save** the `mcp.json` file.
9. **Reload VS Code** to apply your changes:
1. Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux).
2. Type and select **Reload Window**.
### Start the MCP server
1. Open the Command Palette again and type **MCP: List Servers**.
1. Select your server from the list, then click **Start Server**.
2. Check the VS Code **Output** panel to confirm the server has started successfully.
To find the Output Panel, go to the menu and select **View > Output**.
You should see log entries similar to the following:
```
2025-11-14 14:12:46.829 [info] Starting server wherobots-mcp-server
2025-11-14 14:12:46.831 [info] Connection state: Starting
2025-11-14 14:12:46.831 [info] Starting server from LocalProcess extension host
2025-11-14 14:12:46.833 [info] Connection state: Running
2025-11-14 14:12:47.953 [info] Discovered 8 tools
```
### Use the MCP server
1. Open your editor's AI assistant (e.g. GitHub Copilot Chat in VS Code via **View > Chat**).
2. If you haven't already, start a new chat session.
3. Make sure you have **Agent** selected as the chat mode. You can select this from the dropdown menu at the top of the chat panel.
4. You can also select the **model** you wish to use alongside the MCP server from the adjacent dropdown. Quality of responses may vary between models.
Wherobots recommends using the latest versions of advanced models like Claude Opus, Claude Sonnet, Gemini Pro, or GPT Codex for optimal performance with the MCP server.
5. Ask a question to see if it interacts with the Wherobots service, for example:
> Show me the catalogs in my Organization
6. If successful, your AI assistant will confirm it is using the Wherobots MCP server (showing `Ran list_catalogs` or a similar tool) and display all of the available catalogs in your Organization.
The exact response will vary depending on the datasets within your Organization as well as the model used to query the MCP server.
At minimum, `wherobots_open_data` appears for Community Edition, and both `wherobots_open_data` and `wherobots_pro_data` for Professional and Enterprise Edition Organizations.
### Stop the MCP server
When you are finished asking Wherobots-related questions, it is important to stop the MCP server.
Stopping the server ensures that no additional charges are incurred from the MCP server and that resources are freed for other tasks.
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**.
## Enable the Wherobots MCP server in other tools
### OpenCode
If you have OpenCode enabled, complete the following steps to enable the Wherobots MCP server.
1. In your terminal, run `opencode mcp add`
2. Configure the following settings:
* **MCP server name:** ``
* **MCP server type:** `Remote`
* **MCP server URL:** `https://api.cloud.wherobots.com/mcp/`
* **OAuth authentication:** `No`
3. Set the **WHEROBOTS\_API\_KEY** environment variable to the API key you created earlier
* If you need the API key persisted across sessions, you can add `export WHEROBOTS_API_KEY=` to your shell profile (e.g., \~/.bashrc or \~/.zshrc on Mac or Linux).
4. Restart OpenCode
5. Ask a question to verify that the MCP server is working, for example:
> Show me the catalogs in my Organization
6. If configured correctly, OpenCode will call the Wherobots MCP server (showing a tool such as `list_catalogs`) and return the catalogs available in your Organization
OpenCode requires using a [modern terminal emulator](https://opencode.ai/docs/#prerequisites) for the most optimal experience.
For more information on downloading, installing and using OpenCode, see [Install](https://opencode.ai/docs/#install)
and [Usage](https://opencode.ai/docs/#usage) sections in the OpenCode documentation.
### Claude Code
1. In a terminal, run the following command after replacing the placeholder server name and API key with your own:
```shell theme={"system"}
claude mcp add --transport http https://api.cloud.wherobots.com/mcp/ --scope user --header "X-API-Key: "
```
2. Restart Claude Code
3. Ask a question to verify the MCP server is working, for example:
> Show me the catalogs in my Organization
4. If configured correctly, Claude Code will call the Wherobots MCP server (showing a tool such as `list_catalogs`) and return the catalogs available in your Organization
For more information on downloading, installing and using Claude Code, see [Claude Code overview](https://code.claude.com/docs/en/overview)
and [Quickstart](https://code.claude.com/docs/en/quickstart) in the Claude Code Documentation.
## Next steps and best practices
The MCP server excels at helping you understand and work with your spatial data.
Use natural language prompts to explore datasets, assess data quality, and generate spatial SQL queries.
Start by asking questions about your catalogs or datasets to see how the MCP server can assist you in your geospatial analysis tasks.
* For more information on using the MCP Server including common tasks, example prompts, and cost considerations
see [MCP Server Best Practices and Usage](/develop/mcp/mcp-server-usage).
* For a video walkthrough of the MCP server in action, see [Video: Automating Geospatial Discovery and Query Generation](/develop/mcp/mcp-server-automating-geospatial-workflows).
4. You can also select the **model** you wish to use alongside the MCP server from the adjacent dropdown. Quality of responses may vary between models.
At minimum, `wherobots_open_data` appears for Community Edition, and both `wherobots_open_data` and `wherobots_pro_data` for Professional and Enterprise Edition Organizations.
### Stop the MCP server
When you are finished asking Wherobots-related questions, it is important to stop the MCP server.
Stopping the server ensures that no additional charges are incurred from the MCP server and that resources are freed for other tasks.
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**.
4. You can also select the **model** you wish to use alongside the MCP server from the adjacent dropdown. Quality of responses may vary between models.