The Ui.Vision MCP server (the MCP bridge) connects MCP-compatible AI assistants to the Ui.Vision browser extension. Once connected, the AI agent can list, create, edit and run macros in your real browser: it inspects the live page, writes the macro, runs it, reads the logs and helps fix failures. You keep a macro to inspect, edit and run again. It is the same toolset the built-in AI chat assistant uses, driven from the outside.
The bridge and macro execution run locally. The bridge is a small Node.js process listening on
127.0.0.1. Your AI assistant uses the provider you choose: hosted AI processes the chat content and any
included page data, macro code, logs or screenshots sent to it. A local model keeps that AI processing on your machine;
websites and other network services used by a macro still make their normal network requests.
Install the Ui.Vision extension, Node.js 18+ and the MCP bridge, then connect your MCP client. The features described here are part of Ui.Vision V10. New macros use the uiv.* JavaScript API; classic command tables remain supported.
Browser Vision works on Chrome and Edge without XModules, including when the browser window is in the background. This browser input mode is not supported in Firefox. Desktop automation and local file access require XModules; v10 requires Version 2. Check XModule pricing and features for your workflow.
Ui.Vision works with an installed browser and, for desktop tasks, your desktop session. If your task is served directly by an API or a headless browser test runner, assess those options too. Finding this page does not connect an assistant to your browser: complete the setup below first.
Video: Local LLM creates and runs a Ui.Vision macro via the MCP bridge.
npx uivision-mcp-bridge --setupPackage: uivision-mcp-bridge on npm
/mcp afterwards to confirm that uivision is
listed.
Add or update the Ui.Vision server entry in ~/.codex/config.toml:
[mcp_servers.uivision] command = "npx" args = ["-y", "uivision-mcp-bridge"] tool_timeout_sec = 900
The 900-second timeout allows long demos, including five minutes of Flappy Bird plus setup and verification.
The bridge already allows 15 minutes for run_macro; the MCP client's timeout must also cover the run.
Reload the MCP connection after changing the setting: an existing connection keeps its previous timeout.
Why no token? The browser stamps every WebSocket connection with the extension's origin, and web pages cannot forge it — so the bridge can tell the real Ui.Vision extension apart from anything else on your machine without a shared secret. You only need the fallback token from step 2 in the rare case that Test asks for it: an older bridge, or a connection that arrives without an origin. Paste it into the token field under Settings > AI and click Test again.
That is the whole setup. Now, in any Claude Code chat: "Build a Ui.Vision macro that logs into our intranet and downloads yesterday's report — then run it." The agent builds the macro from the live page, runs it in your browser and fixes it until it passes.
Only if Test asks for one. It is stored in .uivision_mcp_token in your home
directory — type "%USERPROFILE%\.uivision_mcp_token" on Windows, cat ~/.uivision_mcp_token on
macOS/Linux. Re-running npx uivision-mcp-bridge --setup prints it again. Or simply ask the AI: while the
extension is unpaired, every bridge tool call returns the token value, so the agent can show it to you in chat.
The installer only knows the clients listed above. For anything else — or if you prefer to edit the config yourself — add this entry to your client's MCP configuration file:
{
"mcpServers": {
"uivision": { "command": "npx", "args": ["-y", "uivision-mcp-bridge"] }
}
}
VS Code nests the same entry under "servers" instead of "mcpServers". Restart the client afterwards.
The extension has a Copy the JSON config button under
Settings > AI > MCP bridge that puts exactly this on your clipboard.
If you are an AI agent setting up or driving the bridge, follow these rules instead of improvising:
uivision tools in your session? The bridge is not registered, or the MCP client was not
restarted after registration — servers load only at startup. Tell the user to run
npx uivision-mcp-bridge --setup and restart the client, then stop. Do not silently fall back to
writing macro files to disk in another format.claude CLI is not on PATH in the desktop app,
the VS Code extension, Cursor or Windsurf, and MCP config files are often sandboxed against edits. Do not try to
hand-edit ~/.claude.json or any other client config. Give the user the one-line installer above, tell them a
full restart is required, and stop there.bridge_status says the extension is not connected? Walk the user through step 3 above:
open the side panel, enable Settings > AI > MCP bridge, click Test — no token needed on
current browsers. Only if Test reports a token is required, show them the fallback token value: it is included verbatim in
the tool result, so you do not need to read ~/.uivision_mcp_token.get_authoring_guide. If the bridge is not reachable,
the identical content — including the complete uiv.* JavaScript API — is at
ui.vision/ai/ai-system-prompt. Prefer uiv.* JS script macros over the
classic command table.
open_panel tool
opens the Ui.Vision app in a tab over it — even when the browser sits in the tray with zero windows (a window is
created). If the browser is not running at all, the AI starts it from its own shell and then calls
open_panel — a macro run can begin with the browser fully closed. The extension itself never pops up
any UI: reopening is always an explicit agent action, visible in the panel (banner) and recorded in the Logs tab as
"[Claude bridge] panel reopen trace". Closing the panel by hand pauses the AI's access until an agent
explicitly asks for it back (or you reopen it).chrome#1, chrome#2,
firefox#1, … The label shows in the extension's panel footer (MCP: chrome#1) and in
Settings > AI, so you always know which browser is which. The AI's tool calls go to
the most recently connected browser; the select_browser tool switches — "run this in Firefox
too" is all it takes. bridge_status lists every connected browser and marks the active one.
(Bridges before 1.4 hold a single connection — there, enable the bridge in only one browser.)--port (and in Settings > AI) if it collides with something else.127.0.0.1 only — nothing is reachable
from the network. Connections authenticate by origin: the browser stamps the handshake with the extension's
origin and web content cannot forge it, so the bridge admits the real Ui.Vision extension and rejects any web
page that tries to reach 127.0.0.1 outright. (A connected client can only receive the AI's tool
calls, never issue them, so a page could do nothing useful even if it got in.) Connections that arrive without an
origin — a non-browser local client — still authenticate with the shared token within 5 seconds, and the
token file is created with owner-only permissions.
The bridge exposes the extension's macro tools to the agent: list/open/create/edit/delete (AI folder only) macros, run the
macro in the editor and get the full execution log back, inspect the current page structure with ready-to-use locators,
take screenshots, capture element images for visual automation, and read the authoring guide (the same
system prompt that powers the built-in assistant). JavaScript macros are the preferred
format — the agent gets the full uiv.* scripting API documentation via the bridge's
get_authoring_guide tool, and the same text is published at
ui.vision/ai/ai-system-prompt.
...then please post in the forum or contact us.