Connect your editor

After npx @unotest/web init (or @unotest/mobile install), the MCP server is wired for you. This page is what’s happening under the hood — and how to wire it by hand if needed.

What init writes

• .mcp.json — the MCP server entry (stdio transport).
• Editor settings (e.g. .claude/settings.json) — the tool allowlist + an agent authoring guide.

Claude Code

init writes .mcp.json at the project root, which Claude Code auto-discovers. The server is launched as npx @unotest/web mcp (stdio). Open Claude Code in the project and ask it to write a test.

Cursor / Codex

Both read MCP server config from their settings. init populates it. If you wire it manually, point the server command at npx @unotest/web (web) or npx @unotest/mobile (iOS) — running with no subcommand starts the MCP server.

Picking an environment

The server reads UNOTEST_ENV at startup to select the unotest/.env.<name> / unotest/.secrets.<name> overlays (see Variables & secrets). Add it to the server’s env block in .mcp.json and reload the editor to switch:

{
  "mcpServers": {
    "unotest-web": {
      "command": "npx",
      "args": ["-y", "@unotest/web", "mcp"],
      "env": { "UNOTEST_ENV": "dev" }
    }
  }
}

There is no per-call switch — explore_start / run_test replies report the active environment under environment, so the agent always sees what a session resolves against.

Intent locators and the Picker

An intent locator names what an element means — “the checkout button” — rather than where it sits. Resolving one takes a model that reads the page, and that model is the Picker. Nothing else needs it: snapshots, find_element and the locators you write by hand work with no model at all, and a scenario that was written with an intent locator carries a plain locator from then on.

A server with a grounder configured has one more tool, ground_element, and intent locators start resolving inside explore_step and find_element. The three keys it reads are:

UNOTEST_GROUNDER_MODE=remote          # unotest/.env
UNOTEST_GROUNDER_REMOTE_URL=...       # unotest/.env
UNOTEST_GROUNDER_REMOTE_TOKEN=...     # unotest/.secrets

box picker on writes all three for a box that has a Picker. UNOTEST_GROUNDER_MODE=local points the same path at a model server of your own instead.

Reload the editor after turning it on. These are read once, when the server starts — a server that came up without them announced a tool list with no ground_element in it, and from the editor that is indistinguishable from a Picker that does not work. explore_start reports what the session actually resolved, under grounder: {available, reason?, hint?}.

Monorepos

Open your editor at the monorepo root and run init there, so .mcp.json lives where the editor looks for it.

Verify

Ask the agent to “write an e2e test for sign-in”. If the MCP tools are available, it will explore your app and produce a scenario. If not, re-run init and reload the editor.