> ## Documentation Index
> Fetch the complete documentation index at: https://docs.universalbench.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Use with Codex

> Add UniversalBench to OpenAI Codex (CLI, IDE extension, or desktop) so your agent can run code, query your data, search the web, invoke LLMs, and manage secrets.

Codex speaks MCP and shares one configuration across its CLI, IDE extension, and desktop app. Set UniversalBench up once and it works everywhere.

## Setup

<Steps>
  <Step title="Get your personal MCP URL">
    Sign up at [universalbench.dev](https://universalbench.dev) and copy your URL from the dashboard. It looks like `https://universalbench-mcp.penantiaglobal.workers.dev/u/ubk_...`
  </Step>

  <Step title="Open MCP servers in Codex">
    In the Codex app, go to **Settings** then **MCP servers**, and click **Add server**. (In the CLI you can instead run `codex mcp add`, or edit `~/.codex/config.toml` directly.)
  </Step>

  <Step title="Fill in the form">
    * **Name:** `universalbench`
    * **Type:** select **Streamable HTTP**
    * **URL:** paste your full URL including the `/u/ubk_...` key
    * **Bearer token env var:** leave this **empty**
    * **Headers:** leave empty

    <Warning>
      Do not put your API key in the "Bearer token env var" field. That field expects the *name of an environment variable*, not a key. If you paste your key there, Codex will look for an environment variable with that name, fail to find it, and the server will not start with an error like `Environment variable ubk_... is not set`. Your key belongs only in the URL.
    </Warning>
  </Step>

  <Step title="Save and start a new thread">
    Save the server. Then **start a new Codex thread.** Tools from a newly added MCP server do not appear in a thread that was already open. The new thread loads `ub_read`, `ub_write`, and `ub_ai`.
  </Step>
</Steps>

## The three tools

| Tool       | What it does                                                                                                                                                                                                                 |
| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ub_read`  | Read-only work: read files, run read-only SQL (`db_select`, `db_query`, `db_search`), read from GitHub, check account status                                                                                                 |
| `ub_write` | Anything that changes state: run code and bash, write files, install packages, run parallel jobs, push to GitHub with validation, safe deploys, write to your database, store secrets in the vault, make outbound HTTP calls |
| `ub_ai`    | Web search and LLM calls, with cost caps on by default                                                                                                                                                                       |

## What you can do now

In a new thread, ask Codex something that needs execution:

> Use UniversalBench to run python that prints the sum of the first 1000 integers.

Codex calls `ub_write` with its `code` capability and returns the result, without dumping the work into your context.

## When to reach for UniversalBench in Codex

UniversalBench is not a replacement for Codex's local shell and file tools. For editing files and running local tests, Codex's own tools are faster. UniversalBench earns its place when you want:

* The agent to query or change **your database or GitHub** using credentials stored once in the vault, without pasting tokens
* **Validated pushes and safe deploys** with rollback
* An **isolated cloud runtime** when you do not want agent code running on your machine
* **Cost-capped LLM and web calls** for small bounded subtasks

## Troubleshooting

| Problem                                              | Fix                                                                                                           |
| :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| `Environment variable ubk_... is not set` on startup | The key is in the Bearer token field. Remove it. The key belongs only in the URL. Save and start a new thread |
| Tools do not appear in the current thread            | Start a new thread. Newly added MCP servers load on thread start                                              |
| Server connected but agent cannot find the tools     | Same fix: start a new thread                                                                                  |
| 401 or 403 errors                                    | The token after `/u/` has a typo. Paste the URL again from the dashboard                                      |