Cursor Browser Tool: Let the Agent Drive a Real Browser

The agent uses the browser the way you would: it opens pages, clicks, types and scrolls. It also reads what the page reports back, from console messages to network requests, so it can debug a problem or run a test flow itself.

The last two rows are what a screenshot tool lacks. Clicking and looking tell the agent what happened. Console messages and request and response pairs tell it why.

Cursor also prompts the agent to find a development server that is already running and use its port, instead of starting a second one. If a screenshot shows something your code can't explain, check which port the agent loaded. An agent reading localhost:3000 while your rebuild serves on 3001 is looking at the old build.

Which use cases does Cursor document?

Cursor's docs list five use cases. Four name a concrete job: accessibility audits against WCAG, automated testing, turning a design into code, and adjusting an existing UI to match a screenshot. Their example prompts all open with @browser. For a first run, we suggest the accessibility audit: contrast ratios and missing alt text have right answers you can check in a minute.

Which models perform best with the Browser tool?

Cursor recommends Sonnet 4.5, GPT-5 and Auto for the best performance with the Browser tool. The docs give no reason and don't rule out other models, so treat the list as a starting point. None of the three is available on Plus, which has no Auto or third-party models.

Cursor's current Browser docs don't describe the design sidebar, and they don't say whether it was removed. For point-and-edit work, Cursor now documents 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., where you click an element in the running app and prompt the agent about it.

Version 2.2 added the sidebar so you can change your site's look inside Cursor and keep the code in sync. Cursor's earlier Browser docs sorted its controls into five groups.

If your version still has the sidebar, click apply when a visual change looks right, and an agent turns it into the matching code edits. You can also select several elements across the site and describe the change in text. Agents then run in parallel, and the result appears after hot-reload.

Read the diffs those agents write. A page that hot-reloads into the right shape doesn't prove the code is right, and one multi-select starts several agents at once. Exact pixel values also make it easy to put a hardcoded number where a spacing token belongs. Name the token or the shared component in the text you send with the change.

Yes. Browser state persists between agent sessions, so a logged-in test doesn't start from scratch each time. Cursor isolates that state per workspace, so each project keeps its own cookies and storage. Three kinds of state carry over.

• Authentication cookies and session data stay available across sessions.
• Data in localStorage and sessionStorage persists.
• IndexedDB content is kept between sessions.

The state that saves you a login can also hand you a stale one. If your app behaves differently for a signed-out user, you won't see it by default, because the browser still carries the last session's cookies. Start the flow where you need it, on a signed-out route or with 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. Cursor says multiple external security auditors have reviewed the integration. Browser actions need your approval by default, and the Browser docs offer three approval modes.

The Browser docs mark manual approval as recommended, and we would stay on it longer than feels necessary. The other two modes skip a review step on a browser that stays signed in to your app between sessions, so what you speed up is an authenticated session. If you move to the allow list, add only the few actions you are tired of approving, and keep navigation off it.

Cursor's Run Modes page describes approvals differently. It names the modes Auto-review, Allowlist and Run Everything under Settings > Agents > Approvals & Execution, and it calls Auto-review the safest useful setup for most people. It also lists Browser Protection, which stops the agent from running Browser tools automatically even when the mode would. If your settings show those names, follow that page, and turn on Browser Protection to keep approving each browser action yourself.

What stops unauthorized access and cross-tab interference?

A second layer protects the browser session itself. Before each browser session starts, Cursor generates a new random authentication token. Each tab gets its own random ID, which keeps tabs from interfering with each other. Whether a given click should happen is still up to your approval mode.

On a small team, keeping everyone on manual approval costs little, because the pages in play are usually your own localhost. On a large team, the approval mode is each person's own setting until an admin narrows it, and fifty engineers can mean fifty different postures.

Cursor's pricing page lists auto-run, browser and network controls on the Enterprise plan only. The Run Modes page adds that admins can set which modes are available to their users in the web dashboard, and that team settings take precedence over individual ones. The lever the Browser docs describe is the origin allowlist in the next section. It limits which sites the tools can act on at all, so it holds whatever mode each person picked.

For enterprise customers, browser access runs 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 turn the feature on or off, with granular control over each MCP server and over browser access. Setting it up for a team takes three steps.

1. 1In the Settings Dashboard, open 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.
2. 2Turn on browser features with Enable Browser Automation Features (v2.0+). Your team's access then follows your 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. allow or deny lists.
3. 3Under Browser Origin Allowlist (v2.1+), click Add Origin once for each origin, such as http://localhost:3000 or https://internal.example.com.

The origin allowlist restricts which sites the agent can navigate to on its own 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. It appears only after your Cursor account team enables it for your organization. Enable browser features before you add origins, because the allowlist has nothing to restrict while they are off.

Cursor's docs also say that an empty allowlist allows all origins. A dashboard you enable on Friday and mean to fill in on Monday allows every site over the weekend.

When browser tools stop working mid-run, first check which origin the browser is on. On an origin outside the allowlist, click, type and navigate are blocked, even if a person went there by hand. Manual navigation to any URL stays allowed on purpose, which helps when you want to read documentation in the pane. It is also how a session ends up parked where the tools won't act.