# Codex CLI

Source: https://webagent-docs-staging.lookover.ai/qa-testing/codex

> Add webagent to Codex CLI as an MCP server, check the connection, and run your first smoke test.

> **Note: API address**
>
> Examples use the variable `$API_URL`. Set it once: `export API_URL=https://api.us.webagent.lookover.ai`. Webagent is in early access, so the address for your account can differ. The **API keys** page in the dashboard shows it as "API base", followed by `/v1`. Use the address without the `/v1`. Running the API on your own machine? Use `export API_URL=http://localhost:4400`. A `config.toml` cannot read variables, so the TOML block below has the address written out: swap the host if yours differs.

You need an API key ([Quickstart](/quickstart)) and Codex CLI. The `codex mcp` commands and the `config.toml` block below were checked with codex-cli 0.137.0.

## 1. Set the address and the key [#1-set-the-address-and-the-key]

```bash
export API_URL=https://api.us.webagent.lookover.ai
export WEBAGENT_API_KEY=wa_us_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Add this line to your shell profile so it is set every time you start `codex`. Codex reads the key from the variable named in the config. The key is never written to `config.toml`.

## 2. Add the server [#2-add-the-server]

One command:

```bash
codex mcp add lookover-webagent \
  --url "$API_URL/mcp" \
  --bearer-token-env-var WEBAGENT_API_KEY
```

This writes the following to `~/.codex/config.toml`. You can also add the block by hand:

```toml title="~/.codex/config.toml"
[mcp_servers.lookover-webagent]
url = "https://api.us.webagent.lookover.ai/mcp"
bearer_token_env_var = "WEBAGENT_API_KEY"
startup_timeout_sec = 20
tool_timeout_sec = 120
```

Add the two timeouts by hand: the command does not set them.

- `tool_timeout_sec = 120` matters. Codex stops waiting for a tool after 60 seconds by default. Webagent's `run_task` and `smoke_test` wait up to 90 seconds and `skill_*` tools up to 120 seconds, so the default would cut a long test off.
- `startup_timeout_sec` is how long Codex waits for the server at start. The default is 10 seconds.
- `url` is a streamable HTTP server. The webagent endpoint is `POST /mcp` and does not use SSE.

Optional: if Codex asks you to approve every tool call and you do not want that, add `default_tools_approval_mode = "approve"` to the same block. Accepted values in codex-cli 0.137.0 are `auto`, `prompt` and `approve`. Only use `approve` in a project where you are happy for the agent to open any public URL you name in your prompt.

## 3. Check the connection [#3-check-the-connection]

```bash
codex mcp list
codex mcp get lookover-webagent
```

`codex mcp list` shows the server with `enabled` and `Bearer token` as its auth:

```text
Name               Url                                    Bearer Token Env Var  Status   Auth
lookover-webagent  https://api.us.webagent.lookover.ai/mcp  WEBAGENT_API_KEY      enabled  Bearer token
```

`codex mcp get lookover-webagent` also shows the two timeouts and the approval mode, once you have set them. These commands read your config. They do not call the server. To see that it connects, start `codex` and type `/mcp`, which lists the active MCP servers and their tools.

The server should offer the 15 fixed tools (`create_session`, `run_task`, `get_task`, `smoke_test`, `get_report`, `list_sessions`, `get_session`, `stop_session`, `scrape`, `screenshot`, `pdf`, `crawl`, `list_skills`, `run_skill`, `get_skill_run`), plus one `skill_<name>` tool for each skill your workspace can run, such as `skill_smoke_uat`.

If it fails to connect:

| What you see | What it means |
|---|---|
| `401` or `invalid API key` | The key is wrong, revoked, or `WEBAGENT_API_KEY` was not set when you started `codex`. |
| `421` or `wrong_region` | The key belongs to another region. Use the API address for that region. |
| Startup timeout | Raise `startup_timeout_sec`, and check the API address. |

## 4. Run a first smoke test [#4-run-a-first-smoke-test]

First install the [agent setup snippet](/qa-testing/agent-setup) in your `AGENTS.md`. Then try the Test Arena, a fake site meant for this:

```text
Use the webagent tools. Smoke test https://webagent-test-web.pages.dev/app/login:
sign in with the email qa@example.com and the password arena-pass. After signing in,
the text "Welcome" must be on the page. Give me the verdict, the failed steps, the
console errors and the report link.
```

You can also run it without the interactive screen:

```bash
codex exec "Use the webagent tools. Smoke test https://webagent-test-web.pages.dev/app/login: sign in with the email qa@example.com and the password arena-pass. After signing in, the text Welcome must be on the page. Give me the verdict, the failed steps, the console errors and the report link."
```

In `exec` mode nobody can answer an approval prompt, so set `default_tools_approval_mode = "approve"` as shown above, or the call may wait for approval.

Codex calls `smoke_test` once. You can watch the browser in the dashboard under **Sessions** while it runs.

The tool result starts with a summary like this (the text of a real `smoke_test` call):

```text
Smoke test of https://webagent-test-web.pages.dev/app/login PASSED in 1 s: 13 of 15 steps passed. No console errors or failed network calls.
Full HTML report (short-lived link): https://...
The whole report is in structuredContent.
```

If the test is not done after the wait, the verdict is `running`, and Codex calls `get_report` with the `id` until it ends. That is normal, not an error. A test that ran and failed is a normal result: `isError` is set only when the test could not run. For an open-ended goal, ask for a task: Codex calls `run_task`, and `get_report` with the task id for the report.

[Recipes](/qa-testing/recipes) has more prompts. [Reading results](/qa-testing/reading-results) explains what each field means.

## Remove the server [#remove-the-server]

```bash
codex mcp remove lookover-webagent
```