Codex browser testing with MCP

Connect Codex to Monito's local MCP server, test deployed or localhost URLs, and resume browser runs to inspect verdicts and screenshots.

Coding agents · Checked 2026-10-23

Use the local MCP configuration documented for Codex to test a change from your workspace. It shares your CLI login and can reach your running dev server.

How it works

  1. Codex starts the configured local MCP process and calls check with your URL and expectation.
  2. Monito runs the browser in the cloud, using a tunnel for HTTP localhost. Codex resumes waits with wait_for_run.
  3. Codex reads get_run and get_screenshot for the verdict and evidence, and gives you the report link.

Set it up

Browser checks use credits without a subscription requirement. OAuth and CLI browser sign-in do not require an API key. Creating API keys, CI bindings or deploy webhooks requires Pro or Team. Plan details

  1. Run npx -y @monitodev/cli auth login once to sign in through your browser.
  2. Add the configuration below to ~/.codex/config.toml. The max-wait value leaves room inside the client tool timeout.
  3. Ask Codex to check a deployed URL or your HTTP localhost app. Keep the local MCP process and dev server running for local checks.
~/.codex/config.toml · toml
[mcp_servers.monito]
command = "npx"
args = ["-y", "@monitodev/cli", "mcp", "--max-wait", "45", "--toolsets", "check,core"]
tool_timeout_sec = 60

The guide's local Codex configuration with check,core enabled so CLI 4.8.1 includes get_screenshot. That toolset also permits creating and changing scenarios.

Follow the verdict to the evidence

Call check with url and expectation, for example your deployed cart URL and "The total includes shipping". Keep projectId stable for previews whose hostname changes.

When done is false, call wait_for_run with the returned runId. Do not launch another check just to keep waiting. Reuse requestId after an uncertain launch response to avoid another charge.

Call get_run with runId to read the verdict, bug reports, failed requests, console messages and screenshot names. Then call get_screenshot with run.sessionId and a fileName from evidence.screenshots, not a screenshot URL.

After a fix, call check again. Use save_check with checkId and a name to keep a deployed check as a test; add its automation separately.

Default tools and the local server

The default tools are check, save_check, get_run, get_screenshot, wait_for_run, list_projects, list_scenarios, list_runs, run_scenario, and run_project.

In CLI 4.8.1, the local server's check,core-read default has seven tools and leaves out list_runs, run_project, and get_screenshot. Pass --toolsets check,core to include them; that also adds the rest of the core toolset, including tools that create and change scenarios. The hosted server includes all three by default.

Default tools and the local server · bash
npx -y @monitodev/cli auth login
npx -y @monitodev/cli mcp --toolsets check,core

Use this command as your client's local server to include screenshot access on CLI 4.8.1. Sign in once before starting it. Keep both the MCP server and your dev server running for localhost checks.

Example result

Example result: field names from the CLI, values illustrative

These verdict fields come from CLI 4.8.1 check --json. This illustrative failure describes a cart total that omits shipping. Timing and billing values are left null in this example. Use the returned reportUrl for the actual evidence.

Illustrative result · JSON
{
  "checkId": "check_example",
  "projectId": "project_example",
  "runId": "run_example",
  "done": true,
  "status": "failed",
  "cause": "product_defect",
  "causeLabel": "App bug",
  "durationMs": null,
  "creditsCharged": null,
  "reportUrl": "https://www.monito.dev/session/session_example",
  "firstFailure": "The cart total does not include shipping."
}

Limits to account for

The hosted server at https://www.monito.dev/api/mcp tests deployed URLs. It rejects localhost and private-network URLs. The local server, npx -y @monitodev/cli mcp, reaches HTTP localhost through a tunnel; the browser still runs in the cloud.

Local checks have no saved logins or request headers. They cannot be scheduled or added to suites, automations or status pages, even after saving.

A failed run reports a bug. An error is not a verdict about your app. Read the evidence before asking your agent to change code.

Comparable benchmark runs

Our team published these runs in the reliability benchmark. They show comparable browser journeys, not executions of the configuration or illustrative result above. Run your own scenario before relying on this integration.

Benchmark method and limits

Read the full guide

All integrations