Cursor Browser Tool: Let the Agent Drive a Real Browser

The agent drives a browser the way you would, and it sees what the page does. With access to console logs and network traffic, it can debug issues and run testing workflows itself. Cursor lists the specific browser actions the agent has; the table below maps each one to what it lets the agent accomplish.

The last two rows are the difference between this and a screenshot tool, and probably the reason to turn it on at all. Clicking and looking tells the agent what happened; console messages and request and response pairs are how it works out why.

Cursor also prompts the agent to notice a development server that is already running and use its port instead of starting a second one. That reads like housekeeping, and mostly it is, right up until the agent loads localhost:3000 while your rebuild is serving on 3001. If a screenshot looks wrong in a way your code cannot explain, check which port it loaded.

Which use cases does Cursor document?

Cursor's docs list five use cases, and four of them name a concrete job: accessibility audits against WCAG, automated testing, turning a design into code, and adjusting an existing UI to match a screenshot. The example prompts all open with @browser. The accessibility pass is where I would start a first run, since contrast ratios and missing alt text have right answers you can check in a minute.

Which models perform best with the browser tool?

Cursor names Sonnet 4.5, GPT-5 and Auto as the models that perform best with the browser tool. No reasoning comes with the list, so read it as a starting point rather than a rule about which models can drive the browser at all.

The browser includes a design sidebar for changing your site directly in Cursor, so you can adjust the look and keep the code in sync. Cursor groups the controls into a few categories.

• Position and layout: move elements, and change flex direction, alignment, and grid layouts.
• Dimensions: adjust width, height, padding, and margins with exact pixel values.
• Colors: apply colors from your design system or add gradients through a visual picker.
• Appearance: change shadows, opacity, and border radius with sliders.
• Theme testing: check your design in light and dark themes.

When the visual change looks right, click apply to start an agent that translates it into the matching code edits. You can also select multiple elements across the site and describe the change in text; agents run in parallel and the result appears after hot-reload.

A page that hot-reloads into the right shape is not evidence the diff is right, though, and one multi-select fans out into several agents running at once.

The dimensions controls give you exact pixel values, useful for a one-off and also the shortest route to a hardcoded number sitting where a spacing token belongs. My rule used to be to catch that in review, which is too late to be much of a rule. Name the token or the shared component in the text you send with the change, then read the diff. Colors avoid this, since the picker reads from your design system.

The click-an-element-then-prompt side of visual editing, keyboard toggle included, is covered on Design ModeA way to point at an element in Cursor's built-in browser and change it directly, instead of describing it in words. Press Enter for the full definition..

Yes. Browser state persists between agent sessions, scoped to your workspace, so a logged-in test does not start from scratch each time. Cursor documents three kinds of retained state, and isolates the context per workspace so projects keep separate cookies and storage.

• Cookies: authentication cookies and session data stay available across sessions.
• Local storage: data in localStorage and sessionStorage persists.
• IndexedDB: database content is retained between sessions.

The state that saves you a login is the same state that hands you a stale one. If your app behaves differently for someone signed out, you will not see that by default, because the browser still carries last session's cookies. Start the flow where you want it, on a signed-out route or a separate account.

The browser runs as a secure web view controlled by an MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. server that runs as an extension, and Cursor says the integration has been reviewed by multiple external security auditors. By default browser actions require your approval; you can change that in Agent Settings, and the three modes trade convenience for control.

The table names three modes and does not say which to sit on. Stay on manual approval, and for longer than feels necessary. Both settings below it trade a review step for speed on a browser that stays signed in to your app between sessions, so the thing being sped up is an authenticated session. If you do graduate to the allow list, put the handful of actions you are tired of approving on it and keep navigation off.

The clip below shows the kind of action sequence these modes govern.

What stops unauthorized access and cross-tab interference?

Underneath the approval modes sits a second layer that answers a different question. Cursor generates a random authentication token before each browser session, gives every tab a unique random id, and regenerates tokens for each new session, all of it aimed at unauthorized access and cross-tab interference. Whether a given click should have happened is still decided by the approval mode you set.

How do approval modes scale across a team?

On a small team I would leave everyone on manual approval and absorb the clicking, since the pages in play are usually your own localhost. That answer does not scale. The mode lives in each person's own Cursor Settings under Agents > Auto-RunThe Cursor Settings > Agents setting that decides which commands the agent runs automatically and which wait for your approval, via allow and block lists. Press Enter for the full definition., so fifty engineers is fifty postures until something above them narrows the range.

Cursor's pricing page lists auto-run and browser controls on the Enterprise plan. The lever this page documents is the origin allowlist in the next section, which works on a different axis. It bounds which sites the tools can run on at all, so it holds whatever each person picked in their own settings.

For enterprise customers, browser functionality is managed through Cursor's MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. controls: admins toggle availability and have granular control over each MCP server and over browser access. Two settings matter most for a controlled rollout, and the dashboard names them plainly.

• Enable browser for the team in the Settings Dashboard under MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. Configuration by toggling browser features; access then follows your MCP allow or deny lists.
• Configure a Browser Origin Allowlist that restricts which sites the agent can automatically navigate to and where MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. tools can run; this feature must be enabled for your organization by your Cursor account team before it appears.
• In the Admin Dashboard, under MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. Configuration, the labels read "Enable Browser Automation Features (v2.0+)" and "Browser Origin Allowlist (v2.1+)"; add each origin separately, for example http://localhost:3000 or https://internal.example.com.

The docs order those two steps. Follow it: confirm browser automation features are enabled, then add origins, because the allowlist restricts automatic navigation and there is nothing to restrict while the feature is off. The line that catches people sits further down, where Cursor's docs say leaving the allowlist empty allows all origins. A dashboard you enable on Friday and mean to fill in on Monday allows everything over the weekend.

When browser tools stop working mid-run, check which origin the browser is on before anything else. Once it sits outside the allowlist, click, type and navigate are blocked, and that holds even when a person navigated there by hand. Manual navigation stays allowed on purpose, which is handy for reading documentation in the pane, and it is also how a session ends up parked where the tools will not act.