> ## 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 Kiro
> Install the Wherobots VS Code Extension in Kiro and manually configure the MCP Server and Agent Skills for AI-assisted geospatial development.
Public Preview
[**Kiro**](https://kiro.dev/) by Amazon Web Services is a Code OSS-based editor with spec-driven AI development.
The Wherobots extension installs from the Open VSX Registry, but MCP support must be enabled in Kiro's
settings before the server will connect, and the MCP config file must use Kiro's `mcpServers` schema.
## 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.
## What you'll do
Here's a high-level overview of the steps to set up Wherobots in Kiro:
Install the Wherobots extension and set your API key. [Jump to section](#install-the-extension).
Turn on MCP in Kiro's settings so the server can connect. [Jump to section](#enable-mcp-support).
Add the Wherobots MCP server to `mcp.json`. [Jump to section](#configure-the-mcp-server).
Give your AI assistant Wherobots-specific knowledge. [Jump to section](#install-agent-skills).
Confirm the setup with a test query. [Jump to section](#verify-your-setup).
## Before you start
Prior to installing the Wherobots VS Code extension, make sure you have:
* [Kiro](https://kiro.dev/) installed.
* For more information on Kiro Plans see [Kiro Pricing](https://kiro.dev/pricing/).
* A **Wherobots Account** within a Community, Professional, or Enterprise Organization.
* For more information, see [Create a Wherobots Account](/get-started/wherobots-cloud/create-account).
**Organization Availability:** Available to all Wherobots Organization Editions.
* **Community Edition Organizations** can create and run local notebooks against the [Tiny and Micro runtimes](/develop/runtimes).
* **Professional or Enterprise Organizations** are required for job submission, the Wherobots MCP server, and additional compute tiers. For more information, see [Upgrade Organization](/get-started/upgrade-organization) or [Organization Editions](/get-started/organization-management/organization-editions).
## Install the extension
Run the following command in your terminal:
```bash theme={"system"}
kiro --install-extension Wherobots.wherobotsjobsubmit
```
Or install from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit).
### Configure the extension
After installation, set your API key to connect to Wherobots Cloud.
If Kiro prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload**.
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.
You will also use this API key in the MCP Server configuration later in this guide.
### 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`
## Enable MCP support
Kiro requires MCP to be explicitly enabled before it will connect to any MCP server.
Press ⌘ + , on macOS or Ctrl + , on Windows/Linux to open **Settings**.
Make sure the following are enabled:
* `wherobotsjobsubmit.mcpServerEnabled`
* `kiroAgent.configureMCP`
In Kiro's **Command Palette**, search for `kiro: open MCP Config`.
## Configure the MCP Server
The [Wherobots MCP Server](/develop/mcp/mcp-server-setup) enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries.
Kiro stores MCP configuration in `mcp.json` using a `mcpServers` object. Choose the appropriate level for your use case:
| 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. |
The steps below use the **User Config** so the server is available in all workspaces.
To use 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)**. Kiro opens `~/.kiro/settings/mcp.json`.
You can also open it via the **Command Palette** (⌘ + Shift + P) by typing **Kiro: Open User MCP Config (JSON)**.
1. Copy and paste the following snippet into your `mcp.json`, modifying the API key as described:
If the file already contains other servers, add the new entry alongside them.
```json wrap theme={"system"}
{
"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 will produce an *"Error loading powers config: Unexpected token"* message in the Output panel.
2. Replace "YOUR\_WHEROBOTS\_API\_KEY" with your [Wherobots API key](/get-started/wherobots-cloud/api-keys/).
3. Save the file.
Kiro automatically detects the change and may add `disabled`, `autoApprove`, and `disabledTools` fields to the entry.
1. Open the **Output** panel (⌘ + Shift + U)
2. Look for the following message in the **Kiro - MCP Logs** output stream:
```sh wrap theme={"system"}
[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.
The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See [Configure MCP server settings](/develop/mcp/mcp-server-setup#configure-mcp-server-settings).
## Agent Skills
The Wherobots [Agent Skills](/develop/agent-skills) give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices.
Install all three Wherobots skills for comprehensive AI assistance across your Wherobots development workflow.
These Skills enable your AI assistant to provide accurate, Wherobots-specific guidance in chat and notebooks.
| Skill | Purpose |
| ------------------- | ------------------------------------------------------------------ |
| `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. |
### Import Agent Skills
Kiro can import skills directly from GitHub through the **Agent Steering & Skills** panel in the sidebar.
-
Click the
Kiro icon in the Activity Bar to open the sidebar.
- Open the AGENT STEERING & SKILLS section.
- Click the + button to add a new skill.
1. Type **Agent Skills** in the search bar that appears.
2. Select either **Global agent skills** or Project-specific agent skills from the dropdown.
3. Click **Import skill from GitHub**.
4. This opens a dialog where you can paste the URL of the skill's GitHub repository.
1. For each URL below, hover over the URL and click on the right-hand side to copy the URL to your clipboard.
```sh wrap theme={"system"}
https://github.com/wherobots/agent-skills/tree/main/.agents/skills/wherobots-develop
```
```sh wrap theme={"system"}
https://github.com/wherobots/agent-skills/tree/main/.agents/skills/wherobots-explore
```
```sh wrap theme={"system"}
https://github.com/wherobots/agent-skills/tree/main/.agents/skills/wherobots-usage
```
2. Paste the URL into Kiro's import dialog and press Enter.
After each import, Kiro downloads the `SKILL.md` file and adds the skill to the **AGENT STEERING & SKILLS** section in the sidebar.
We recommend installing **all three skills** to get the full benefits of AI-assisted development with Wherobots.
All three skills should appear under **AGENT STEERING & SKILLS** in the sidebar.
## Verify your setup
1. Check the **MCP SERVERS** section in Kiro's sidebar (left panel).
You should see `wherobots` with **Connected (8 tools)** and a list of tools including `list_catalogs_tool`, `list_tables_tool`, `describe_table_tool`, `execute_query_tool`, and `search_documentation_tool`.
2. Open a **New Session** chat panel.
3. Ask a test question, for example:
> List the catalogs I have access to in Wherobots
4. Kiro's agent calls `list_catalogs_tool` on the `wherobots` MCP server. You may be prompted to **Trust** or **Run** the tool call.
5. If successful, the agent returns your available catalogs, which includes `wherobots_open_data`, `wherobots_pro_data` (for Professional and Enterprise Organizations), and any private catalogs in your Organization.
## 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.
To pin the Wherobots extension to the sidebar:
Right-click the **Activity Bar** (the vertical icon bar on the left side of your editor).
A menu will appear showing all available extensions.
To pin the extension, find **Wherobots** in the list and click on it to ensure it's checked.
## Troubleshooting
### `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 will display *"command 'workbench.mcp.browseServers' not found"*.
This does **not** mean the MCP server is broken.
To verify the server is working:
* Check the **MCP SERVERS** section in Kiro's sidebar for a green **Connected** status.
* Check the **Output** panel → **Kiro - MCP Logs** for the "Successfully connected" message.
* Test the server directly in chat by asking a question like *"Show me the catalogs in my Wherobots Organization"*.
### `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. Kiro does not use this field and it will cause an error.
* Missing the outer `{ ... }` wrapper or a trailing comma.
Re-paste the snippet from [Configure the MCP Server](#configure-the-mcp-server) exactly as shown, save the file, and check the Output panel for a successful connection.
### `MCP is currently disabled`
If you see a banner saying *"MCP is currently disabled. To start using MCP, please enable it in the settings."*, review
the [Enable MCP support](#enable-mcp-support) section above to ensure MCP is turned on in Kiro's settings.
## Next steps
Browse catalogs, schemas, and tables in the Data Hub sidebar.
Create and connect local notebooks to remote Wherobots compute.
Submit Python scripts as Wherobots job runs from your editor.
Common tasks, example prompts, and cost considerations for the MCP Server.