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

> Configure the Wherobots MCP Server, Agent Skills, and CLI in OpenAI Codex — in the desktop app or terminal — for AI-assisted geospatial development.

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

[**Codex**](https://developers.openai.com/codex) is OpenAI's agentic coding tool, available as both a [terminal CLI](https://developers.openai.com/codex/cli) and a [native desktop app](https://developers.openai.com/codex/app).

Unlike the VS Code extension flow, Codex requires separate installation of the MCP Server, Agent Skills, and CLI.

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

* Either 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) installed.
* A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account).
* An API key for the Wherobots CLI. For more information, see [API Keys](/get-started/wherobots-cloud/api-keys).
* [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`).

## Install and configure

<Steps>
  <Step title="Configure the MCP Server">
    Codex stores MCP server entries in `~/.codex/config.toml`.

    The Codex CLI and the Codex desktop app share the same config file, so the following steps apply to both interfaces:

    1. Open `~/.codex/config.toml` in your editor (create the file if it does not exist):

           <Note>
             Remote HTTP servers like Wherobots must be added by editing this file directly — `codex mcp add` only supports local stdio servers.
           </Note>

       * Add a `[mcp_servers.<YOUR_SERVER_NAME>]` section.

       * Replace `<YOUR_SERVER_NAME>` with your preferred name for the Wherobots MCP server (e.g. `wherobots-mcp-server`):

         ```toml theme={"system"}
         [mcp_servers.<YOUR_SERVER_NAME>]
         url = "https://api.cloud.wherobots.com/mcp/"
         ```

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

       ```shell theme={"system"}
       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, the terminal will display a URL you can copy and paste into any browser to complete the login.

    3. Restart Codex so it picks up the new MCP server.

    <Accordion title="Alternative: Use an API key instead of OAuth">
      Skip `codex mcp login` and add an `X-API-Key` header to the server entry:

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

    <Info>
      For more information on downloading, installing, and using Codex, see the [Codex documentation](https://developers.openai.com/codex/cli).
    </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

To confirm the installation, ask a question in Codex:

```text wrap theme={"system"}
List the catalogs in my Wherobots Data Hub
```

If configured correctly, Codex will call the Wherobots MCP server and return the catalogs available in your [Wherobots Data Hub](https://cloud.wherobots.com/data-hub).

Additionally, you can verify that the Agent Skills were installed correctly, if the **Wherobots MCP Server** is listed as a **Source** within Codex as it processes your query.

<Frame caption="Verifying Wherobots MCP Server as a source in Codex">
  <img src="https://mintcdn.com/wherobots/jep6hunnoEJVIVgn/develop/agentic-tools/images/codex-source.png?fit=max&auto=format&n=jep6hunnoEJVIVgn&q=85&s=2133a75fc18fca60efca7097616a0ed0" alt="Codex agentic verify" width="2932" height="636" data-path="develop/agentic-tools/images/codex-source.png" />
</Frame>

## Next steps

<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 Codex 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>