Skip to main content

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.

Public Preview Draft
These instructions are a preliminary adaptation of Codex’s Model Context Protocol Documentation. As such this page has been labeled as a Draft.We are actively testing and refining the Codex integration, and will update this documentation as we learn more. Should you have any questions, feedback, or suggestions, please reach out to the Wherobots team at support@wherobots.com.
Codex is OpenAI’s agentic coding tool, available as both a terminal CLI and a native desktop 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:
Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution.
Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors.
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.
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.
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.
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.
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:
  • Either the Codex CLI (run in a modern terminal emulator) or the Codex desktop app installed.
  • A Wherobots Account within a Professional or Enterprise Organization. See Create a Wherobots Account.
  • An API key for the Wherobots CLI. For more information, see API Keys.
  • Node.js and npm installed on your system (required for installing Agent Skills via npx).

​
Install and configure

1

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 steps below apply to both.
  1. Open ~/.codex/config.toml in your editor (create the file if it does not exist):
    Remote HTTP servers like Wherobots must be added by editing this file directly — codex mcp add only supports local stdio servers.
    • 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): 
      [mcp_servers.<YOUR_SERVER_NAME>]
url = "https://api.cloud.wherobots.com/mcp/"
  2. Save the file, then 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.
  3. Restart Codex so it picks up the new server.
Skip codex mcp login and add an X-API-Key header to the server entry:
[mcp_servers.<YOUR_SERVER_NAME>]
url = "https://api.cloud.wherobots.com/mcp/"
http_headers = { "X-API-Key" = "<YOUR_WHEROBOTS_API_KEY>" }
For more information on downloading, installing, and using Codex, see the Codex documentation.
2

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
3

Install the CLI (optional)

The Wherobots CLI wraps the full Wherobots API into a single binary for job submission, log streaming, and automation.
gh repo clone wherobots/wbc-cli && cd wbc-cli && ./scripts/install-release.sh
Set your API key as an environment variable:
export WHEROBOTS_API_KEY='<your-api-key>'
Verify the connection:
wherobots api --tree

​
Verify installation

Ask a question in Codex: 
Use the Wherobots MCP server to show me the data tables in my Wherobots Organization
If configured correctly, Codex will call the Wherobots MCP server and return the data tables available in your Organization.

​
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 with Codex 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.