Set Up Wherobots in an AI Assistant

Public Preview Every AI assistant on this page connects to the same Wherobots MCP Server, at https://api.cloud.wherobots.com/mcp/, and signs in with OAuth. The MCP Server lets your assistant explore your catalogs, search the Wherobots documentation, run read-only Spatial SQL queries, and read workload and Spark execution details. Only the place where you add the server differs between assistants. Terminal agents (Claude Code, Codex, and OpenCode) can also use Agent Skills and the Wherobots CLI. Claude and ChatGPT run in a chat app, so their setup covers the MCP Server only. For what each Wherobots component does, see What each component does. To use Wherobots in VS Code or another Code OSS editor instead, see Set Up Wherobots in Your Editor.

Before you start

You need:

A Wherobots Account. See Create a Wherobots Account.
A browser to sign in to Wherobots with OAuth. For CI, scripts, or other environments where browser sign-in isn’t possible, terminal agents can use a Wherobots API key instead.
Your AI assistant:

Assistant	Requirements
Claude Code	Claude Code installed.
Codex	The Codex CLI, run in a modern terminal emulator, or the Codex desktop app.
OpenCode	OpenCode, the terminal agent with a modern terminal emulator or the desktop app.
Claude (desktop and web)	A Claude account with an active paid subscription, and Claude Desktop for the desktop flow. On Team and Enterprise plans, an Owner or Primary Owner may need to enable connectors for your Claude organization first.
ChatGPT	A ChatGPT account with an active paid plan (Plus, Pro, Business, or Enterprise), and ChatGPT Desktop for the desktop flow.

For the terminal agents, you also need Node.js with npm to install Agent Skills with npx.

Connect the MCP Server

Choose your assistant.

Claude Code
Codex
OpenCode
Claude (desktop and web)
ChatGPT

Claude Code is Anthropic’s terminal-based agentic tool.

Add the MCP server

In a terminal, run the following command, replacing the placeholder with your preferred server name:

claude mcp add --transport http <YOUR_SERVER_NAME> https://api.cloud.wherobots.com/mcp/ --scope user

The --scope user flag makes the server available to all your Claude Code agents. For more information on scope options, see the Claude Code documentation.Claude Code signs in to the MCP server with OAuth. When you first use the MCP server, a browser window opens for you to sign in to Wherobots and select your organization.

Alternative: Use an API key instead of OAuth

Add the server with an x-api-key header that contains your Wherobots API key:

claude mcp add --transport http <YOUR_SERVER_NAME> https://api.cloud.wherobots.com/mcp/ --scope user --header "x-api-key: <YOUR_WHEROBOTS_API_KEY>"

Restart Claude Code

Restart Claude Code after adding the server. Then add Agent Skills and the CLI.For more information on installing and using Claude Code, see the Claude Code overview and Quickstart.

Codex is OpenAI’s agentic coding tool, available as a terminal CLI and a desktop app. Both read MCP server entries from the same ~/.codex/config.toml file, so these steps apply to both.

Add the MCP server

In a terminal, run the following command, replacing <YOUR_SERVER_NAME> with your preferred name (e.g. wherobots-mcp-server):

codex mcp add <YOUR_SERVER_NAME> --url https://api.cloud.wherobots.com/mcp/

Codex saves the server entry in ~/.codex/config.toml.

Alternative: Edit config.toml directly

Open ~/.codex/config.toml in your editor (create the file if it does not exist) and add a section for the Wherobots MCP server:

[mcp_servers.<YOUR_SERVER_NAME>]
url = "https://api.cloud.wherobots.com/mcp/"

Alternative: Use an API key instead of OAuth

Skip codex mcp login and add an X-API-Key header with your Wherobots API key to the server entry in ~/.codex/config.toml:

[mcp_servers.<YOUR_SERVER_NAME>]
url = "https://api.cloud.wherobots.com/mcp/"
http_headers = { "X-API-Key" = "<YOUR_WHEROBOTS_API_KEY>" }

Start the OAuth flow:

codex mcp login <YOUR_SERVER_NAME>

A browser window opens for you to sign in to Wherobots. Select your Organization and click Allow access. Alternatively, copy the URL that the terminal displays into any browser to complete the login.

Restart Codex

Restart Codex so it picks up the new MCP server. Then add Agent Skills and the CLI.When you verify your setup, Codex lists the Wherobots MCP Server as a Source while it processes your query.

Codex agentic verify — Verifying Wherobots MCP Server as a source in Codex

For more information on installing and using Codex, see the Codex documentation.

OpenCode is an open-source agentic coding tool for the terminal and desktop. These steps work for both. For more information, see the OpenCode documentation.

Add the MCP server

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.

Alternative: Edit the configuration file instead

Open your OpenCode config file (create it if it does not exist). The path sets the scope:

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 an entry under mcp, replacing YOUR-WHEROBOTS-MCP-SERVER-NAME with your desired name (e.g. wherobots-mcp-server-opencode), and save the file:

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

Alternative: Use an API key instead of OAuth

Turn off OAuth for the server entry and add an x-api-key header that contains your Wherobots API key. Then skip the OAuth step.

{
  "$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>"
      }
    }
  }
}

Authenticate the new server, replacing <YOUR-WHEROBOTS-MCP-SERVER-NAME> with the name you chose:

opencode mcp auth <YOUR-WHEROBOTS-MCP-SERVER-NAME>

A browser window opens. Sign in to Wherobots, select the Organization that you want OpenCode to access, and click Allow Access.

Wherobots OAuth consent screen prompting OpenCode access for the selected Organization — OpenCode OAuth consent screen.

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

Browser page confirming Authorization Successful — Authorization Successful confirmation page.

Confirm the server is connected

Run:

opencode mcp list

You should see 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)

Then add Agent Skills and the CLI.

Claude is Anthropic’s AI assistant, available as a desktop app for macOS and Windows and in the browser. Both add Wherobots as an official connector from Claude’s connector Directory, and each user enables it from their own account.

On Team and Enterprise plans, an Owner or Primary Owner may need to enable connectors for the organization before you can add Wherobots. Each user still authenticates individually after it is enabled. For more information, see Use Connectors to extend Claude’s capabilities.

Open Connectors in Claude

Web: Go to https://claude.ai/directory.
Desktop: Open Customize > Connectors > Browse from the left sidebar.

Enable the Wherobots connector

In the Directory modal, search for wherobots.
Select the official Wherobots Spatial AI Assistant.
Click + to enable the Connector in your Claude Organization.

Complete OAuth

A new browser tab opens to the Wherobots sign-in page.
Sign in to Wherobots, select your Organization from the Organization access dropdown, and click Allow access.
Wherobots OAuth consent screen for Claude.
Return to Claude. The Wherobots connector appears in the Web section of the Connectors page, and you can use it in your conversations.

Then verify your setup.

ChatGPT is OpenAI’s AI assistant, available as a desktop app for macOS and Windows and in the browser. In ChatGPT, custom MCP servers are added as Apps, and each user creates the Wherobots App on their own account. The same steps work on the web and in ChatGPT Desktop.

Open the Apps settings

In ChatGPT, go to Settings > Apps > Advanced settings and enable Developer mode. This allows you to add custom MCP servers as Apps.
Go back to Settings > Apps and click Create app.
Apps settings with the Create app button.

Configure the Wherobots app

In the New App form, enter:

Name: wherobots or a name of your choice (e.g. Wherobots Geospatial Assistant)
Description (optional): a short description, such as AI-assisted geospatial development with Wherobots
MCP Server URL: https://api.cloud.wherobots.com/mcp/
Authentication: OAuth

Review the warning about custom MCP servers and tick I understand and want to continue, then save the app.

ChatGPT New App form with Name, MCP Server URL, and OAuth Authentication fields — New App form configured for the Wherobots MCP Server.

Complete the OAuth flow

A new browser tab opens to the Wherobots sign-in page.
Sign in to Wherobots, select your Organization from the Organization access dropdown, and click Allow access.
Wherobots Allow screen.
Return to ChatGPT and go to Apps. Wherobots now appears under your Enabled apps with the DEV badge.
ChatGPT Apps settings with Wherobots app added.

Add the app to your conversation

To give ChatGPT the Wherobots app as context, open the + menu in the chat composer, click … More, and enable Wherobots before sending your prompt.

ChatGPT chat composer with Wherobots app enabled

Then verify your setup.

Add Agent Skills and the CLI

For Claude Code, Codex, and OpenCode. Claude and ChatGPT run in a chat app, so skip this section for them.

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.

Run the following command to install the CLI:

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

Sign in with your browser (OAuth):
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 your setup

Ask your assistant a test question:

List the catalogs in my Wherobots Organization

If everything is configured, the assistant calls a Wherobots MCP tool such as list_catalogs_tool and returns the catalogs available in your Organization.

Troubleshooting

Claude: The Wherobots connector does not appear in the Directory

On Team and Enterprise plans, connectors must be enabled at the organization level before individual users can add them. If you search the Directory and Wherobots does not appear, or the option to add it is unavailable, ask your team’s Owner or Primary Owner to enable connectors for the organization.Once connectors are enabled at the organization level, each user still completes the Claude steps and authenticates individually. See Use Connectors to extend Claude’s capabilities for details on connector permissions.

If the consent screen does not complete or Claude reports it cannot connect:

Confirm you have a stable internet connection and an active Wherobots Account.
Make sure you selected the correct Organization from the Organization access dropdown before clicking Allow access.
On the Claude Connectors page, disconnect the Wherobots connector and reconnect to restart the OAuth flow.

Claude: Claude does not call the Wherobots MCP server

If Claude answers without invoking a Wherobots tool (such as list_catalogs_tool):

Confirm the Wherobots connector is enabled on the Connectors page and toggled on for the conversation.
Start a new conversation and ask an explicitly geospatial question so Claude selects the connector, such as the test question above.

Next steps

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 from a terminal agent 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 an AI Assistant

Before you start

Connect the MCP Server

Add Agent Skills and the CLI

Verify your setup

Troubleshooting

Next steps

MCP Server Best Practices

MCP Server Demo Videos

Agent Skills

Agentic Terminal Usage

CLI Reference

MCP Server vs CLI

​Before you start

​Connect the MCP Server

​Add Agent Skills and the CLI

​Verify your setup

​Troubleshooting

​Next steps

MCP Server Best Practices

MCP Server Demo Videos

Agent Skills

Agentic Terminal Usage

CLI Reference

MCP Server vs CLI

Before you start

Connect the MCP Server

Add Agent Skills and the CLI

Verify your setup

Troubleshooting

Next steps