Skip to content

Commit 72939a5

Browse files
IlyaasKIlyaasK
committed
Update MCP docs for browser pool parity
1 parent a33ae0f commit 72939a5

20 files changed

Lines changed: 749 additions & 68 deletions

‎docs.json‎

Lines changed: 42 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -300,16 +300,48 @@
300300
{
301301
"group": "Tools",
302302
"pages": [
303-
"reference/mcp-server/tools/manage-browsers",
304-
"reference/mcp-server/tools/manage-profiles",
305-
"reference/mcp-server/tools/manage-browser-pools",
306-
"reference/mcp-server/tools/manage-proxies",
307-
"reference/mcp-server/tools/manage-extensions",
308-
"reference/mcp-server/tools/manage-apps",
309-
"reference/mcp-server/tools/computer-action",
310-
"reference/mcp-server/tools/execute-playwright-code",
311-
"reference/mcp-server/tools/exec-command",
312-
"reference/mcp-server/tools/search-docs"
303+
"reference/mcp-server/tools",
304+
{
305+
"group": "Browser Control",
306+
"pages": [
307+
"reference/mcp-server/tools/manage-browsers",
308+
"reference/mcp-server/tools/manage-browser-pools",
309+
"reference/mcp-server/tools/browser-curl",
310+
"reference/mcp-server/tools/computer-action",
311+
"reference/mcp-server/tools/execute-playwright-code",
312+
"reference/mcp-server/tools/exec-command"
313+
]
314+
},
315+
{
316+
"group": "Browser Resources",
317+
"pages": [
318+
"reference/mcp-server/tools/manage-profiles",
319+
"reference/mcp-server/tools/manage-proxies",
320+
"reference/mcp-server/tools/manage-extensions"
321+
]
322+
},
323+
{
324+
"group": "Apps & Organization",
325+
"pages": [
326+
"reference/mcp-server/tools/manage-apps",
327+
"reference/mcp-server/tools/manage-projects",
328+
"reference/mcp-server/tools/manage-api-keys"
329+
]
330+
},
331+
{
332+
"group": "Managed Auth",
333+
"pages": [
334+
"reference/mcp-server/tools/manage-auth-connections",
335+
"reference/mcp-server/tools/manage-credentials",
336+
"reference/mcp-server/tools/manage-credential-providers"
337+
]
338+
},
339+
{
340+
"group": "Utilities",
341+
"pages": [
342+
"reference/mcp-server/tools/search-docs"
343+
]
344+
}
313345
]
314346
},
315347
{

‎reference/mcp-server.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with
2121
Authorize access through your browser when prompted. See [Authentication](/reference/mcp-server/authentication) for OAuth and API key options.
2222
</Step>
2323
<Step title="Start automating">
24-
Use the [tools](/reference/mcp-server/tools/manage-browsers) to launch browsers, run Playwright code, and invoke your apps.
24+
Use the [tools](/reference/mcp-server/tools) to launch browsers, warm browser pools, run Playwright code, invoke your apps, and manage auth workflows.
2525
</Step>
2626
</Steps>
2727

@@ -37,8 +37,8 @@ The server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with
3737
<Card icon="rectangle-terminal" title="Connect your client" href="/reference/mcp-server/clients/claude">
3838
Setup for Claude, Cursor, VS Code, and more.
3939
</Card>
40-
<Card icon="wrench" title="Tools" href="/reference/mcp-server/tools/manage-browsers">
41-
Browsers, profiles, proxies, apps, and more.
40+
<Card icon="wrench" title="Tools" href="/reference/mcp-server/tools">
41+
Browsers, pools, apps, projects, API keys, and managed auth.
4242
</Card>
4343
<Card icon="database" title="Resources" href="/reference/mcp-server/resources">
4444
Read browsers, pools, profiles, and apps.

‎reference/mcp-server/resources.mdx‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,17 @@ title: "Resources"
33
description: "Read browsers, pools, profiles, and apps as MCP resources"
44
---
55

6-
The Kernel MCP server exposes your account's objects as MCP resources. Each resource URI lists all items or returns a specific one.
6+
The Kernel MCP server exposes your account's objects as MCP resources. List URIs return collections, and templated URIs return one object.
77

88
| Resource | Description |
99
|----------|-------------|
10-
| `browsers://` | Access browser sessions (list all or get a specific session). |
11-
| `browser_pools://` | Access browser pools (list all or get a specific pool). |
12-
| `profiles://` | Access browser profiles (list all or get a specific profile). |
13-
| `apps://` | Access deployed apps (list all or get a specific app). |
10+
| `browsers://` | List browser sessions. |
11+
| `browsers://{session_id}` | Read one browser session. |
12+
| `browser-pools://` | List browser pools. |
13+
| `browser-pools://{id_or_name}` | Read one browser pool by ID or name. |
14+
| `profiles://` | List browser profiles. |
15+
| `profiles://{profile_name}` | Read one browser profile by name. |
16+
| `apps://` | List deployed apps. |
17+
| `apps://{app_name}` | Read one deployed app by name. |
18+
19+
Use resources when your client needs read-only context. Use the matching `manage_*` tool when you need to create, update, delete, acquire, release, or invoke something.

‎reference/mcp-server/tools.mdx‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: "Tools"
3+
description: "Choose the right Kernel MCP tool for browser automation, apps, projects, and managed auth"
4+
---
5+
6+
Kernel MCP tools let your agent create and control browser sessions, manage reusable browser resources, invoke apps, organize project access, and keep profiles authenticated.
7+
8+
Examples on these pages show MCP tool argument payloads, not SDK code. Use the linked product guides when you need TypeScript, Python, or Go examples.
9+
10+
## Source of truth
11+
12+
The live argument schema for each tool comes from the Kernel MCP server implementation. These pages explain how to use those tools in agent workflows. When a tool action, parameter, or response changes, update the server tool definition and the matching page together.
13+
14+
## Browser control
15+
16+
<Columns cols={2}>
17+
<Card icon="globe" title="Manage Browsers" href="/reference/mcp-server/tools/manage-browsers">
18+
Create, update, list, inspect, and delete live browser sessions.
19+
</Card>
20+
<Card icon="layers" title="Manage Browser Pools" href="/reference/mcp-server/tools/manage-browser-pools">
21+
Create, resize, acquire from, release to, flush, and delete pre-warmed browser pools.
22+
</Card>
23+
<Card icon="terminal" title="Browser Curl" href="/reference/mcp-server/tools/browser-curl">
24+
Send HTTP requests through a browser session's cookies, headers, and network path.
25+
</Card>
26+
<Card icon="mouse-pointer-click" title="Computer Action" href="/reference/mcp-server/tools/computer-action">
27+
Move, click, type, scroll, wait, screenshot, and manage clipboard state.
28+
</Card>
29+
<Card icon="code" title="Execute Playwright Code" href="/reference/mcp-server/tools/execute-playwright-code">
30+
Run Playwright code against an existing Kernel browser session.
31+
</Card>
32+
<Card icon="square-terminal" title="Exec Command" href="/reference/mcp-server/tools/exec-command">
33+
Run shell commands inside the browser VM.
34+
</Card>
35+
</Columns>
36+
37+
## Browser resources
38+
39+
<Columns cols={2}>
40+
<Card icon="user-circle" title="Manage Profiles" href="/reference/mcp-server/tools/manage-profiles">
41+
Set up, list, inspect, and delete browser profiles.
42+
</Card>
43+
<Card icon="route" title="Manage Proxies" href="/reference/mcp-server/tools/manage-proxies">
44+
Create, list, and delete proxy configurations.
45+
</Card>
46+
<Card icon="puzzle-piece" title="Manage Extensions" href="/reference/mcp-server/tools/manage-extensions">
47+
List and delete browser extensions uploaded to your organization.
48+
</Card>
49+
</Columns>
50+
51+
## Apps and organization
52+
53+
<Columns cols={2}>
54+
<Card icon="rocket" title="Manage Apps" href="/reference/mcp-server/tools/manage-apps">
55+
List apps, invoke actions, inspect deployments, and inspect invocation results.
56+
</Card>
57+
<Card icon="folder-tree" title="Manage Projects" href="/reference/mcp-server/tools/manage-projects">
58+
Create, list, inspect, rename, archive, and delete projects.
59+
</Card>
60+
<Card icon="key" title="Manage API Keys" href="/reference/mcp-server/tools/manage-api-keys">
61+
Create, list, inspect, rename, and revoke API keys.
62+
</Card>
63+
</Columns>
64+
65+
## Managed auth
66+
67+
<Columns cols={2}>
68+
<Card icon="lock" title="Manage Auth Connections" href="/reference/mcp-server/tools/manage-auth-connections">
69+
Create managed auth connections, start login flows, poll state, and submit user input.
70+
</Card>
71+
<Card icon="badge-check" title="Manage Credentials" href="/reference/mcp-server/tools/manage-credentials">
72+
Store, rotate, inspect, delete, and generate TOTP codes for managed auth credentials.
73+
</Card>
74+
<Card icon="vault" title="Manage Credential Providers" href="/reference/mcp-server/tools/manage-credential-providers">
75+
Connect external credential providers and list available provider items.
76+
</Card>
77+
</Columns>
78+
79+
## Utilities
80+
81+
<Columns cols={2}>
82+
<Card icon="search" title="Search Docs" href="/reference/mcp-server/tools/search-docs">
83+
Search Kernel documentation from your MCP client.
84+
</Card>
85+
</Columns>

‎reference/mcp-server/tools/browser-curl.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: "Browser Curl"
3+
description: "Send HTTP requests through an existing browser session"
4+
---
5+
6+
Use `browser_curl` when an agent needs an HTTP request to behave like it came from an existing browser session. The request goes through the browser's Chrome network stack, so it can use the session's cookies, proxy, network context, and origin behavior.
7+
8+
This is useful after a browser has logged in to a site and the agent needs a JSON endpoint, a redirect target, or a binary asset without writing Playwright code for the request.
9+
10+
<Note>For documentation lookup or general web search, use `search_docs` or your agent's normal search tool instead.</Note>
11+
12+
## Recommended flow
13+
14+
1. Use `manage_browsers` or `manage_browser_pools` to get a browser with the right cookies, proxy, and profile.
15+
2. Call `browser_curl` with the returned `session_id`.
16+
3. Use `response_encoding: "base64"` when the response might be binary.
17+
4. Use `execute_playwright_code` instead when you need page JavaScript, DOM state, or user-visible navigation.
18+
19+
## Parameters
20+
21+
| Parameter | Description |
22+
|-----------|-------------|
23+
| `session_id` | Browser session ID. Required. |
24+
| `url` | Target `http` or `https` URL. Required. |
25+
| `method` | HTTP method: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, or `OPTIONS`. Defaults to `GET`. |
26+
| `headers` | Custom headers merged with browser defaults. |
27+
| `body` | Request body for `POST`, `PUT`, or `PATCH` requests. |
28+
| `response_encoding` | Response body encoding: `utf8` or `base64`. Use `base64` for binary content. |
29+
| `timeout_ms` | Request timeout in milliseconds. Must be 1 or greater. |
30+
31+
## Read an authenticated endpoint
32+
33+
```json
34+
{
35+
"session_id": "browser_2vDb5kRmZ4nP8xQ1cA7",
36+
"url": "https://app.example.com/api/account",
37+
"method": "GET",
38+
"headers": {
39+
"Accept": "application/json"
40+
},
41+
"timeout_ms": 10000
42+
}
43+
```
44+
45+
## Post with browser cookies
46+
47+
```json
48+
{
49+
"session_id": "browser_2vDb5kRmZ4nP8xQ1cA7",
50+
"url": "https://app.example.com/api/tasks",
51+
"method": "POST",
52+
"headers": {
53+
"Content-Type": "application/json"
54+
},
55+
"body": "{\"title\":\"Run nightly checkout audit\"}",
56+
"response_encoding": "utf8"
57+
}
58+
```

‎reference/mcp-server/tools/computer-action.mdx‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
---
2-
title: "computer_action"
3-
description: "Mouse, keyboard, and screenshot controls for browser sessions"
2+
title: "Computer Action"
3+
description: "Mouse, keyboard, clipboard, and screenshot controls for browser sessions"
44
---
55

6-
Execute computer actions on a browser session. Pass a single action for simple operations, or pass multiple actions to batch them into one request for lower latency.
6+
Use `computer_action` when an agent needs to interact with the browser like a user: click, type, scroll, drag, copy, paste, or inspect the screen. Pass one action for a simple operation, or batch several actions into one call to reduce latency.
77

8-
<Tip>Always include a `screenshot` as the last action so you can see the result. `screenshot` and `get_mouse_position` return data, so they must come last.</Tip>
8+
<Tip>Include a `screenshot` as the last action when you need to see the result. `screenshot`, `read_clipboard`, and `get_mouse_position` return data, so they must be the last action if included.</Tip>
99

1010
## Parameters
1111

1212
| Parameter | Description |
1313
|-----------|-------------|
1414
| `session_id` | Browser session ID. Required. |
15-
| `actions` | Ordered list of actions to perform. Required. |
15+
| `actions` | Ordered list of one or more actions to perform. Required. |
1616

1717
## Action types
1818

@@ -26,10 +26,19 @@ Execute computer actions on a browser session. Pass a single action for simple o
2626
| `drag_mouse` | Drag along a `path` of `[x, y]` points. |
2727
| `set_cursor` | Show or hide the cursor (`hidden`). |
2828
| `sleep` | Wait `duration_ms` between steps when the page needs time to react. |
29+
| `write_clipboard` | Write `text` to the browser session clipboard. |
30+
| `read_clipboard` | Read the browser session clipboard. Must be the last action if included. |
2931
| `screenshot` | Capture the page, optionally limited to a `region`. |
3032
| `get_mouse_position` | Return the current cursor position. |
3133

32-
## Example
34+
## Recommended flow
35+
36+
1. Start with `screenshot` so the agent can see the viewport and coordinate space.
37+
2. Batch related pointer and keyboard actions together.
38+
3. Add `sleep` between actions that trigger navigation, animation, or async UI updates.
39+
4. End with `screenshot`, `read_clipboard`, or `get_mouse_position` only when you need returned data.
40+
41+
## Search from the page
3342

3443
```json
3544
{
@@ -43,3 +52,18 @@ Execute computer actions on a browser session. Pass a single action for simple o
4352
]
4453
}
4554
```
55+
56+
## Clipboard example
57+
58+
```json
59+
{
60+
"session_id": "browser_2vDb5kRmZ4nP8xQ1cA7",
61+
"actions": [
62+
{ "type": "write_clipboard", "write_clipboard": { "text": "https://kernel.sh/docs" } },
63+
{ "type": "press_key", "press_key": { "keys": ["Ctrl+l"] } },
64+
{ "type": "press_key", "press_key": { "keys": ["Ctrl+v"] } },
65+
{ "type": "press_key", "press_key": { "keys": ["Return"] } },
66+
{ "type": "screenshot" }
67+
]
68+
}
69+
```

‎reference/mcp-server/tools/exec-command.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: "exec_command"
2+
title: "Exec Command"
33
description: "Run shell commands inside a browser VM"
44
---
55

6-
Execute a command synchronously inside a browser VM. Returns decoded stdout, stderr, and the exit code. The `command` field is the executable; pass its arguments in `args`.
6+
Use `exec_command` to execute a command synchronously inside a browser VM. It returns decoded stdout, stderr, and the exit code. The `command` field is the executable; pass its arguments in `args`.
77

88
## Parameters
99

‎reference/mcp-server/tools/execute-playwright-code.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: "execute_playwright_code"
2+
title: "Execute Playwright Code"
33
description: "Run Playwright/TypeScript code against a browser session"
44
---
55

6-
Execute Playwright/TypeScript automation code against a Kernel browser session. If `session_id` is provided, uses that existing browser; otherwise creates a new one. Returns the result with a video replay URL, and auto-cleans up browsers it creates.
6+
Use `execute_playwright_code` to run Playwright/TypeScript automation code against a Kernel browser session. If you provide `session_id`, it uses that existing browser. If you omit `session_id`, it creates a browser and cleans it up after execution.
77

88
<Tip>Use `computer_action` with the `screenshot` action instead of `page.screenshot()` in your code. For a comprehensive page state snapshot, use `await page._snapshotForAI()`.</Tip>
99

‎reference/mcp-server/tools/manage-api-keys.mdx‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: "Manage API Keys"
3+
description: "Create, list, update, and revoke Kernel API keys"
4+
---
5+
6+
Use `manage_api_keys` when an agent or automation workflow needs to provision, inspect, rename, or revoke Kernel API keys. Created keys include the plaintext secret once; later reads return masked key metadata.
7+
8+
Create project-scoped keys for workloads that only need one project's resources. Use org-wide keys only when the workload needs access across projects.
9+
10+
For API key concepts, scoping rules, rotation guidance, and SDK examples, see [API Keys](/info/api-keys).
11+
12+
## Actions
13+
14+
| Action | Description |
15+
|--------|-------------|
16+
| `create` | Create an org-wide or project-scoped API key. |
17+
| `list` | List masked API keys. |
18+
| `get` | Retrieve one masked API key. |
19+
| `update` | Rename an API key. |
20+
| `delete` | Revoke an API key. |
21+
22+
## Recommended flow
23+
24+
1. Call `list` before creating a key so you don't duplicate an existing workload key.
25+
2. Call `create` with `project_id` for project-scoped automation.
26+
3. Store the returned plaintext key immediately.
27+
4. Call `update` when a key's owner or purpose changes.
28+
5. Call `delete` to revoke keys for retired workloads.
29+
30+
## Parameters
31+
32+
| Parameter | Description |
33+
|-----------|-------------|
34+
| `action` | Operation to perform. Required. |
35+
| `api_key_id` | API key ID. Required for `get`, `update`, and `delete`. |
36+
| `name` | (create, update) API key name. |
37+
| `project_id` | (create) Project ID for project-scoped keys. Omit or use `null` for org-wide keys. |
38+
| `days_to_expire` | (create) Days until expiry, up to 3650. Use `null` for no expiry. |
39+
| `limit` | (list) Max results per page. Must be 1-100. |
40+
| `offset` | (list) Pagination offset. Must be 0 or greater. |
41+
42+
## Create a project-scoped key
43+
44+
```json
45+
{
46+
"action": "create",
47+
"name": "checkout-agent-prod",
48+
"project_id": "proj_2vE0M7bLwX9kQ4nP3sY8",
49+
"days_to_expire": 90
50+
}
51+
```
52+
53+
## Rename a key
54+
55+
```json
56+
{
57+
"action": "update",
58+
"api_key_id": "ak_2vE1qJ7ZpLm8N4cT6rW0",
59+
"name": "checkout-agent-prod-rotated"
60+
}
61+
```

0 commit comments

Comments
 (0)