Set Up Wherobots in OpenCode

Public Preview OpenCode is an open-source terminal-based agentic coding tool. Unlike the VS Code extension, OpenCode requires separate installation of the MCP Server, Agent Skills, and CLI. The following instructions work for both the Open Code Agentic Terminal and the OpenCode desktop application. For more information on OpenCode, see the OpenCode documentation.

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

The following prerequisites are required:

OpenCode installed with a modern terminal emulator.
A Wherobots Account within a Professional, Innovation, or Enterprise Organization. See Create a Wherobots Account.
A browser to sign in to Wherobots. OpenCode signs in to the MCP server with OAuth, and the Wherobots CLI signs in with wherobots auth login.
- For CI, scripts, or editors that don’t support OAuth, use a Wherobots API key instead. For more information, see API Keys.
Node.js and npm installed on your system (required for installing Agent Skills via npx).

Install Wherobots MCP Server in OpenCode

These steps connect OpenCode to the Wherobots MCP Server, giving your AI assistant access to your Wherobots Organization’s catalogs, datasets, and tools.

Configure the MCP Server

Choose one of two methods to add the Wherobots MCP server to OpenCode.

Use opencode mcp add (recommended)
Edit configuration JSON manually

In your terminal, start the OpenCode MCP setup wizard:
opencode mcp add

Respond to each prompt as follows:

Prompt	Value
Location	`Global` or `Local`
Enter MCP server name	`YOUR-WHEROBOTS-MCP-SERVER-NAME` Replace with your desired name for the Wherobots MCP server
Select MCP server type	`Remote`
Enter MCP server URL	`https://api.cloud.wherobots.com/mcp/`
Does this server require OAuth authentication?	`Yes`
Do you have a pre-registered client ID?	`No`

Choose the Global location to make the server available in all your projects, or Local to keep it separate from other projects.

OpenCode writes the entry to ~/.config/opencode/opencode.jsonc and prints MCP server "YOUR-WHEROBOTS-MCP-SERVER-NAME" added successfully.

Terminal showing the completed opencode mcp add wizard prompts — Completed opencode mcp add wizard.

Authenticate the new server with OAuth, replacing <YOUR-WHEROBOTS-MCP-SERVER-NAME> with your desired name for the Wherobots MCP server (e.g. wherobots-mcp-server-opencode):
opencode mcp auth <YOUR-WHEROBOTS-MCP-SERVER-NAME>
This opens a browser window prompting you to log in to your Wherobots account and authorize OpenCode to access your account information.
In the browser, select the Wherobots Organization that you want OpenCode to access, then click Allow Access.
OpenCode OAuth consent screen.
Once the browser shows Authorization Successful, close the tab and return to your terminal. OpenCode prints Authentication successful!.
Authorization Successful confirmation page.

Verify the server is connected:

opencode mcp list

You should see something similar to the following, YOUR-WHEROBOTS-MCP-SERVER-NAME connected (OAuth) along with the server URL.

┌  MCP Servers
│
●  ✓ YOUR-WHEROBOTS-MCP-SERVER-NAME connected (OAuth)
│      https://api.cloud.wherobots.com/mcp/
│
│
└  1 server(s)

Open your OpenCode config file in your editor — the path determines the scope (create the file if it does not exist):
- Global (available in all projects): ~/.config/opencode/opencode.jsonc (or ~/.config/opencode/opencode.json).
- Local (project-specific): opencode.jsonc (or opencode.json) in your project root.

Add a YOUR-WHEROBOTS-MCP-SERVER-NAME entry under mcp, replacing YOUR-WHEROBOTS-MCP-SERVER-NAME with your desired name for the Wherobots MCP server (e.g. wherobots-mcp-server-opencode):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "YOUR-WHEROBOTS-MCP-SERVER-NAME": {
      "type": "remote",
      "url": "https://api.cloud.wherobots.com/mcp/",
      "oauth": {}
    }
  }
}

Save the file, then start the OAuth flow:
opencode mcp auth YOUR-WHEROBOTS-MCP-SERVER-NAME
Sign in to Wherobots in the browser, select your Organization, and click Allow Access.
OpenCode OAuth consent screen.
The browser shows Authorization Successful.
Authorization Successful confirmation page.

In the terminal, verify the server is connected:

opencode mcp list

You will see something similar to the following, YOUR-WHEROBOTS-MCP-SERVER-NAME connected (OAuth) along with the server URL.

┌  MCP Servers
│
●  ✓ wherobots-opencode-oauth connected (OAuth)
│      https://api.cloud.wherobots.com/mcp/
│
│
└  1 server(s)

Alternative: Use an API key instead of OAuth

For CI, scripts, or other environments where browser sign-in isn’t possible, turn off OAuth for the server entry and add an x-api-key header that contains your Wherobots API key:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "YOUR-WHEROBOTS-MCP-SERVER-NAME": {
      "type": "remote",
      "url": "https://api.cloud.wherobots.com/mcp/",
      "oauth": false,
      "headers": {
        "x-api-key": "<YOUR_WHEROBOTS_API_KEY>"
      }
    }
  }
}

For more information on downloading, installing, and using OpenCode, see Install and Usage sections in the OpenCode documentation.

Install Agent Skills

Agent Skills give your AI assistant structured context about Wherobots workflows, APIs, and best practices.

npx skills add -g wherobots/agent-skills

Install the CLI (optional)

The Wherobots CLI wraps the full Wherobots API into a single binary for job submission, log streaming, and automation.

curl -fsSL https://raw.githubusercontent.com/wherobots/wherobots-cli/main/scripts/install-release.sh | bash

wherobots auth login

Confirm that the code in the browser matches the one printed in the terminal, select your Organization, and authorize the CLI.

For scripts and other non-interactive use, set an API key instead with export WHEROBOTS_API_KEY='<your-api-key>'. See Configure authentication.

Verify the connection:

wherobots --tree

Verify installation

The following steps confirm that OpenCode is properly connected to the Wherobots MCP server and that your AI assistant can access your Wherobots data and tools.

Test the MCP Server connection

To confirm that OpenCode can communicate with the Wherobots MCP server, ask a question in your AI assistant within OpenCode:

List the catalogs in my Wherobots Data Hub

If configured correctly, OpenCode will call the Wherobots MCP server (showing a tool such as list_catalogs_tool) and return the catalogs available in your Organization.

Next steps

Explore the following resources to learn how to use Wherobots in OpenCode and get ideas for using your AI assistant to automate geospatial workflows.

MCP Server Best Practices

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

MCP Server Demo Videos

Watch the MCP Server automate catalog discovery, spatial queries, and notebook generation.

Agent Skills

Learn more about available skills and installation options.

Agentic Terminal Usage

Use the CLI with OpenCode for natural language job management.

CLI Reference

Submit jobs, stream logs, and access the full Wherobots API.

MCP Server vs CLI

Understand when to use the MCP Server vs. the CLI.

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 OpenCode

Component Overview

Why use Wherobots’ agentic tools?

Before you start

Install Wherobots MCP Server in OpenCode

Verify installation

Test the MCP Server connection

Next steps

MCP Server Best Practices

MCP Server Demo Videos

Agent Skills

Agentic Terminal Usage

CLI Reference

MCP Server vs CLI

​Component Overview

​Why use Wherobots’ agentic tools?

​Before you start

​Install Wherobots MCP Server in OpenCode

​Verify installation

​Test the MCP Server connection

​Next steps

MCP Server Best Practices

MCP Server Demo Videos

Agent Skills

Agentic Terminal Usage

CLI Reference

MCP Server vs CLI

Component Overview

Why use Wherobots’ agentic tools?

Before you start

Install Wherobots MCP Server in OpenCode

Verify installation

Test the MCP Server connection

Next steps