> ## 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 OpenCode

> Configure the Wherobots MCP Server, Agent Skills, and CLI in OpenCode for AI-assisted geospatial development from your terminal.

<Badge color="purple">Public Preview</Badge>

[**OpenCode**](https://opencode.ai/) 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](https://opencode.ai/docs/).

## Component Overview

Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience:

<AccordionGroup>
  <Accordion title="MCP Server" icon="message-bot">
    Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution.
  </Accordion>

  <Accordion title="Agent Skills" icon="brain">
    Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors.
  </Accordion>

  <Accordion title="Wherobots CLI" icon="terminal">
    Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation.
  </Accordion>
</AccordionGroup>

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

<AccordionGroup>
  <Accordion title="Explore your spatial catalog conversationally" icon="book-open">
    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.
  </Accordion>

  <Accordion title="Generate Spatial SQL without memorizing functions" icon="code">
    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.
  </Accordion>

  <Accordion title="Submit and monitor Wherobots jobs from your editor" icon="rocket">
    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.
  </Accordion>

  <Accordion title="Get Wherobots-aware AI assistance" icon="brain">
    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.
  </Accordion>
</AccordionGroup>

## Before you start

The following prerequisites are required:

* [OpenCode](https://opencode.ai/) installed with a [modern terminal emulator](https://opencode.ai/docs/#prerequisites).
* A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account).
* A Wherobots API key. For more information, see [API Keys](/get-started/wherobots-cloud/api-keys).
  * You will use this to install the Wherobots CLI, which is recommended for accessing Wherobots features in OpenCode.
* [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) 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.

<Steps>
  <Step title="Configure the MCP Server">
    Choose one of two methods to add the Wherobots MCP server to OpenCode.

    <Tabs>
      <Tab title="Use opencode mcp add (recommended)">
        1. In your terminal, start the OpenCode MCP setup wizard:

           ```bash theme={"system"}
           opencode mcp add
           ```

        2. Respond to each prompt as follows:

           | Prompt                                              | Value                                                                                                     |
           | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
           | Location                                            | `Global` or `Local`                                                                                       |
           | Enter MCP server name                               | `YOUR-WHEROBOTS-MCP-SERVER-NAME` <br /><br /> 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<br />require OAuth authentication? | `Yes`                                                                                                     |
           | Do you have a pre-registered<br />client ID?        | `No`                                                                                                      |

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

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

                   <Frame caption="Completed opencode mcp add wizard.">
                     <img src="https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/opencode-mcp-add-wizard.png?fit=max&auto=format&n=-xg1VXa7MjWQmfwe&q=85&s=756b9b8e53108c422003ad0f29de8504" alt="Terminal showing the completed opencode mcp add wizard prompts" width="833" height="621" data-path="develop/agentic-tools/images/opencode-mcp-add-wizard.png" />
                   </Frame>

        3. 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`):

           ```bash theme={"system"}
           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.

        4. In the browser, select the Wherobots Organization that you want OpenCode to access, then click **Allow Access**.

                   <Frame caption="OpenCode OAuth consent screen.">
                     <img src="https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/opencode-oauth-consent.png?fit=max&auto=format&n=-xg1VXa7MjWQmfwe&q=85&s=911365bdfe4058016ab6ca65500bb90d" alt="Wherobots OAuth consent screen prompting OpenCode access for the selected Organization" width="1495" height="765" data-path="develop/agentic-tools/images/opencode-oauth-consent.png" />
                   </Frame>

        5. Once the browser shows **Authorization Successful**, close the tab and return to your terminal. OpenCode prints `Authentication successful!`.

                   <Frame caption="Authorization Successful confirmation page.">
                     <img src="https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/opencode-oauth-success.png?fit=max&auto=format&n=-xg1VXa7MjWQmfwe&q=85&s=153f23d8c67696e8614dce9474c5c615" alt="Browser page confirming Authorization Successful" width="2897" height="1628" data-path="develop/agentic-tools/images/opencode-oauth-success.png" />
                   </Frame>

        6. Verify the server is connected:

           ```bash theme={"system"}
           opencode mcp list
           ```

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

           ```bash theme={"system"}
           ┌  MCP Servers
           │
           ●  ✓ YOUR-WHEROBOTS-MCP-SERVER-NAME connected (OAuth)
           │      https://api.cloud.wherobots.com/mcp/
           │
           │
           └  1 server(s)
           ```
      </Tab>

      <Tab title="Edit configuration JSON manually">
        1. 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.

        2. 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`):

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

        3. Save the file, then start the OAuth flow:

           ```bash theme={"system"}
           opencode mcp auth YOUR-WHEROBOTS-MCP-SERVER-NAME
           ```

           Sign in to Wherobots in the browser, select your Organization, and click **Allow Access**.

                   <Frame caption="OpenCode OAuth consent screen.">
                     <img src="https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/opencode-oauth-consent.png?fit=max&auto=format&n=-xg1VXa7MjWQmfwe&q=85&s=911365bdfe4058016ab6ca65500bb90d" alt="Wherobots OAuth consent screen prompting OpenCode access for the selected Organization" width="1495" height="765" data-path="develop/agentic-tools/images/opencode-oauth-consent.png" />
                   </Frame>

           The browser shows **Authorization Successful**.

                   <Frame caption="Authorization Successful confirmation page.">
                     <img src="https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/opencode-oauth-success.png?fit=max&auto=format&n=-xg1VXa7MjWQmfwe&q=85&s=153f23d8c67696e8614dce9474c5c615" alt="Browser page confirming Authorization Successful" width="2897" height="1628" data-path="develop/agentic-tools/images/opencode-oauth-success.png" />
                   </Frame>

        4. In the terminal, verify the server is connected:

           ```bash theme={"system"}
           opencode mcp list
           ```

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

           ```bash theme={"system"}
           ┌  MCP Servers
           │
           ●  ✓ wherobots-opencode-oauth connected (OAuth)
           │      https://api.cloud.wherobots.com/mcp/
           │
           │
           └  1 server(s)
           ```
      </Tab>
    </Tabs>

    <Info>
      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.
    </Info>
  </Step>

  <Step title="Install Agent Skills">
    [Agent Skills](/develop/agent-skills) give your AI assistant structured context about Wherobots workflows, APIs, and best practices.

    ```bash theme={"system"}
    npx skills add -g wherobots/agent-skills
    ```
  </Step>

  <Step title="Install the CLI (optional)">
    The [Wherobots CLI](/develop/cli) wraps the full Wherobots API into a single binary for job submission, log streaming, and automation.

    ```bash theme={"system"}
    gh repo clone wherobots/wbc-cli && cd wbc-cli && ./scripts/install-release.sh
    ```

    Set your API key as an environment variable:

    ```bash theme={"system"}
    export WHEROBOTS_API_KEY='<your-api-key>'
    ```

    Verify the connection:

    ```bash theme={"system"}
    wherobots api --tree
    ```
  </Step>
</Steps>

## 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:

```text wrap theme={"system"}
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`) 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.

<CardGroup cols={2}>
  <Card title="MCP Server Best Practices" icon="message-bot" href="/develop/mcp/mcp-server-usage">
    Common tasks, example prompts, and cost considerations for the MCP Server.
  </Card>

  <Card title="MCP Server Demo Videos" icon="video" href="/develop/mcp/mcp-server-automating-geospatial-workflows">
    Watch the MCP Server automate catalog discovery, spatial queries, and notebook generation.
  </Card>

  <Card title="Agent Skills" icon="brain" href="/develop/agent-skills">
    Learn more about available skills and installation options.
  </Card>

  <Card title="Agentic Terminal Usage" icon="terminal" href="/develop/cli-agentic-usage">
    Use the CLI with OpenCode for natural language job management.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/develop/cli">
    Submit jobs, stream logs, and access the full Wherobots API.
  </Card>

  <Card title="MCP Server vs CLI" icon="scale-balanced" href="/develop/mcp-vs-cli">
    Understand when to use the MCP Server vs. the CLI.
  </Card>
</CardGroup>