> ## 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 an AI Assistant > Connect the Wherobots MCP Server to Claude Code, Codex, OpenCode, Claude, or ChatGPT, and add Agent Skills and the CLI to terminal agents. Public Preview Every AI assistant on this page connects to the same [Wherobots MCP Server](https://docs.wherobots.com/develop/mcp/mcp-server-overview.md), 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](https://docs.wherobots.com/develop/agent-skills.md) and the [Wherobots CLI](https://docs.wherobots.com/develop/cli.md). 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](https://docs.wherobots.com/develop/agentic-tools.md#what-each-component-does). To use Wherobots in VS Code or another Code OSS editor instead, see [Set Up Wherobots in Your Editor](https://docs.wherobots.com/develop/agentic-tools/editors.md). ## Before you start You need: * A **Wherobots Account**. See [Create a Wherobots Account](https://docs.wherobots.com/get-started/wherobots-cloud/create-account.md). * 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](https://docs.wherobots.com/get-started/wherobots-cloud/api-keys.md) instead. * Your AI assistant: | Assistant | Requirements | | - | - | | **Claude Code** | [Claude Code](https://code.claude.com/) installed. | | **Codex** | The [Codex CLI](https://developers.openai.com/codex/cli), run in a modern terminal emulator, or the [Codex desktop app](https://developers.openai.com/codex/app). | | **OpenCode** | [OpenCode](https://opencode.ai/), the terminal agent with a [modern terminal emulator](https://opencode.ai/docs/#prerequisites) or the desktop app. | | **Claude (desktop and web)** | A [Claude](https://claude.ai) account with an active paid [subscription](https://www.anthropic.com/pricing), and [Claude Desktop](https://claude.ai/download) 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](https://chatgpt.com) account with an active paid plan (Plus, Pro, Business, or Enterprise), and [ChatGPT Desktop](https://chatgpt.com/download) for the desktop flow. | For the terminal agents, you also need [Node.js](https://nodejs.org/) with npm to install Agent Skills with `npx`. ## Connect the MCP Server Choose your assistant. **Claude Code** [Claude Code](https://code.claude.com/docs/en/overview) is Anthropic's terminal-based agentic tool. **1. Add the MCP server** In a terminal, run the following command, replacing the placeholder with your preferred server name: ```shell theme={"system"} claude mcp add --transport http 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](https://code.claude.com/docs/en/mcp#scope-hierarchy-and-precedence). 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](https://docs.wherobots.com/get-started/wherobots-cloud/api-keys.md): > > ```shell theme={"system"} > claude mcp add --transport http https://api.cloud.wherobots.com/mcp/ --scope user --header "x-api-key: " > ``` **2. Restart Claude Code** Restart Claude Code after adding the server. Then [add Agent Skills and the CLI](#add-agent-skills-and-the-cli). For more information on installing and using Claude Code, see the [Claude Code overview](https://code.claude.com/docs/en/overview) and [Quickstart](https://code.claude.com/docs/en/quickstart). **Codex** [Codex](https://developers.openai.com/codex) is OpenAI's agentic coding tool, available as a [terminal CLI](https://developers.openai.com/codex/cli) and a [desktop app](https://developers.openai.com/codex/app). Both read MCP server entries from the same `~/.codex/config.toml` file, so these steps apply to both. **1. Add the MCP server** In a terminal, run the following command, replacing `` with your preferred name (e.g. `wherobots-mcp-server`): ```shell theme={"system"} codex mcp add --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: > > ```toml theme={"system"} > [mcp_servers.] > 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](https://docs.wherobots.com/get-started/wherobots-cloud/api-keys.md) to the server entry in `~/.codex/config.toml`: > > ```toml theme={"system"} > [mcp_servers.] > url = "https://api.cloud.wherobots.com/mcp/" > http_headers = { "X-API-Key" = "" } > ``` **2. Sign in with OAuth** Start the OAuth flow: ```shell theme={"system"} codex mcp login ``` 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. **3. Restart Codex** Restart Codex so it picks up the new MCP server. Then [add Agent Skills and the CLI](#add-agent-skills-and-the-cli). When you [verify your setup](#verify-your-setup), Codex lists the **Wherobots MCP Server** as a **Source** while it processes your query. ![Codex agentic verify](https://mintcdn.com/wherobots/jep6hunnoEJVIVgn/develop/agentic-tools/images/codex-source.png?fit=max\&auto=format\&n=jep6hunnoEJVIVgn\&q=85\&s=2133a75fc18fca60efca7097616a0ed0) Verifying Wherobots MCP Server as a source in Codex For more information on installing and using Codex, see the [Codex documentation](https://developers.openai.com/codex/cli). **OpenCode** [OpenCode](https://opencode.ai/) is an open-source agentic coding tool for the terminal and desktop. These steps work for both. For more information, see the [OpenCode documentation](https://opencode.ai/docs/). **1. Add the MCP server** In your terminal, start the OpenCode MCP setup wizard: ```bash theme={"system"} 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](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/opencode-mcp-add-wizard.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=756b9b8e53108c422003ad0f29de8504) 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: > > ```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": {} > } > } > } > ``` > **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](https://docs.wherobots.com/get-started/wherobots-cloud/api-keys.md). Then skip the OAuth step. > > ```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": false, > "headers": { > "x-api-key": "" > } > } > } > } > ``` **2. Sign in with OAuth** Authenticate the new server, replacing `` with the name you chose: ```bash theme={"system"} opencode mcp auth ``` 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](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/opencode-oauth-consent.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=911365bdfe4058016ab6ca65500bb90d) 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](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/opencode-oauth-success.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=153f23d8c67696e8614dce9474c5c615) Authorization Successful confirmation page. **3. Confirm the server is connected** Run: ```bash theme={"system"} opencode mcp list ``` You should see `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) ``` Then [add Agent Skills and the CLI](#add-agent-skills-and-the-cli). **Claude (desktop and web)** [Claude](https://claude.ai) is Anthropic's AI assistant, available as a [desktop app](https://claude.ai/download) 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. > [!NOTE] > > 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](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities#h_bbcedba6ca). **1. Open Connectors in Claude** * **Web:** Go to [https://claude.ai/directory](https://claude.ai/directory). ![](https://mintcdn.com/wherobots/1ufYnZKbUKooC-ox/develop/agentic-tools/images/claude-directory-wherobots-connector.png?fit=max\&auto=format\&n=1ufYnZKbUKooC-ox\&q=85\&s=9ff4b4697332bdae311a59dd5bf0b837) * **Desktop:** Open **Customize > Connectors > Browse** from the left sidebar. **2. Enable the Wherobots connector** 1. In the **Directory** modal, search for `wherobots`. ![](https://mintcdn.com/wherobots/yxh_cgunQ9YvqePl/develop/agentic-tools/images/claude-directory.png?fit=max\&auto=format\&n=yxh_cgunQ9YvqePl\&q=85\&s=0f24fa7266b6e716526a81cd60790f12) 2. Select the official **Wherobots Spatial AI Assistant**. 3. Click **+** to enable the Connector in your Claude Organization. **3. Complete OAuth** 1. A new browser tab opens to the Wherobots sign-in page. 2. Sign in to Wherobots, select your Organization from the **Organization access** dropdown, and click **Allow access**. ![Wherobots OAuth consent screen prompting Claude access for the selected Organization](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/claude-grant-access.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=4f31edc3256a5c85a578456c452e5561) Wherobots OAuth consent screen for Claude. 3. 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](#verify-your-setup). **ChatGPT** [ChatGPT](https://chatgpt.com/) is OpenAI's AI assistant, available as a [desktop app](https://chatgpt.com/download) 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. **1. Open the Apps settings** 1. In ChatGPT, go to [**Settings > Apps > Advanced settings**](https://chatgpt.com/#settings/Connectors/Advanced) and enable **Developer mode**. This allows you to add custom MCP servers as Apps. ![ChatGPT Developer mode toggle in Advanced settings](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/chatgpt-developer-mode.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=60b68f8cce75b9688377189dad2dc053) 2. Go back to [**Settings > Apps**](https://chatgpt.com/#settings/Connectors) and click **Create app**. ![ChatGPT Apps settings page with the Create app button visible](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/chatgpt-apps-create.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=296e55c1b94ed3977bda8964d2009499) Apps settings with the Create app button. **2. 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](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/chatgpt-new-app-form.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=44b919e922017d3d8dc796b549648a0b) New App form configured for the Wherobots MCP Server. **3. Complete the OAuth flow** 1. A new browser tab opens to the Wherobots sign-in page. 2. Sign in to Wherobots, select your Organization from the **Organization access** dropdown, and click **Allow access**. ![Wherobots Allow screen](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/chatgpt-allow-screen.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=408b55c9ae59d97ce01529c2613acf71) Wherobots Allow screen. 3. Return to ChatGPT and go to [**Apps**](https://chatgpt.com/#settings/Connectors). **Wherobots** now appears under your **Enabled apps** with the `DEV` badge. ![ChatGPT Apps settings page with Wherobots app listed](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/chatgpt-enabled-app.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=d7330af6ca472479c50916f3099d81b1) ChatGPT Apps settings with Wherobots app added. **4. 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](https://mintcdn.com/wherobots/-xg1VXa7MjWQmfwe/develop/agentic-tools/images/chatgpt-add-wherobots-app.png?fit=max\&auto=format\&n=-xg1VXa7MjWQmfwe\&q=85\&s=d633bb892d81ad2a42f635cd5cdae650) Then [verify your setup](#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. **1. Install Agent Skills** [Agent Skills](https://docs.wherobots.com/develop/agent-skills.md) give your AI assistant structured context about Wherobots workflows, APIs, and best practices. ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` **2. Install the CLI (optional)** The [Wherobots CLI](https://docs.wherobots.com/develop/cli.md) wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. 1. Run the following command to install the CLI: ```bash theme={"system"} curl -fsSL https://raw.githubusercontent.com/wherobots/wherobots-cli/main/scripts/install-release.sh | bash ``` 2. Sign in with your browser (OAuth): ```bash theme={"system"} wherobots auth login ``` Confirm that the code in the browser matches the one printed in the terminal, select your Organization, and authorize the CLI. > [!TIP] > > For scripts and other non-interactive use, set an API key instead with `export WHEROBOTS_API_KEY=''`. See [Configure authentication](https://docs.wherobots.com/develop/cli.md#configure-authentication). 3. Verify the connection: ```bash theme={"system"} wherobots --tree ``` ## Verify your setup Ask your assistant a test question: ```text wrap theme={"system"} 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](#claude-desktop-and-web) steps and authenticates individually. See [Use Connectors to extend Claude's capabilities](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities#h_bbcedba6ca) for details on connector permissions. > **Claude: Sign-in or OAuth fails** > > 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](https://docs.wherobots.com/develop/mcp/mcp-server-usage.md)** > > Common tasks, example prompts, and cost considerations for the MCP Server. > **[MCP Server Demo Videos](https://docs.wherobots.com/develop/mcp/mcp-server-overview.md#watch-a-10-minute-demo)** > > Watch the MCP Server automate catalog discovery, spatial queries, and notebook generation. > **[Agent Skills](https://docs.wherobots.com/develop/agent-skills.md)** > > Learn more about available skills and installation options. > **[Agentic Terminal Usage](https://docs.wherobots.com/develop/cli.md#use-the-cli-from-an-agentic-terminal)** > > Use the CLI from a terminal agent for natural language job management. > **[CLI Reference](https://docs.wherobots.com/develop/cli.md)** > > Submit jobs, stream logs, and access the full Wherobots API. > **[MCP Server vs CLI](https://docs.wherobots.com/develop/agentic-tools.md#mcp-server-or-cli)** > > Understand when to use the MCP Server vs. the CLI. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.