Reference guide for AI agents connecting to SwiftClip Browser Bridge
Browser Bridge is a Chrome extension that lets AI agents control a real user's browser. Unlike headless browsers or cloud solutions, it uses the user's actual Chrome session — meaning their cookies, logins, and browsing context are already available. No authentication setup needed.
The user installs the extension, generates a connection code, and shares it with you. You connect via MCP (Model Context Protocol) and can then navigate, click, type, read pages, and more — all through the user's real browser.
The user will provide you with a session ID and password. Authenticate by sending a Bearer sessionId:password header with every request to the MCP endpoint. The connection uses standard MCP protocol over HTTPS.
MCP endpoint: https://bridge.swiftclip.dev/mcp
Each session has a limited duration (1–24 hours) chosen by the user. Sessions expire automatically — you will receive an error if the session has ended.
Parameters: url (string, required)
Navigate the browser to the specified URL. Waits for the page to load before returning.
Parameters: selector (string, required)
Click on an element matching the CSS selector. If multiple elements match, clicks the first one. Use snapshot or execute_js first to identify the right selector.
Parameters: x (number, required), y (number, required)
Click at specific x,y coordinates on the page. Useful when CSS selectors can't reliably identify the target element (e.g., dynamically generated classes on SPA pages). Coordinates are in pixels from the top-left of the viewport. Use find_clickable to get precise coordinates.
Parameters: selector (string, optional), maxResults (number, optional, default 50)
Returns a list of all visible clickable elements on the page with their coordinates, text content, tag, and a suggested CSS selector. Use this before click_at to know exactly where to click.
selector — scope the search to a specific container (e.g. "nav", "#main"). Defaults to the entire page.maxResults — max elements to return. Default: 50.Parameters: selector (string, required), text (string, required)
Type text into an input field identified by the CSS selector. Clears existing content first. Works with input fields, textareas, and contenteditable elements.
Parameters: key (string, required)
Press a keyboard key. Examples: Enter, Tab, Escape, ArrowDown. Use for form submission, navigation, or keyboard shortcuts.
Parameters: direction (string: "up"|"down", required), amount (number, optional, default 3)
Scroll the page up or down by the specified number of viewport heights.
Parameters: none
Capture a screenshot of the current page viewport. Returns a base64-encoded PNG image. Use this to see what the user sees.
Parameters: stableMs (number, optional, default 1500), timeoutMs (number, optional, default 8000), maxDepth (number, optional, default 12)
Returns a simplified representation of the page's rendered DOM structure. Waits for the DOM to stabilize before capturing — uses a MutationObserver to detect when the page has finished rendering. This makes it work reliably on JavaScript-heavy sites (LinkedIn, Twitter, Gmail, etc.). The _meta.stability field indicates whether the page was "stable" or reached the "timeout".
Use this to identify elements, selectors, and page content before interacting. Much faster and more useful than raw HTML for understanding page layout.
Parameters: script (string, required)
Execute JavaScript in the page context. By default, this tool requires explicit user approval before every execution — a popup will ask the user to Allow or Deny the script. Only use this when snapshot, query_dom, get_text, and find_clickable cannot extract the information you need.
Auto-approve (Pro): Pro users can enable "Auto-approve scripts" in Settings to skip the confirmation popup for all JS executions. This is opt-in and disabled by default.
Parameters: ms (number, required)
Wait for the specified number of milliseconds. Useful after navigation or clicks that trigger animations, loading states, or dynamic content.
Parameters: selector (string, optional) OR text (string, optional), timeoutMs (number, optional, default 15000)
Wait until a specific condition is met: either a CSS selector appears in the DOM, or specific text content is found on the page. Polls every 500ms and returns immediately when the condition is satisfied. Auto-approved in Approval mode (read-only polling). Much more efficient than wait(ms) + trial-and-error.
Examples:
{"selector": ".job-card"} — wait for a job card to appear{"text": "Postuler"} — wait for the word "Postuler" on the pageParameters: none
List all open tabs in the browser window. Returns tab titles and indices. If more than 10 tabs are open, a warning is included to remind the agent to close unused tabs.
Parameters: index (number, required)
Switch to a different tab by its index. Use tabs_list first to find the right index.
Parameters: index (number, optional) OR indexes (number[], optional)
Close one or more browser tabs. Supports three modes:
{"index": 5} — close a single tab by index{"indexes": [1, 3, 5, 8]} — batch close multiple tabs in one call (more efficient than multiple single calls){} — close the current active tabUse tabs_list first to find the right indexes. Always close tabs you no longer need to keep the browser clean.
Parameters: message (string, required), buttons (string[], optional), inputPlaceholder (string, optional), timeoutMs (number, optional)
Display a popup message directly in the user's browser. Use this when you need the user to perform a manual action (click a blocked button, upload a file, solve a CAPTCHA) or when you need information from them.
message — the message to displaybuttons — custom button labels. Default: ["OK"]inputPlaceholder — if provided, shows a text input field. The user's typed response is returnedtimeoutMs — auto-dismiss after this time. 0 = no timeoutReturns: { "button": "OK", "input": "user typed text" }
Always call snapshot, screenshot, or execute_js before interacting with a page. This ensures you understand the current state and can identify the correct selectors.
snapshot waits for DOM stability and gives you the rendered structure. execute_js is the most powerful tool for extracting content from JavaScript-heavy pages — use it when snapshot doesn't capture enough. screenshot shows you what it actually looks like visually.
After navigating, use wait_for with a selector or text to wait until the page has actually loaded. This is more reliable than wait(ms) because it checks the actual page state instead of guessing timings.
JavaScript-heavy single-page apps often generate dynamic CSS classes that make click(selector) unreliable. Use this approach:
execute_js to find and identify elementsclick_at with coordinates from a screenshot if selectors failwait_for to wait for dynamic content to appearUse CSS selectors to target elements. Common patterns:
input[name="email"] — input field by namebutton[type="submit"] — submit buttona[href*="login"] — link containing "login" in href#search-box — element by ID.btn-primary — element by classPlan your actions accordingly. Use snapshot to observe before acting, rather than trial-and-error clicking.
When a site opens a new tab (popup, external redirect), close the old tab with tabs_close once you've switched to the new one. Leaving tabs open clutters the browser and can slow it down. Use batch close {"indexes": [1,2,3]} to clean up multiple tabs at once.
The extension can auto-close orphaned about:blank tabs if enabled in Settings. A warning is shown when more than 10 tabs are open.
Some sites block automated clicks (popups, CAPTCHAs, file uploads). When you detect a blockage, use ask_user to ask the user to perform the action manually, then continue. This is the hybrid approach — you drive, the user handles what you can't.
Browser Bridge operates in two modes:
execute_js to inspect the actual DOM, or try click_at with coordinates from a screenshot.stableMs or timeoutMs, or use execute_js as a fallback to read the rendered DOM directly.