The Ui.Vision MCP bridge connects Claude Code — or any MCP client — to the Ui.Vision browser extension. Once paired, 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 iterates until the macro works. It is the same toolset the built-in AI chat assistant uses, driven from the outside.
Everything runs locally: the bridge is a small Node.js process listening on 127.0.0.1 only, the extension
connects out to it from the side panel, and a shared token authenticates the pairing. No macro data goes anywhere except
to the AI you are chatting with.
npx uivision-mcp-bridge --setupIt registers Ui.Vision with every MCP client it finds on the machine — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code — and then prints your pairing token. Copy that token; you need it in step 3.
/mcp afterwards to confirm that uivision is
listed.
Developer and test browsers skip the token. If you run Ui.Vision as an unpacked extension or in Firefox Developer Edition, just switch the bridge on and keep the panel open — leave the token field empty. The bridge accepts a developer/test browser without one, and Settings > AI shows a green "no pairing token needed" note when this applies. Regular, store-installed browsers still require the token from step 2 — it is what stops another local app from hijacking an end user's bridge, which a hands-on developer setup does not need.
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.
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? The tool result already contains the
pairing token value — show it to the user verbatim in chat and walk them through step 3 above. You do not need to
read ~/.uivision_mcp_token; the value in the tool result is authoritative.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, connections from a
store-installed browser must present the token within 5 seconds, and the token file is created with owner-only
permissions. Treat the token like a password for your browser automation. (Developer/test browsers — unpacked
extensions, Firefox Developer Edition — connect without a token: that is already a hands-on developer setup, and
the token exists only to keep another local app from hijacking an end user's bridge.)
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.