Set Up Wherobots in Kiro

Public Preview Kiro 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.

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 the MCP Server returns optimized Spatial SQL using WherobotsDB’s ST functions, spatial joins, and indexing patterns.

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.

What you’ll do

Here’s a high-level overview of the steps to set up Wherobots in Kiro:

1. Install the extension

Install the Wherobots extension and set your API key. Jump to section.

2. Enable MCP support

Turn on MCP in Kiro’s settings so the server can connect. Jump to section.

3. Configure the MCP Server

Add the Wherobots MCP server to mcp.json. Jump to section.

4. Install Agent Skills

Give your AI assistant Wherobots-specific knowledge. Jump to section.

5. Verify your setup

Confirm the setup with a test query. Jump to section.

Before you start

Prior to installing the Wherobots VS Code extension, make sure you have:

Kiro installed.
- For more information on Kiro Plans see Kiro Pricing.
A Wherobots Account within a Community, Professional, or Enterprise Organization.
- For more information, see Create a Wherobots Account.
  Organization Availability: Available to all Wherobots Organization Editions.
  - Community Edition Organizations can create and run local notebooks against the Tiny and Micro runtimes.
  - Professional or Enterprise Organizations are required for job submission, the Wherobots MCP server, and additional compute tiers. For more information, see Upgrade Organization or Organization Editions.

Install the extension

Run the following command in your terminal:

kiro --install-extension Wherobots.wherobotsjobsubmit

Or install from the Open VSX Registry.

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.

Open the Command Palette

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.

Set your API key

If you don’t have an API key yet, click Wherobots: Generate API Key on Wherobots Cloud to create one.
Click Wherobots: Set API Key and enter your existing or newly created Wherobots API key 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:

Open the Command Palette

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.

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

Enable MCP support

Kiro requires MCP to be explicitly enabled before it will connect to any MCP server.

Open Kiro Settings

Press ⌘ + , on macOS or Ctrl + , on Windows/Linux to open Settings.Make sure the following are enabled:

wherobotsjobsubmit.mcpServerEnabled
kiroAgent.configureMCP

Kiro Settings panel with the Wherobots MCP server and job submission settings enabled

Enable MCP

In Kiro’s Command Palette, search for kiro: open MCP Config.

Configure the MCP Server

The Wherobots MCP Server 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.

Open your MCP config file

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).

Kiro MCP config editor showing User Config and Workspace Config tabs

Add the Wherobots MCP server

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.
```
    {
      "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.
Replace “YOUR_WHEROBOTS_API_KEY” with your Wherobots API key.
Save the file. Kiro automatically detects the change and may add disabled, autoApprove, and disabledTools fields to the entry.

Confirm the server connected

Open the Output panel (⌘ + Shift + U)
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.

For advanced MCP configuration options, see Configure Wherobots MCP Server.

Agent Skills

The Wherobots 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.

Open the skill import dialog

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.

Kiro Agent Steering & Skills section with + button to add a new skill highlighted

Select Import skill from GitHub

Type Agent Skills in the search bar that appears.
Select either Global agent skills or Project-specific agent skills from the dropdown.
Click Import skill from GitHub.
This opens a dialog where you can paste the URL of the skill’s GitHub repository.

Import each Wherobots skill

For each URL below, hover over the URL and click on the right-hand side to copy the URL to your clipboard.

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

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.

Confirm the skills are installed

All three skills should appear under AGENT STEERING & SKILLS in the sidebar.

Kiro sidebar with all three Wherobots skills installed under Agent Steering & Skills

Verify your setup

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.
Open a New Session chat panel.
Ask a test question, for example:
List the catalogs I have access to in Wherobots
Kiro’s agent calls list_catalogs_tool on the wherobots MCP server. You may be prompted to Trust or Run the tool call.
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:

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 Kiro Activity Bar

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”.

Kiro error dialog showing the workbench.mcp.browseServers command 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 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 section above to ensure MCP is turned on 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.

MCP Server Best Practices

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

Agentic Development

Notebook Management

RasterFlow

SQL API & SDKs

Storage Management

Orchestration

Monitoring

Set Up Wherobots in Kiro

Why use Wherobots’ agentic tools?

What you’ll do

Before you start

Install the extension

Configure the extension

Verify the installation

Enable MCP support

Configure the MCP Server

Agent Skills

Import Agent Skills

Verify your setup

Pin the extension for easy access

Troubleshooting

`MCP: Browse MCP Servers` results in an error

`Error loading powers config: Unexpected token`

`MCP is currently disabled`

Next steps

Browse Your Data

AI-Assisted Notebooks

Submit Job Runs

MCP Server Best Practices

Agentic Development

Notebook Management

RasterFlow

SQL API & SDKs

Storage Management

Orchestration

Monitoring

​Why use Wherobots’ agentic tools?

​What you’ll do

​Before you start

​Install the extension

​Configure the extension

​Verify the installation

​Enable MCP support

​Configure the MCP Server

​Agent Skills

​Import Agent Skills

​Verify your setup

​Pin the extension for easy access

​Troubleshooting

​MCP: Browse MCP Servers results in an error

​Error loading powers config: Unexpected token

​MCP is currently disabled

​Next steps

Browse Your Data

AI-Assisted Notebooks

Submit Job Runs

MCP Server Best Practices

Why use Wherobots’ agentic tools?

What you’ll do

Before you start

Install the extension

Configure the extension

Verify the installation

Enable MCP support

Configure the MCP Server

Agent Skills

Import Agent Skills

Verify your setup

Pin the extension for easy access

Troubleshooting

`MCP: Browse MCP Servers` results in an error

`Error loading powers config: Unexpected token`

`MCP is currently disabled`

Next steps