Codex CLI
Add webagent to Codex CLI as an MCP server, check the connection, and run your first smoke test.
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) 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
export API_URL=https://api.us.webagent.lookover.ai
export WEBAGENT_API_KEY=wa_us_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAdd 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
One command:
codex mcp add lookover-webagent \
--url "$API_URL/mcp" \
--bearer-token-env-var WEBAGENT_API_KEYThis writes the following to ~/.codex/config.toml. You can also add the block by hand:
[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 = 120Add the two timeouts by hand: the command does not set them.
tool_timeout_sec = 120matters. Codex stops waiting for a tool after 60 seconds by default. Webagent'srun_taskandsmoke_testwait up to 90 seconds andskill_*tools up to 120 seconds, so the default would cut a long test off.startup_timeout_secis how long Codex waits for the server at start. The default is 10 seconds.urlis a streamable HTTP server. The webagent endpoint isPOST /mcpand 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
codex mcp list
codex mcp get lookover-webagentcodex mcp list shows the server with enabled and Bearer token as its auth:
Name Url Bearer Token Env Var Status Auth
lookover-webagent https://api.us.webagent.lookover.ai/mcp WEBAGENT_API_KEY enabled Bearer tokencodex 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
First install the agent setup snippet in your AGENTS.md. Then try the Test Arena, a fake site meant for this:
Use the webagent tools. Smoke test https://webagent-test-web.pages.dev/app/login:
sign in with the email [email protected] 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:
codex exec "Use the webagent tools. Smoke test https://webagent-test-web.pages.dev/app/login: sign in with the email [email protected] 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):
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 has more prompts. Reading results explains what each field means.
Remove the server
codex mcp remove lookover-webagent