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 the browser's own origin authenticates the pairing — on current
Chrome, Edge and Firefox no pairing token is needed (bridge 1.7+). No macro data goes anywhere except
to the AI you are chatting with.
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.
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.