Back to docs

Tool Navigate

Category: Browser Automation · Tier: All

Navigate to a URL and take a screenshot. Pass _browserToken from a previous call to reuse the same browser. To test a phone or tablet layout, pass device and/or viewport on the navigate that starts the session; the response reports the device and viewport used.

When to Use

Browser automation tools map to human motor interaction research. Click accuracy, form filling speed, and scroll behavior follow HCI models.

Parameters

Parameter Type Required Description
url string Yes The URL to navigate to
waitAfterLoad number No Extra ms to wait after page load. Use for i18n or deferred rendering (3000-5000).
waitForSelector string No CSS selector to wait for after load. Example: [data-translated]. Times out after 10s.
device string No Device to emulate for this session: mobile, tablet, desktop, or a preset from list_devices such as iPhone 15 or Pixel 8 (user agent, touch, pixel ratio and size). Names match in any case.
viewport string No Page size for this session: WIDTHxHEIGHT (e.g. 1280x720) or a size name (mobile, tablet, desktop, desktop-sm, ...). With device, it sets the size and the device keeps its emulation.
_browserToken string No Session token from a previous call, to keep cookies and the page

Example

Navigate to our staging site to check the new deployment

Navigate to the French version and wait for translation to finish
→ url: "https://example.com/fr", waitAfterLoad: 4000

Navigate and wait for dynamic content
→ url: "https://example.com", waitForSelector: "#app:not(:empty)"

Open the pricing page as an iPhone 15
→ url: "https://example.com/pricing",
  device: "iPhone 15"

Device and viewport

device and viewport apply when navigate starts a session, that is, when you pass no _browserToken. A session keeps the device it started with.

  • With a _browserToken on the hosted server, navigate refuses rather than relaunch a session that may hold a login. The response is an error, device_needs_new_session. Call navigate without the token to start an emulated session.
  • On the local npx cbrowser mcp-server there is one shared browser, so navigate relaunches it with the new device.
  • An unknown device name is an error, unknown_device, with the closest presets in suggestions.
  • A malformed viewport is an error, invalid_viewport.

With device or viewport set, the response also carries device (the preset in use, or null when there is none) and viewport (the page's width and height). Abridged:

{
  "success": true,
  "url":
    "https://example.com/pricing",
  "title": "Pricing",
  "device": "iphone-15",
  "viewport": {
    "width": 393,
    "height": 852
  },
  "_browserToken": "..."
}

Tips

  • Pass _browserToken from a previous tool call to maintain the same browser session
  • The tool returns a _browserToken in its response — pass it to subsequent calls
  • Without _browserToken, each call gets a fresh browser (blank page)
  • Use waitAfterLoad for client-side translation (Google Translate, Tolgee, i18next)
  • Use waitForSelector for SPAs that render after JS hydration
  • Without device or viewport, pages render at 1920x1080

Research

From the Blog