Skip to content

Commit eddde13

Browse files
kathaylkathayl
committed
Merge origin/production: resolve conflicts with CDP docs PR
2 parents fcf5961 + d308e5d commit eddde13

File tree

9 files changed

+509
-2
lines changed

9 files changed

+509
-2
lines changed

‎src/content/docs/browser-rendering/cdp/index.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
pcx_content_type: concept
3+
title: Chrome DevTools Protocol (CDP)
4+
description: Create persistent browser sessions, manage tabs, and interact with browsers using Chrome DevTools Protocol (CDP) commands via the /devtools endpoints.
5+
sidebar:
6+
order: 5
7+
badge: Beta
8+
---
9+
10+
import { Render } from "~/components";
11+
12+
The `/devtools` endpoints provide session management capabilities that follow the [Chrome DevTools Protocol (CDP)](https://chromedevtools.github.io/devtools-protocol/). These endpoints allow you to create persistent browser sessions, manage multiple tabs, and interact with browsers using CDP commands. This is useful for advanced automation, debugging, and remote browser control.
13+
14+
CDP endpoints can be accessed from any environment that supports WebSocket connections, including local development machines, external servers, and CI/CD pipelines. This means you can connect to Browser Rendering from Node.js scripts, Puppeteer, Playwright, or any CDP-compatible client.
15+
16+
<Render file="rest-api-token-permissions" product="browser-rendering" />
17+
18+
## What is CDP?
19+
20+
The Chrome DevTools Protocol (CDP) is a remote debugging protocol that allows you to instrument, inspect, debug, and profile Chromium-based browsers. It is the same protocol used by Chrome DevTools to control and monitor the browser. Popular browser automation libraries like Puppeteer and Playwright provide high-level APIs over the Chrome DevTools Protocol, making it easier to automate common tasks.
21+
22+
## Use cases
23+
24+
The browser sessions endpoints enable you to:
25+
26+
- **Create and manage persistent browser sessions** — Launch browser instances that remain active for extended periods
27+
- **Open, close, and list browser tabs (targets)** — Manage multiple debuggable targets (pages, iframes, etc.) within a single browser instance
28+
- **Connect via WebSocket to send CDP commands** — Automate browser actions programmatically
29+
- **View live browser sessions using Chrome DevTools UI** — Debug and inspect remote browser sessions visually
30+
- **Integrate with existing CDP clients** — Use standard CDP clients like Puppeteer or custom WebSocket implementations
31+
32+
## How it works
33+
34+
Once you acquire a browser session, you can interact with it in two ways:
35+
36+
### CDP over WebSocket
37+
38+
Connect to the WebSocket endpoint `/devtools/browser` to acquire a session and send [CDP commands](https://chromedevtools.github.io/devtools-protocol/) directly over the connection. This is the standard way to use CDP and works with any CDP client, including [Puppeteer](/browser-rendering/cdp/puppeteer/), [Playwright](/browser-rendering/cdp/playwright/), and [MCP clients](/browser-rendering/cdp/mcp-clients/).
39+
40+
### HTTP API
41+
42+
HTTP endpoints are also available to manage the browser lifecycle without using WebSockets. These follow the standard [CDP HTTP endpoints](https://chromedevtools.github.io/devtools-protocol/#endpoints):
43+
44+
1. **Create session** — `POST /devtools/browser`
45+
2. **List tabs** — `GET /devtools/browser/{session_id}/json/list`
46+
3. **Create tab** — `PUT /devtools/browser/{session_id}/json/new`
47+
4. **Close tab** — `DELETE /devtools/browser/{session_id}/json/close/{target_id}`
48+
5. **Close session** — `DELETE /devtools/browser/{session_id}`
49+
50+
Check the [API reference](/api/resources/browser_rendering/) for the full list of endpoints.
51+
52+
<Render file="faq" product="browser-rendering" />

‎src/content/docs/browser-rendering/cdp/mcp-clients.mdx‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Using with MCP clients (CDP)
4+
description: Configure AI coding agents to control Browser Rendering sessions through the Model Context Protocol (MCP) using the chrome-devtools-mcp package.
5+
sidebar:
6+
order: 4
7+
---
8+
9+
import { Render } from "~/components";
10+
11+
You can use the CDP endpoints with AI coding agents through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). The [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) package provides an MCP server that allows AI assistants to control and inspect browser sessions.
12+
13+
<Render file="rest-api-token-permissions" product="browser-rendering" />
14+
15+
## What is MCP?
16+
17+
The Model Context Protocol (MCP) is an open protocol that enables AI assistants to interact with external tools and services. By configuring an MCP client with Browser Rendering, your AI coding agent can perform browser automation tasks like navigating to pages, taking screenshots, running performance audits, and debugging JavaScript.
18+
19+
## Prerequisites
20+
21+
- Node.js v20.19 or newer
22+
- An MCP-compatible AI client (for example, Claude Desktop, Claude Code, Cursor, OpenCode)
23+
- A Browser Rendering API token with `Browser Rendering - Edit` permissions
24+
25+
## Configure your MCP client
26+
27+
Add the following configuration to your MCP client settings file (the exact location depends on your client):
28+
29+
### Claude Desktop and Claude Code
30+
31+
Add to `claude_desktop_config.json` (Claude Desktop) or `~/.claude.json` (Claude Code):
32+
33+
```json
34+
{
35+
"mcpServers": {
36+
"browser-rendering": {
37+
"command": "npx",
38+
"args": [
39+
"-y",
40+
"chrome-devtools-mcp@latest",
41+
"--wsEndpoint=wss://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/devtools/browser?keep_alive=600000",
42+
"--wsHeaders={\"Authorization\":\"Bearer <API_TOKEN>\"}"
43+
]
44+
}
45+
}
46+
}
47+
```
48+
49+
### OpenCode
50+
51+
Add to `.opencode.jsonc`:
52+
53+
```json
54+
{
55+
"mcp": {
56+
"browser-rendering": {
57+
"type": "local",
58+
"command": [
59+
"npx",
60+
"-y",
61+
"chrome-devtools-mcp@latest",
62+
"--wsEndpoint=wss://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/devtools/browser?keep_alive=600000",
63+
"--wsHeaders={\"Authorization\":\"Bearer <API_TOKEN>\"}"
64+
],
65+
"enabled": true
66+
}
67+
}
68+
}
69+
```
70+
71+
### Cursor
72+
73+
Add to `~/.cursor/mcp.json`:
74+
75+
```json
76+
{
77+
"mcpServers": {
78+
"browser-rendering": {
79+
"command": "npx",
80+
"args": [
81+
"-y",
82+
"chrome-devtools-mcp@latest",
83+
"--wsEndpoint=wss://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/devtools/browser?keep_alive=600000",
84+
"--wsHeaders={\"Authorization\":\"Bearer <API_TOKEN>\"}"
85+
]
86+
}
87+
}
88+
}
89+
```
90+
91+
Replace `ACCOUNT_ID` with your Cloudflare account ID and `API_TOKEN` with your Browser Rendering API token. You can obtain these from your Cloudflare dashboard.
92+
93+
For other MCP clients, refer to the [chrome-devtools-mcp documentation](https://github.com/ChromeDevTools/chrome-devtools-mcp/tree/main?tab=readme-ov-file#mcp-client-configuration).
94+
95+
## Example usage
96+
97+
After configuring the MCP client, you can ask your AI agent to perform browser tasks:
98+
99+
```txt
100+
Navigate to https://example.com and take a screenshot of the homepage
101+
```
102+
103+
```txt
104+
Check the console messages on the current page for any errors
105+
```
106+
107+
```txt
108+
Run a Lighthouse audit on https://developers.cloudflare.com
109+
```
110+
111+
## How it works
112+
113+
The MCP server connects to Browser Rendering via WebSocket using the CDP protocol:
114+
115+
1. **WebSocket endpoint** - The `--wsEndpoint` URL connects to the Browser Rendering service
116+
2. **Authentication** - The `--wsHeaders` parameter includes your API token for authentication
117+
3. **Keep-alive** - The `keep_alive` query parameter (in milliseconds) specifies how long the session stays active
118+
4. **MCP protocol** - The server translates MCP tool calls into CDP commands
119+
120+
:::note[Session management]
121+
The `--wsEndpoint` parameter creates a new browser session automatically when the MCP server starts. The session remains active for the duration specified in `keep_alive` (in the examples above, 10 minutes). The MCP server will use this session for all browser operations until it is restarted.
122+
:::
123+
124+
## Additional resources
125+
126+
- [chrome-devtools-mcp repository](https://github.com/ChromeDevTools/chrome-devtools-mcp) - Official MCP server for Chrome DevTools
127+
- [Model Context Protocol documentation](https://modelcontextprotocol.io/) - Learn more about MCP
128+
- [Claude Desktop MCP setup](https://modelcontextprotocol.io/docs/develop/connect-local-servers) - Configure MCP servers in Claude Desktop
129+
- [Claude Code MCP setup](https://docs.anthropic.com/en/docs/claude-code/mcp) - Configure MCP servers in Claude Code
130+
- [Cursor MCP setup](https://cursor.com/docs/mcp) - Configure MCP servers in Cursor
131+
- [OpenCode MCP setup](https://opencode.ai/docs/mcp-servers/) - Configure MCP servers in OpenCode
132+
133+
<Render file="faq" product="browser-rendering" />

‎src/content/docs/browser-rendering/cdp/playwright.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Using with Playwright (CDP)
4+
description: Connect Playwright to Browser Rendering sessions from any Node.js environment to automate browser tasks using the Chrome DevTools Protocol.
5+
sidebar:
6+
order: 3
7+
---
8+
9+
import { PackageManagers, Render } from "~/components";
10+
11+
You can use [Playwright](https://playwright.dev/) to connect to Browser Rendering sessions from any Node.js environment and automate browser tasks programmatically via CDP. This is useful for scripts running on your local machine, CI/CD pipelines, or external servers.
12+
13+
<Render file="rest-api-token-permissions" product="browser-rendering" />
14+
15+
## Prerequisites
16+
17+
- Node.js installed on your machine
18+
- A Cloudflare account with Browser Rendering enabled
19+
- A Browser Rendering API token with `Browser Rendering - Edit` permissions
20+
21+
## Install Playwright
22+
23+
Install the `playwright-core` package (the version without bundled browsers):
24+
25+
<PackageManagers pkg="playwright-core" />
26+
27+
## Connect to Browser Rendering
28+
29+
The following script demonstrates how to connect to a Browser Rendering session, navigate to a page, extract the title, and take a screenshot.
30+
31+
Create a file named `script.js`:
32+
33+
```js
34+
const { chromium } = require("playwright-core");
35+
36+
const ACCOUNT_ID = process.env.CF_ACCOUNT_ID || "<ACCOUNT_ID>";
37+
const API_TOKEN = process.env.CF_API_TOKEN || "<API_TOKEN>";
38+
39+
const browserWSEndpoint = `wss://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-rendering/devtools/browser?keep_alive=600000`;
40+
41+
async function main() {
42+
const browser = await chromium.connectOverCDP(browserWSEndpoint, {
43+
headers: {
44+
Authorization: `Bearer ${API_TOKEN}`,
45+
},
46+
});
47+
48+
const context = browser.contexts()[0];
49+
const page = context.pages()[0] || (await context.newPage());
50+
await page.goto("https://developers.cloudflare.com");
51+
52+
const title = await page.title();
53+
console.log(`Page title: ${title}`);
54+
55+
await page.screenshot({ path: "screenshot.png" });
56+
57+
await browser.close();
58+
}
59+
60+
main().catch(console.error);
61+
```
62+
63+
Replace `ACCOUNT_ID` with your Cloudflare account ID and `API_TOKEN` with your Browser Rendering API token, or set them as environment variables:
64+
65+
```bash
66+
export CF_ACCOUNT_ID="<ACCOUNT_ID>"
67+
export CF_API_TOKEN="<API_TOKEN>"
68+
```
69+
70+
## Run the script
71+
72+
```bash
73+
node script.js
74+
```
75+
76+
You should see the page title printed to the console and a screenshot saved as `screenshot.png`.
77+
78+
## How it works
79+
80+
The script connects directly to Browser Rendering via WebSocket using the CDP protocol:
81+
82+
1. **WebSocket endpoint** - The `browserWSEndpoint` URL acquires a new browser session and connects to it via WebSocket
83+
2. **Authentication** - The `Authorization` header with your API token authenticates the request
84+
3. **Keep-alive** - The `keep_alive` parameter (in milliseconds) specifies how long the session stays active
85+
4. **Playwright API** - Once connected, you use the standard Playwright API to control the browser
86+
87+
<Render file="faq" product="browser-rendering" />

‎src/content/docs/browser-rendering/cdp/puppeteer.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Using with Puppeteer (CDP)
4+
description: Connect Puppeteer to Browser Rendering sessions from any Node.js environment to automate browser tasks using the Chrome DevTools Protocol.
5+
sidebar:
6+
order: 2
7+
---
8+
9+
import { PackageManagers, Render } from "~/components";
10+
11+
You can use [Puppeteer](https://pptr.dev/) to connect to Browser Rendering sessions from any Node.js environment and automate browser tasks programmatically via CDP. This is useful for scripts running on your local machine, CI/CD pipelines, or external servers.
12+
13+
<Render file="rest-api-token-permissions" product="browser-rendering" />
14+
15+
## Prerequisites
16+
17+
- Node.js installed on your machine
18+
- A Cloudflare account with Browser Rendering enabled
19+
- A Browser Rendering API token with `Browser Rendering - Edit` permissions
20+
21+
## Install Puppeteer
22+
23+
Install the `puppeteer-core` package (the version without bundled Chrome):
24+
25+
<PackageManagers pkg="puppeteer-core" />
26+
27+
## Connect to Browser Rendering
28+
29+
The following script demonstrates how to connect to a Browser Rendering session, navigate to a page, extract the title, and take a screenshot.
30+
31+
Create a file named `script.js`:
32+
33+
```js
34+
const puppeteer = require("puppeteer-core");
35+
36+
const ACCOUNT_ID = process.env.CF_ACCOUNT_ID || "<ACCOUNT_ID>";
37+
const API_TOKEN = process.env.CF_API_TOKEN || "<API_TOKEN>";
38+
39+
const browserWSEndpoint = `wss://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-rendering/devtools/browser?keep_alive=600000`;
40+
41+
async function main() {
42+
const browser = await puppeteer.connect({
43+
browserWSEndpoint,
44+
headers: {
45+
Authorization: `Bearer ${API_TOKEN}`,
46+
},
47+
});
48+
49+
const page = await browser.newPage();
50+
await page.goto("https://developers.cloudflare.com");
51+
52+
const title = await page.title();
53+
console.log(`Page title: ${title}`);
54+
55+
await page.screenshot({ path: "screenshot.png" });
56+
57+
await browser.close();
58+
}
59+
60+
main().catch(console.error);
61+
```
62+
63+
Replace `ACCOUNT_ID` with your Cloudflare account ID and `API_TOKEN` with your Browser Rendering API token, or set them as environment variables:
64+
65+
```bash
66+
export CF_ACCOUNT_ID="<ACCOUNT_ID>"
67+
export CF_API_TOKEN="<API_TOKEN>"
68+
```
69+
70+
## Run the script
71+
72+
```bash
73+
node script.js
74+
```
75+
76+
You should see the page title printed to the console and a screenshot saved as `screenshot.png`.
77+
78+
## How it works
79+
80+
The script connects directly to Browser Rendering via WebSocket using the CDP protocol:
81+
82+
1. **WebSocket endpoint** - The `browserWSEndpoint` URL acquires a new browser session and connects to it via WebSocket
83+
2. **Authentication** - The `Authorization` header with your API token authenticates the request
84+
3. **Keep-alive** - The `keep_alive` parameter (in milliseconds) specifies how long the session stays active
85+
4. **Puppeteer API** - Once connected, you use the standard Puppeteer API to control the browser
86+
87+
<Render file="faq" product="browser-rendering" />

0 commit comments

Comments
 (0)