How to Use Browser Tools MCP with Trae

Trae can control web pages in two different ways: its built-in Browser Use controls, or an external browser tool exposed through MCP. Use the built-in route when you want Trae to operate its own browser. Add Playwright MCP when you need a separately configured tool server, browser automation actions, or a connection to an existing Chrome or Edge session.

These routes are configured separately. A browser server added under Settings > MCP is not the same thing as enabling Trae’s native browser controls. Trae’s documentation refers to its main China client as TraeCode, and menu names can vary by version and region.

Choose the right route

Route	Where it runs	Best for	Logged-in browser state
Built-in Browser Use	Trae’s built-in browser	Quick page inspection and simple interactions	Uses the built-in browser profile
External Chrome	Your Chrome or Edge instance through the TraeWork extension	Existing tabs, cookies, and trusted domains	Can reuse the connected browser session
Playwright MCP	A fresh Playwright browser or a connected Chromium session	Structured navigation, forms, screenshots, tabs, and test workflows	Depends on the selected Playwright connection mode

Trae states that its Chat agent cannot operate the browser. Use an agent that supports Browser Use or MCP tools, such as Builder or a custom agent configured with the relevant MCP server.

Option 1: enable Trae’s built-in browser

1. Open Trae settings.
2. Open Browser.
3. Enable Allow AI to control built-in browser.
4. Open a harmless test page and ask a compatible agent to report its title.

The built-in browser is the shortest path when you do not need your normal Chrome profile. Trae’s browser settings also document clearing built-in-browser cookies and local storage, which is useful when a test must start without prior session data. See the [Trae Browser Use documentation](https://docs.trae.cn/).

Option 2: connect external Chrome or Edge

1. Open Settings > Browser > External Browser.
2. Install the TraeWork Browser Extension.
3. If you work with logged-in pages, configure the trusted-domain allowlist before installing or connecting the extension.
4. Enable Default use external browser.
5. Open the target tab in Chrome or Edge and run a small read-only task first.

The extension route is useful when the page requires cookies, an existing login, or a specific browser profile. Treat trusted domains as an access boundary: include only the sites the agent needs.

Option 3: add Playwright MCP from Trae’s marketplace

1. Open Settings > MCP.
2. Choose Add, then Add from Marketplace.
3. Find Playwright and add it.
4. Review the server configuration and confirm it.
5. Open Builder or create a custom agent.
6. In the agent’s MCP tools, select Playwright.

Trae’s Playwright tutorial describes this marketplace flow. The exact marketplace entries and labels can change, so review the configuration shown by your installed client before confirming it.

Install Playwright MCP manually

Playwright’s documented baseline starts the server with npx and requires Node.js 20 or newer:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Save this object wherever your MCP client expects server configuration, then restart or reload the client. In Trae, you can also use the MCP import-link flow. Trae describes import links containing Base64-encoded JSON; importing opens the configuration for review and confirmation. Never confirm a command or URL you have not inspected.

Connect Playwright MCP to an existing browser

Playwright supports several connection modes. Choose one instead of combining flags casually:

Need	Connection
Start an isolated browser	Run the baseline npx @playwright/mcp@latest server.
Use a running Chrome or Edge channel	Start with --cdp-endpoint=chrome.
Connect to Chromium exposing a debugging endpoint	Provide its CDP URL.
Connect to a Playwright server	Use --endpoint=ws://....
Reuse existing Chrome or Edge tabs through an extension	Use --extension; select a profile with --profile-dir-name when required.

Existing-session modes can expose cookies, account data, and open tabs to the agent. Use a dedicated browser profile for development work and avoid connecting a personal profile to an untrusted MCP client.

Run a safe first task

1. Open a public documentation page or local development page.
2. Ask the agent to navigate to it and report the page title.
3. Ask for a screenshot.
4. Try one non-destructive interaction, such as opening a link or filling a test form.
5. Only then attempt authenticated workflows or state-changing actions.

Playwright MCP exposes navigation, clicking, form filling, selecting fields, screenshots, console logs, page text and HTML, keyboard and mouse actions, drag operations, tabs, viewport resizing, and HTTP methods. Use the smallest set of tools needed for the task.

What the agent can see and do

• Navigation: open URLs, move between pages, and inspect page state.
• Interaction: click, fill, select, type, press keys, drag, and handle tabs or dialogs.
• Inspection: read structured accessibility snapshots, page text, HTML, console output, and screenshots.
• Network: issue HTTP GET, POST, PUT, PATCH, and DELETE requests when the configured tool permits them.
• Presentation: resize the viewport and capture screenshots.

Playwright’s MCP approach uses structured accessibility snapshots for many interactions. This is generally easier for an agent to reason about than coordinates, but pages with unusual custom controls may still need a different locator or a carefully scoped script.

Security and permissions

Use trusted domains

For external Chrome, configure Trae’s trusted-domain option before connecting a profile that contains authenticated sessions. Keep the allowlist narrow and remove domains when a task is complete.

Separate test and personal profiles

A fresh Playwright profile avoids sending personal cookies to the agent. If you must reuse a session, use a dedicated profile with test accounts and limited permissions.

Be careful with arbitrary JavaScript

Playwright documents its arbitrary-JavaScript tool as RCE-equivalent and recommends enabling it only for trusted MCP clients. Ordinary navigation, locators, form actions, and screenshots usually do not require this capability. Keep arbitrary code disabled unless the workflow genuinely needs it.

Review imported configurations

An MCP configuration can run a local executable or connect to a remote endpoint. Review the command, package, arguments, environment variables, and endpoint before confirming an import.

Common errors and fixes

Error or symptom	Likely cause	Fix
The agent cannot click or navigate	You are using Trae’s Chat agent or an agent without browser tools.	Use Builder or a custom agent and assign Browser Use or Playwright MCP.
Playwright does not appear in MCP tools	The server was added but not assigned to the current agent.	Open the agent configuration and select Playwright in its MCP tools.
npx fails to start	Node.js is missing, too old, or unavailable on PATH.	Install Node.js 20 or newer, restart Trae, and confirm node --version and npx --version.
The browser opens but the target tab is missing	The wrong connection mode or profile is selected.	Use the documented CDP, endpoint, or extension mode and select the intended profile with --profile-dir-name when needed.
A logged-in page appears logged out	The server started an isolated profile.	Use the external-browser extension or another existing-session mode with a dedicated authenticated profile.
Actions time out	The page is still loading, a selector is wrong, a dialog blocks input, or the site requires a longer wait.	Inspect the accessibility snapshot, wait for the relevant state, handle dialogs, and use stable semantic locators.
CAPTCHA or bot checks stop the workflow	The site detected automation.	Do not attempt to bypass the challenge. Use an approved test environment or complete the check manually in a permitted session.
Import-link configuration looks different	Trae or the server package changed.	Decode and review the link contents, compare them with the current Playwright documentation, and confirm only after checking each field.
Existing Chrome connection is refused	The debugging endpoint is unavailable or the browser was started without the required connection mode.	Restart the browser with the documented CDP or extension setup, verify the endpoint, and retry.

Reliability and performance practices

• Start with a title or text assertion before performing a write action.
• Prefer semantic roles, labels, and stable test IDs over CSS paths tied to layout.
• Wait for a specific selector or application state instead of using long fixed sleeps.
• Keep each agent task small; separate navigation, data entry, and verification when failures are expensive.
• Capture console output and screenshots around failures so you can distinguish an application bug from an MCP connection problem.
• Use an isolated profile for repeatable runs and a persistent profile only when session reuse is required.
• Limit concurrency when the site rate-limits requests or the machine has limited memory.

Native browser versus Playwright MCP

Question	Native Browser Use	Playwright MCP
Setup	Enable a Trae browser setting.	Add and configure an MCP server.
Browser target	Built-in browser, or external Chrome through the extension.	Fresh Playwright browser, CDP browser, Playwright endpoint, or extension-connected tabs.
Session reuse	Built-in storage or connected external profile.	Depends on the selected profile and connection mode.
Tool surface	Trae’s native browser controls.	Playwright navigation, interaction, inspection, screenshots, tabs, and related tools.
Best starting point	Quick inspection inside Trae.	Repeatable browser workflows and explicit MCP tool assignment.

Or skip the browser setup

If your goal is a clean screenshot rather than interactive browser control, ScreenshotNeo returns an image or PDF from one request. Its consent step accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. It also provides an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for all options. This one-call example captures Stripe as WebP:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo includes full-page and element capture, dark mode, device presets or custom viewports, retina scale, PDF paper and page controls, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Free accounts include 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account and start with 1,000 screenshots a month without adding a card.

FAQ

Is Browser MCP the same as Playwright MCP?

No. “Browser MCP” can refer to a separate vendor server, while Playwright MCP is the server documented by Playwright and covered in Trae’s tutorial. Verify the package and extension instructions for any third-party server before importing it.

Can Trae control my normal Chrome tabs?

Yes, when you use the external-browser extension or a Playwright connection mode that attaches to an existing browser. Use a dedicated profile and trusted domains.

Does Playwright MCP require Node.js?

The documented baseline uses npx and Node.js 20 or newer.

Why can’t the Chat agent use browser tools?

Trae documents that its Chat agent cannot operate the browser. Choose an agent with Browser Use or MCP tools enabled.

Should I enable arbitrary JavaScript?

Only for a trusted MCP client and a task that requires it. Playwright labels that capability RCE-equivalent.