Skip to content

Commit cb2ae5a

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

19 files changed

Lines changed: 615 additions & 61 deletions

‎docs.json‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -301,14 +301,20 @@
301301
"group": "Tools",
302302
"pages": [
303303
"reference/mcp-server/tools/manage-browsers",
304-
"reference/mcp-server/tools/manage-profiles",
305304
"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",
305+
"reference/mcp-server/tools/browser-curl",
309306
"reference/mcp-server/tools/computer-action",
310307
"reference/mcp-server/tools/execute-playwright-code",
311308
"reference/mcp-server/tools/exec-command",
309+
"reference/mcp-server/tools/manage-profiles",
310+
"reference/mcp-server/tools/manage-proxies",
311+
"reference/mcp-server/tools/manage-extensions",
312+
"reference/mcp-server/tools/manage-apps",
313+
"reference/mcp-server/tools/manage-projects",
314+
"reference/mcp-server/tools/manage-api-keys",
315+
"reference/mcp-server/tools/manage-auth-connections",
316+
"reference/mcp-server/tools/manage-credentials",
317+
"reference/mcp-server/tools/manage-credential-providers",
312318
"reference/mcp-server/tools/search-docs"
313319
]
314320
},

‎reference/mcp-server.mdx‎

Lines changed: 2 additions & 2 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/manage-browsers) to launch browsers, warm browser pools, run Playwright code, invoke your apps, and manage auth workflows.
2525
</Step>
2626
</Steps>
2727

@@ -38,7 +38,7 @@ The server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with
3838
Setup for Claude, Cursor, VS Code, and more.
3939
</Card>
4040
<Card icon="wrench" title="Tools" href="/reference/mcp-server/tools/manage-browsers">
41-
Browsers, profiles, proxies, apps, and more.
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/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: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
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+
## Actions
11+
12+
| Action | Description |
13+
|--------|-------------|
14+
| `create` | Create an org-wide or project-scoped API key. |
15+
| `list` | List masked API keys. |
16+
| `get` | Retrieve one masked API key. |
17+
| `update` | Rename an API key. |
18+
| `delete` | Revoke an API key. |
19+
20+
## Recommended flow
21+
22+
1. Call `list` before creating a key so you don't duplicate an existing workload key.
23+
2. Call `create` with `project_id` for project-scoped automation.
24+
3. Store the returned plaintext key immediately.
25+
4. Call `update` when a key's owner or purpose changes.
26+
5. Call `delete` to revoke keys for retired workloads.
27+
28+
## Parameters
29+
30+
| Parameter | Description |
31+
|-----------|-------------|
32+
| `action` | Operation to perform. Required. |
33+
| `api_key_id` | API key ID. Required for `get`, `update`, and `delete`. |
34+
| `name` | (create, update) API key name. |
35+
| `project_id` | (create) Project ID for project-scoped keys. Omit or use `null` for org-wide keys. |
36+
| `days_to_expire` | (create) Days until expiry, up to 3650. Use `null` for no expiry. |
37+
| `limit` | (list) Max results per page. Must be 1-100. |
38+
| `offset` | (list) Pagination offset. Must be 0 or greater. |
39+
40+
## Create a project-scoped key
41+
42+
```json
43+
{
44+
"action": "create",
45+
"name": "checkout-agent-prod",
46+
"project_id": "proj_2vE0M7bLwX9kQ4nP3sY8",
47+
"days_to_expire": 90
48+
}
49+
```
50+
51+
## Rename a key
52+
53+
```json
54+
{
55+
"action": "update",
56+
"api_key_id": "ak_2vE1qJ7ZpLm8N4cT6rW0",
57+
"name": "checkout-agent-prod-rotated"
58+
}
59+
```

‎reference/mcp-server/tools/manage-apps.mdx‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: "manage_apps"
2+
title: "Manage Apps"
33
description: "List apps, invoke actions, and check deployments and invocations"
44
---
55

6-
Manage Kernel apps, deployments, and invocations.
6+
Use `manage_apps` when an agent needs to run a deployed Kernel app or inspect app deployment state. List apps first when the agent doesn't know the exact app or action name, then invoke the action and poll the invocation result.
77

88
## Actions
99

@@ -15,6 +15,13 @@ Manage Kernel apps, deployments, and invocations.
1515
| `list_deployments` | Check deployment status. |
1616
| `get_invocation` | Check action results. |
1717

18+
## Recommended flow
19+
20+
1. Call `list_apps` to discover available apps and actions.
21+
2. Call `invoke` with `app_name`, `action_name`, and a JSON-string `payload`.
22+
3. Call `get_invocation` with the returned invocation ID when you need the result later.
23+
4. Use `list_deployments` and `get_deployment` when the agent needs deployment status.
24+
1825
## Parameters
1926

2027
| Parameter | Description |
@@ -26,10 +33,10 @@ Manage Kernel apps, deployments, and invocations.
2633
| `version` | (list_apps, invoke) App version filter. Defaults to `latest` for invoke. |
2734
| `deployment_id` | (get_deployment) Deployment ID to retrieve. |
2835
| `invocation_id` | (get_invocation) Invocation ID to retrieve. |
29-
| `limit` | (list_apps, list_deployments) Max results. Default 50. |
30-
| `offset` | (list_apps, list_deployments) Pagination offset. Default 0. |
36+
| `limit` | (list_apps, list_deployments) Max results per page. Must be 1-100. |
37+
| `offset` | (list_apps, list_deployments) Pagination offset. Must be 0 or greater. |
3138

32-
## Example
39+
## Invoke an app
3340

3441
```json
3542
{

‎reference/mcp-server/tools/manage-auth-connections.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: "Manage Auth Connections"
3+
description: "Create and operate managed auth connections for browser profiles"
4+
---
5+
6+
Use `manage_auth_connections` when you want Kernel to keep a browser profile logged in to a third-party site. A connection ties a domain to a profile, then drives login and re-auth flows with stored credentials, external provider credentials, or user-provided input.
7+
8+
This tool is best for recurring workflows where the agent needs durable access to a site but the login flow can require MFA, SSO, or occasional user review.
9+
10+
## Actions
11+
12+
| Action | Description |
13+
|--------|-------------|
14+
| `create` | Start managing auth for a profile and domain. |
15+
| `list` | List auth connections. |
16+
| `get` | Poll one connection or login flow state. |
17+
| `delete` | Remove an auth connection. |
18+
| `login` | Begin a login flow. Returns a hosted URL and live view URL. |
19+
| `submit` | Submit discovered field values, an MFA option, or an SSO button selection. |
20+
21+
## Recommended flow
22+
23+
1. Call `create` with `domain` and `profile_name`.
24+
2. Call `login` to start a login flow.
25+
3. Share the returned hosted URL with the user or watch the returned live view URL.
26+
4. Call `get` to poll flow state and inspect `discovered_fields`.
27+
5. Call `submit` when the flow asks for field values, an MFA option, or an SSO choice.
28+
29+
## Parameters
30+
31+
| Parameter | Description |
32+
|-----------|-------------|
33+
| `action` | Operation to perform. Required. |
34+
| `id` | Auth connection ID. Required for `get`, `delete`, `login`, and `submit`. |
35+
| `domain` | (create) Target domain, such as `netflix.com`. |
36+
| `profile_name` | (create) Profile to manage auth for. Also filters `list`. |
37+
| `allowed_domains` | (create) Additional domains valid for this auth flow. Common SSO providers are allowed by default. |
38+
| `credential_name` | (create) Name of a stored Kernel credential for automatic login. |
39+
| `credential_provider` | (create) External credential provider name, such as `1password`. Use with `credential_path` or `credential_auto`. |
40+
| `credential_path` | (create) Provider-specific item path, such as `Engineering/Netflix Admin`. |
41+
| `credential_auto` | (create) If true, the provider auto-looks up credentials by domain. |
42+
| `login_url` | (create) Explicit login page URL to skip discovery. |
43+
| `health_check_interval` | (create) Seconds between automatic re-auth checks. The max is 86400. |
44+
| `save_credentials` | (create) Save credentials after each successful login. Default true. |
45+
| `proxy_id` / `proxy_name` | (create, login) Proxy to route the auth flow through. |
46+
| `domain_filter` | (list) Filter by domain. |
47+
| `limit` | (list) Max results per page. Must be 1-100. |
48+
| `offset` | (list) Pagination offset. Must be 0 or greater. |
49+
| `fields` | (submit) Map of field name to value, such as `{ "mfa_code": "123456" }`. Check `discovered_fields` from `get`. |
50+
| `mfa_option_id` | (submit) MFA option ID from the connection. |
51+
| `sso_button_selector` | (submit) XPath of an SSO button to click instead of submitting fields. |
52+
53+
## Create a managed login
54+
55+
```json
56+
{
57+
"action": "create",
58+
"domain": "accounts.example.com",
59+
"profile_name": "work-accounts",
60+
"credential_name": "example-work-login",
61+
"login_url": "https://accounts.example.com/login",
62+
"health_check_interval": 3600
63+
}
64+
```
65+
66+
## Submit an MFA code
67+
68+
```json
69+
{
70+
"action": "submit",
71+
"id": "authconn_2vE3Nq8WmY5bL0sC9pR1",
72+
"fields": {
73+
"mfa_code": "123456"
74+
}
75+
}
76+
```

0 commit comments

Comments
 (0)