diff --git a/docs.json b/docs.json index 76480d7..d2a1e98 100644 --- a/docs.json +++ b/docs.json @@ -300,16 +300,48 @@ { "group": "Tools", "pages": [ - "reference/mcp-server/tools/manage-browsers", - "reference/mcp-server/tools/manage-profiles", - "reference/mcp-server/tools/manage-browser-pools", - "reference/mcp-server/tools/manage-proxies", - "reference/mcp-server/tools/manage-extensions", - "reference/mcp-server/tools/manage-apps", - "reference/mcp-server/tools/computer-action", - "reference/mcp-server/tools/execute-playwright-code", - "reference/mcp-server/tools/exec-command", - "reference/mcp-server/tools/search-docs" + "reference/mcp-server/tools", + { + "group": "Browser Control", + "pages": [ + "reference/mcp-server/tools/manage-browsers", + "reference/mcp-server/tools/manage-browser-pools", + "reference/mcp-server/tools/browser-curl", + "reference/mcp-server/tools/computer-action", + "reference/mcp-server/tools/execute-playwright-code", + "reference/mcp-server/tools/exec-command" + ] + }, + { + "group": "Browser Resources", + "pages": [ + "reference/mcp-server/tools/manage-profiles", + "reference/mcp-server/tools/manage-proxies", + "reference/mcp-server/tools/manage-extensions" + ] + }, + { + "group": "Apps & Organization", + "pages": [ + "reference/mcp-server/tools/manage-apps", + "reference/mcp-server/tools/manage-projects", + "reference/mcp-server/tools/manage-api-keys" + ] + }, + { + "group": "Managed Auth", + "pages": [ + "reference/mcp-server/tools/manage-auth-connections", + "reference/mcp-server/tools/manage-credentials", + "reference/mcp-server/tools/manage-credential-providers" + ] + }, + { + "group": "Utilities", + "pages": [ + "reference/mcp-server/tools/search-docs" + ] + } ] }, { diff --git a/reference/mcp-server.mdx b/reference/mcp-server.mdx index b14cffd..527cd58 100644 --- a/reference/mcp-server.mdx +++ b/reference/mcp-server.mdx @@ -21,7 +21,7 @@ The server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with Authorize access through your browser when prompted. See [Authentication](/reference/mcp-server/authentication) for OAuth and API key options. - Use the [tools](/reference/mcp-server/tools/manage-browsers) to launch browsers, run Playwright code, and invoke your apps. + Use the [tools](/reference/mcp-server/tools) to launch browsers, warm browser pools, run Playwright code, invoke your apps, and manage auth workflows. @@ -37,8 +37,8 @@ The server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with Setup for Claude, Cursor, VS Code, and more. - - Browsers, profiles, proxies, apps, and more. + + Browsers, pools, apps, projects, API keys, and managed auth. Read browsers, pools, profiles, and apps. diff --git a/reference/mcp-server/resources.mdx b/reference/mcp-server/resources.mdx index f9ca098..76435fb 100644 --- a/reference/mcp-server/resources.mdx +++ b/reference/mcp-server/resources.mdx @@ -3,11 +3,17 @@ title: "Resources" description: "Read browsers, pools, profiles, and apps as MCP resources" --- -The Kernel MCP server exposes your account's objects as MCP resources. Each resource URI lists all items or returns a specific one. +The Kernel MCP server exposes your account's objects as MCP resources. List URIs return collections, and templated URIs return one object. | Resource | Description | |----------|-------------| -| `browsers://` | Access browser sessions (list all or get a specific session). | -| `browser_pools://` | Access browser pools (list all or get a specific pool). | -| `profiles://` | Access browser profiles (list all or get a specific profile). | -| `apps://` | Access deployed apps (list all or get a specific app). | +| `browsers://` | List browser sessions. | +| `browsers://{sessionId}` | Read one browser session. | +| `browser-pools://` | List browser pools. | +| `browser-pools://{idOrName}` | Read one browser pool by ID or name. | +| `profiles://` | List browser profiles. | +| `profiles://{profileName}` | Read one browser profile by name. | +| `apps://` | List deployed apps. | +| `apps://{appName}` | Read one deployed app by name. | + +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. diff --git a/reference/mcp-server/tools.mdx b/reference/mcp-server/tools.mdx new file mode 100644 index 0000000..c3ebf57 --- /dev/null +++ b/reference/mcp-server/tools.mdx @@ -0,0 +1,85 @@ +--- +title: "Tools" +description: "Choose the right Kernel MCP tool for browser automation, apps, projects, and managed auth" +--- + +Kernel MCP tools let your agent create and control browser sessions, manage reusable browser resources, invoke apps, organize project access, and keep profiles authenticated. + +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. + +## Source of truth + +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. + +## Browser control + + + + Create, update, list, inspect, and delete live browser sessions. + + + Create, resize, acquire from, release to, flush, and delete pre-warmed browser pools. + + + Send HTTP requests through a browser session's cookies, headers, and network path. + + + Move, click, type, scroll, wait, screenshot, and manage clipboard state. + + + Run Playwright code against an existing Kernel browser session. + + + Run shell commands inside the browser VM. + + + +## Browser resources + + + + Set up, list, and delete browser profiles. + + + Create, list, and delete proxy configurations. + + + List and delete browser extensions uploaded to your organization. + + + +## Apps and organization + + + + List apps, invoke actions, inspect deployments, and inspect invocation results. + + + Create, list, inspect, rename, archive, and delete projects. + + + Create, list, inspect, rename, and revoke API keys. + + + +## Managed auth + + + + Create managed auth connections, start login flows, poll state, and submit user input. + + + Store, rotate, inspect, delete, and generate TOTP codes for managed auth credentials. + + + Connect external credential providers and list available provider items. + + + +## Utilities + + + + Search Kernel documentation from your MCP client. + + diff --git a/reference/mcp-server/tools/browser-curl.mdx b/reference/mcp-server/tools/browser-curl.mdx new file mode 100644 index 0000000..9f64698 --- /dev/null +++ b/reference/mcp-server/tools/browser-curl.mdx @@ -0,0 +1,58 @@ +--- +title: "Browser Curl" +description: "Send HTTP requests through an existing browser session" +--- + +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. + +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. + +For documentation lookup or general web search, use `search_docs` or your agent's normal search tool instead. + +## Recommended flow + +1. Use `manage_browsers` or `manage_browser_pools` to get a browser with the right cookies, proxy, and profile. +2. Call `browser_curl` with the returned `session_id`. +3. Use `response_encoding: "base64"` when the response might be binary. +4. Use `execute_playwright_code` instead when you need page JavaScript, DOM state, or user-visible navigation. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `session_id` | Browser session ID. Required. | +| `url` | Target `http` or `https` URL. Required. | +| `method` | HTTP method: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, or `OPTIONS`. Defaults to `GET`. | +| `headers` | Custom headers merged with browser defaults. | +| `body` | Request body for `POST`, `PUT`, or `PATCH` requests. | +| `response_encoding` | Response body encoding: `utf8` or `base64`. Use `base64` for binary content. | +| `timeout_ms` | Request timeout in milliseconds. Must be 1 or greater. | + +## Read an authenticated endpoint + +```json +{ + "session_id": "browser_2vDb5kRmZ4nP8xQ1cA7", + "url": "https://app.example.com/api/account", + "method": "GET", + "headers": { + "Accept": "application/json" + }, + "timeout_ms": 10000 +} +``` + +## Post with browser cookies + +```json +{ + "session_id": "browser_2vDb5kRmZ4nP8xQ1cA7", + "url": "https://app.example.com/api/tasks", + "method": "POST", + "headers": { + "Content-Type": "application/json" + }, + "body": "{\"title\":\"Run nightly checkout audit\"}", + "response_encoding": "utf8" +} +``` diff --git a/reference/mcp-server/tools/computer-action.mdx b/reference/mcp-server/tools/computer-action.mdx index 9f73010..a7142f8 100644 --- a/reference/mcp-server/tools/computer-action.mdx +++ b/reference/mcp-server/tools/computer-action.mdx @@ -1,18 +1,18 @@ --- -title: "computer_action" -description: "Mouse, keyboard, and screenshot controls for browser sessions" +title: "Computer Action" +description: "Mouse, keyboard, clipboard, and screenshot controls for browser sessions" --- -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. +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. -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. +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. ## Parameters | Parameter | Description | |-----------|-------------| | `session_id` | Browser session ID. Required. | -| `actions` | Ordered list of actions to perform. Required. | +| `actions` | Ordered list of one or more actions to perform. Required. | ## Action types @@ -26,10 +26,19 @@ Execute computer actions on a browser session. Pass a single action for simple o | `drag_mouse` | Drag along a `path` of `[x, y]` points. | | `set_cursor` | Show or hide the cursor (`hidden`). | | `sleep` | Wait `duration_ms` between steps when the page needs time to react. | +| `write_clipboard` | Write `text` to the browser session clipboard. | +| `read_clipboard` | Read the browser session clipboard. Must be the last action if included. | | `screenshot` | Capture the page, optionally limited to a `region`. | | `get_mouse_position` | Return the current cursor position. | -## Example +## Recommended flow + +1. Start with `screenshot` so the agent can see the viewport and coordinate space. +2. Batch related pointer and keyboard actions together. +3. Add `sleep` between actions that trigger navigation, animation, or async UI updates. +4. End with `screenshot`, `read_clipboard`, or `get_mouse_position` only when you need returned data. + +## Search from the page ```json { @@ -43,3 +52,18 @@ Execute computer actions on a browser session. Pass a single action for simple o ] } ``` + +## Clipboard example + +```json +{ + "session_id": "browser_2vDb5kRmZ4nP8xQ1cA7", + "actions": [ + { "type": "write_clipboard", "write_clipboard": { "text": "https://kernel.sh/docs" } }, + { "type": "press_key", "press_key": { "keys": ["Ctrl+l"] } }, + { "type": "press_key", "press_key": { "keys": ["Ctrl+v"] } }, + { "type": "press_key", "press_key": { "keys": ["Return"] } }, + { "type": "screenshot" } + ] +} +``` diff --git a/reference/mcp-server/tools/exec-command.mdx b/reference/mcp-server/tools/exec-command.mdx index c2138c1..981f9fe 100644 --- a/reference/mcp-server/tools/exec-command.mdx +++ b/reference/mcp-server/tools/exec-command.mdx @@ -1,9 +1,9 @@ --- -title: "exec_command" +title: "Exec Command" description: "Run shell commands inside a browser VM" --- -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`. +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`. ## Parameters diff --git a/reference/mcp-server/tools/execute-playwright-code.mdx b/reference/mcp-server/tools/execute-playwright-code.mdx index 7152515..4394d41 100644 --- a/reference/mcp-server/tools/execute-playwright-code.mdx +++ b/reference/mcp-server/tools/execute-playwright-code.mdx @@ -1,9 +1,9 @@ --- -title: "execute_playwright_code" +title: "Execute Playwright Code" description: "Run Playwright/TypeScript code against a browser session" --- -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. +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. Use `computer_action` with the `screenshot` action instead of `page.screenshot()` in your code. For a comprehensive page state snapshot, use `await page._snapshotForAI()`. diff --git a/reference/mcp-server/tools/manage-api-keys.mdx b/reference/mcp-server/tools/manage-api-keys.mdx new file mode 100644 index 0000000..5d6e3af --- /dev/null +++ b/reference/mcp-server/tools/manage-api-keys.mdx @@ -0,0 +1,61 @@ +--- +title: "Manage API Keys" +description: "Create, list, update, and revoke Kernel API keys" +--- + +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. + +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. + +For API key concepts, scoping rules, rotation guidance, and SDK examples, see [API Keys](/info/api-keys). + +## Actions + +| Action | Description | +|--------|-------------| +| `create` | Create an org-wide or project-scoped API key. | +| `list` | List masked API keys. | +| `get` | Retrieve one masked API key. | +| `update` | Rename an API key. | +| `delete` | Revoke an API key. | + +## Recommended flow + +1. Call `list` before creating a key so you don't duplicate an existing workload key. +2. Call `create` with `project_id` for project-scoped automation. +3. Store the returned plaintext key immediately. +4. Call `update` when a key's owner or purpose changes. +5. Call `delete` to revoke keys for retired workloads. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform. Required. | +| `api_key_id` | API key ID. Required for `get`, `update`, and `delete`. | +| `name` | (create, update) API key name. | +| `project_id` | (create) Project ID for project-scoped keys. Omit or use `null` for org-wide keys. | +| `days_to_expire` | (create) Days until expiry, up to 3650. Use `null` for no expiry. | +| `limit` | (list) Max results per page. Must be 1-100. | +| `offset` | (list) Pagination offset. Must be 0 or greater. | + +## Create a project-scoped key + +```json +{ + "action": "create", + "name": "checkout-agent-prod", + "project_id": "proj_2vE0M7bLwX9kQ4nP3sY8", + "days_to_expire": 90 +} +``` + +## Rename a key + +```json +{ + "action": "update", + "api_key_id": "ak_2vE1qJ7ZpLm8N4cT6rW0", + "name": "checkout-agent-prod-rotated" +} +``` diff --git a/reference/mcp-server/tools/manage-apps.mdx b/reference/mcp-server/tools/manage-apps.mdx index 7e0c082..208eaee 100644 --- a/reference/mcp-server/tools/manage-apps.mdx +++ b/reference/mcp-server/tools/manage-apps.mdx @@ -1,9 +1,9 @@ --- -title: "manage_apps" +title: "Manage Apps" description: "List apps, invoke actions, and check deployments and invocations" --- -Manage Kernel apps, deployments, and invocations. +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. ## Actions @@ -15,6 +15,13 @@ Manage Kernel apps, deployments, and invocations. | `list_deployments` | Check deployment status. | | `get_invocation` | Check action results. | +## Recommended flow + +1. Call `list_apps` to discover available apps and actions. +2. Call `invoke` with `app_name`, `action_name`, and a JSON-string `payload`. +3. Call `get_invocation` with the returned invocation ID when you need the result later. +4. Use `list_deployments` and `get_deployment` when the agent needs deployment status. + ## Parameters | Parameter | Description | @@ -26,10 +33,10 @@ Manage Kernel apps, deployments, and invocations. | `version` | (list_apps, invoke) App version filter. Defaults to `latest` for invoke. | | `deployment_id` | (get_deployment) Deployment ID to retrieve. | | `invocation_id` | (get_invocation) Invocation ID to retrieve. | -| `limit` | (list_apps, list_deployments) Max results. Default 50. | -| `offset` | (list_apps, list_deployments) Pagination offset. Default 0. | +| `limit` | (list_apps, list_deployments) Max results per page. Must be 1-100. | +| `offset` | (list_apps, list_deployments) Pagination offset. Must be 0 or greater. | -## Example +## Invoke an app ```json { diff --git a/reference/mcp-server/tools/manage-auth-connections.mdx b/reference/mcp-server/tools/manage-auth-connections.mdx new file mode 100644 index 0000000..a105405 --- /dev/null +++ b/reference/mcp-server/tools/manage-auth-connections.mdx @@ -0,0 +1,78 @@ +--- +title: "Manage Auth Connections" +description: "Create and operate managed auth connections for browser profiles" +--- + +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. + +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. + +For managed auth concepts, profile lifecycle, and SDK flows, see [Managed Auth](/auth/overview) and [Programmatic](/auth/programmatic). + +## Actions + +| Action | Description | +|--------|-------------| +| `create` | Start managing auth for a profile and domain. | +| `list` | List auth connections. | +| `get` | Poll one connection or login flow state. | +| `delete` | Remove an auth connection. | +| `login` | Begin a login flow. Returns a hosted URL and live view URL. | +| `submit` | Submit discovered field values, an MFA option, or an SSO button selection. | + +## Recommended flow + +1. Call `create` with `domain` and `profile_name`. +2. Call `login` to start a login flow. +3. Share the returned hosted URL with the user or watch the returned live view URL. +4. Call `get` to poll flow state and inspect `discovered_fields`. +5. Call `submit` when the flow asks for field values, an MFA option, or an SSO choice. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform. Required. | +| `id` | Auth connection ID. Required for `get`, `delete`, `login`, and `submit`. | +| `domain` | (create) Target domain, such as `netflix.com`. | +| `profile_name` | (create) Profile to manage auth for. Also filters `list`. | +| `allowed_domains` | (create) Additional domains valid for this auth flow. Common SSO providers are allowed by default. | +| `credential_name` | (create) Name of a stored Kernel credential for automatic login. | +| `credential_provider` | (create) External credential provider name, such as `1password`. Use with `credential_path` or `credential_auto`. | +| `credential_path` | (create) Provider-specific item path, such as `Engineering/Netflix Admin`. | +| `credential_auto` | (create) If true, the provider auto-looks up credentials by domain. | +| `login_url` | (create) Explicit login page URL to skip discovery. | +| `health_check_interval` | (create) Seconds between automatic re-auth checks. The max is 86400. | +| `save_credentials` | (create) Save credentials after each successful login. Default true. | +| `proxy_id` / `proxy_name` | (create, login) Proxy to route the auth flow through. | +| `domain_filter` | (list) Filter by domain. | +| `limit` | (list) Max results per page. Must be 1-100. | +| `offset` | (list) Pagination offset. Must be 0 or greater. | +| `fields` | (submit) Map of field name to value, such as `{ "mfa_code": "123456" }`. Check `discovered_fields` from `get`. | +| `mfa_option_id` | (submit) MFA option ID from the connection. | +| `sso_button_selector` | (submit) XPath of an SSO button to click instead of submitting fields. | + +## Create a managed login + +```json +{ + "action": "create", + "domain": "accounts.example.com", + "profile_name": "work-accounts", + "credential_name": "example-work-login", + "login_url": "https://accounts.example.com/login", + "health_check_interval": 3600 +} +``` + +## Submit an MFA code + +```json +{ + "action": "submit", + "id": "authconn_2vE3Nq8WmY5bL0sC9pR1", + "fields": { + "mfa_code": "123456" + } +} +``` diff --git a/reference/mcp-server/tools/manage-browser-pools.mdx b/reference/mcp-server/tools/manage-browser-pools.mdx index b794b99..7ea886e 100644 --- a/reference/mcp-server/tools/manage-browser-pools.mdx +++ b/reference/mcp-server/tools/manage-browser-pools.mdx @@ -1,15 +1,22 @@ --- -title: "manage_browser_pools" +title: "Manage Browser Pools" description: "Create and manage pools of pre-warmed browsers" --- -Manage pools of pre-warmed browser instances for fast acquisition. +Use `manage_browser_pools` when your agent needs the same browser setup more than once. A pool keeps pre-warmed browsers ready with the profile, viewport, proxy, extension, Chrome policy, and start URL you choose, so the agent can acquire a session without waiting for a fresh browser to boot. + +Create the pool outside the hot path of your agent workflow. During the task, acquire a browser, control it with `computer_action` or `execute_playwright_code`, then release it back to the pool when the browser can be reused. + + +Browser pools are available on Start-Up and Enterprise plans. See [Pricing](/info/pricing#reserved-browsers-browser-pools) for availability and [Browser Pools](/browsers/pools/overview) for SDK examples. + ## Actions | Action | Description | |--------|-------------| | `create` | Set up a pool. | +| `update` | Change pool configuration or rebuild idle browsers. | | `list` | List pools. | | `get` | Inspect a specific pool. | | `acquire` | Get a browser from a pool. | @@ -17,32 +24,93 @@ Manage pools of pre-warmed browser instances for fast acquisition. | `flush` | Destroy idle browsers in a pool. | | `delete` | Remove a pool. | +## Recommended flow + +1. Call `create` with the browser configuration your repeated task needs. +2. Call `list` to find an existing pool, or `get` when you need the full pool configuration. +3. Call `acquire` before browser control. +4. Use the returned `session_id` with `computer_action`, `execute_playwright_code`, `browser_curl`, or `exec_command`. +5. Call `release` with `reuse: true` when the session can return to the pool, or `reuse: false` when it needs to be replaced. +6. Call `update` when you need to resize the pool or change its browser configuration. + ## Parameters | Parameter | Description | |-----------|-------------| | `action` | Operation to perform. Required. | -| `id_or_name` | Pool ID or name. Required for `get`, `delete`, `flush`, `acquire`, and `release`. | -| `name` | (create) Unique pool name. | -| `size` | (create) Number of browsers to maintain in the pool. | -| `fill_rate_per_minute` | (create) Pool fill rate percentage per minute. Default 10%. | -| `headless` | (create) Headless mode for pool browsers. | -| `stealth` | (create) Stealth mode for pool browsers. | -| `profile_name` | (create) Profile to load into pool browsers. | -| `proxy_id` | (create) Proxy for pool browsers. | -| `timeout_seconds` | (create) Idle timeout for acquired browsers. Default 600. | +| `id_or_name` | Pool ID or name. Required for `update`, `get`, `delete`, `flush`, `acquire`, and `release`. | +| `name` | (create, update) Unique pool name. | +| `size` | (create, update) Number of browsers to maintain. Required for `create`; optional for `update`. | +| `fill_rate_per_minute` | (create, update) Pool fill rate percentage per minute. Default 10%. | +| `headless` | (create, update) Headless mode for pool browsers. | +| `stealth` | (create, update) Stealth mode for pool browsers. | +| `timeout_seconds` | (create, update) Idle timeout for acquired browsers. Default 600. | +| `start_url` | (create, update) URL to open when a browser is warmed into the pool. Navigation is best effort. | +| `chrome_policy` | (create, update) Chrome enterprise policy overrides. The API blocks Kernel-managed policies such as extensions, proxy, CDP, and automation. Empty objects are ignored. | +| `kiosk_mode` | (create, update) Hide address bar and tabs in live view. | +| `profile_name` / `profile_id` | (create, update) Profile to load into pool browsers. Use one, not both. | +| `save_profile_changes` | (create, update) Save session changes back to the selected profile when sessions end. | +| `proxy_id` | (create, update) Proxy for pool browsers. | +| `extension_id` / `extension_name` | (create, update) Extension to load. Use one, not both. | +| `viewport_width` / `viewport_height` | (create, update) Window size in pixels. Set both values together. | +| `viewport_refresh_rate` | (create, update) Display refresh rate in Hz. | +| `discard_all_idle` | (update) Discard idle browsers and rebuild the pool immediately. | | `acquire_timeout_seconds` | (acquire) Max seconds to wait for a browser. | | `session_id` | (release) Session ID of the browser to release. | | `reuse` | (release) Reuse the browser instance or recreate it. Default true. | | `force` | (delete) Force delete even if browsers are leased. | -## Example +## Response behavior + +`create` and `update` return a compact `browser_pool` summary plus `next_actions`. The next actions use the stable pool `id`, so agents can follow up without relying on the display name. + +`list` returns compact pool summaries and a note to call `get` for full details. `acquire` returns a compact browser summary plus next actions for controlling, releasing, and inspecting the acquired browser. + +## Create a checkout pool ```json { "action": "create", - "name": "scrape-pool", + "name": "retail-checkout-pool", "size": 5, - "stealth": true + "stealth": true, + "profile_id": "prof_2uWzXn7J8mY4kQpR6sT1", + "start_url": "https://shop.example.com/login", + "extension_name": "checkout-helper", + "viewport_width": 1440, + "viewport_height": 900, + "chrome_policy": { + "HomepageLocation": "https://shop.example.com" + } +} +``` + +## Update idle capacity + +```json +{ + "action": "update", + "id_or_name": "pool_2vDaXqN9R1pL0tZ8YhK4", + "size": 8, + "discard_all_idle": true +} +``` + +## Acquire and release a browser + +```json +{ + "action": "acquire", + "id_or_name": "pool_2vDaXqN9R1pL0tZ8YhK4", + "acquire_timeout_seconds": 30 +} +``` + +```json +{ + "action": "release", + "id_or_name": "pool_2vDaXqN9R1pL0tZ8YhK4", + "session_id": "browser_2vDb5kRmZ4nP8xQ1cA7", + "reuse": true } ``` diff --git a/reference/mcp-server/tools/manage-browsers.mdx b/reference/mcp-server/tools/manage-browsers.mdx index 5cf3816..56947b4 100644 --- a/reference/mcp-server/tools/manage-browsers.mdx +++ b/reference/mcp-server/tools/manage-browsers.mdx @@ -1,48 +1,95 @@ --- -title: "manage_browsers" +title: "Manage Browsers" description: "Create, list, get, and delete browser sessions" --- -Manage browser sessions on the Kernel platform. Created browsers run in isolated VMs and support headless/stealth modes, profiles, proxies, viewports, extensions, and SSH tunneling. +Use `manage_browsers` when your agent needs one live browser session to inspect, automate, or debug web state. A created browser runs in an isolated VM and can use profiles, proxies, viewports, extensions, Chrome policy overrides, telemetry, start URLs, and SSH tunneling. + +For repeated browser work with the same configuration, use [Manage Browser Pools](/reference/mcp-server/tools/manage-browser-pools) instead. Pools reduce startup latency when your agent needs many similar sessions. ## Actions | Action | Description | |--------|-------------| | `create` | Launch a new browser session. | +| `update` | Change supported session settings. | | `list` | List existing sessions. | | `get` | Retrieve details about a specific session. | | `delete` | Terminate a session. | +## Recommended flow + +1. Call `list` before creating a browser if an existing session might already be active. +2. Call `create` with the browser configuration the task needs. +3. Use `computer_action`, `execute_playwright_code`, `browser_curl`, or `exec_command` with the returned `session_id`. +4. Call `update` only for session settings that can change after launch, such as profile, proxy, viewport, or telemetry. +5. Call `delete` when the task is done. If `save_profile_changes` is enabled, deleting the browser saves changes back to the selected profile. + ## Parameters | Parameter | Description | |-----------|-------------| -| `action` | Operation to perform: `create`, `list`, `get`, or `delete`. Required. | -| `session_id` | Browser session ID. Required for `get` and `delete`. | +| `action` | Operation to perform: `create`, `update`, `list`, `get`, or `delete`. Required. | +| `session_id` | Browser session ID. Required for `update`, `get`, and `delete`. | +| `start_url` | (create) URL to open when the browser is created. Navigation is best effort. | +| `chrome_policy` | (create) Chrome enterprise policy overrides. The API blocks Kernel-managed policies such as extensions, proxy, CDP, and automation. Empty objects are ignored. | | `headless` | (create) Launch without GUI. Faster but no live view. | +| `gpu` | (create) Enable GPU acceleration. Requires `headless=false` and a Start-Up or Enterprise plan. See [GPU Acceleration](/browsers/gpu-acceleration). | | `stealth` | (create) Avoid bot detection. Recommended for scraping. | | `kiosk_mode` | (create) Hide address bar/tabs in live view. | -| `profile_id` / `profile_name` | (create) Profile to load saved cookies/logins. Use one, not both. | -| `save_profile_changes` | (create) Save session changes back to the profile on close. | -| `proxy_id` | (create) Proxy ID for traffic routing. | +| `profile_id` / `profile_name` | (create, update) Profile to load saved cookies and logins. Use one, not both. | +| `save_profile_changes` | (create, update) Save session changes back to the profile on close. | +| `proxy_id` | (create, update) Proxy ID for traffic routing. | +| `clear_proxy` | (update) Remove the current proxy from the browser session. | +| `disable_default_proxy` | (update) For stealth browsers, connect directly instead of using the default stealth proxy. | | `extension_id` / `extension_name` | (create) Extension to load. | -| `viewport_width` / `viewport_height` | (create) Window size in pixels. Must be set together. | -| `viewport_refresh_rate` | (create) Display refresh rate in Hz. | +| `viewport_width` / `viewport_height` | (create, update) Window size in pixels. Set both values together. | +| `viewport_refresh_rate` | (create, update) Display refresh rate in Hz. | +| `viewport_force` | (update) Force viewport changes even when live view or recording is active. | | `timeout_seconds` | (create) Inactivity timeout in seconds (max 259200 = 72h). Default 60. | | `local_forward` | (create) SSH local forwarding (`localport:host:remoteport`). | | `remote_forward` | (create) SSH remote forwarding (`remoteport:host:localport`). Use to expose a local dev server to the browser. | | `status` | (list) Filter by status: `active`, `deleted`, or `all`. Default `active`. | -| `limit` | (list) Max results per page. Default 50. | -| `offset` | (list) Pagination offset. Default 0. | +| `limit` | (list) Max results per page. Must be 1-100. | +| `offset` | (list) Pagination offset. Must be 0 or greater. | +| `telemetry_enabled` | (create, update) Enable telemetry with VM defaults, or disable telemetry when false. | +| `telemetry_console` | (create, update) Enable or disable console telemetry. | +| `telemetry_network` | (create, update) Enable or disable network telemetry. | +| `telemetry_page` | (create, update) Enable or disable page lifecycle telemetry. | +| `telemetry_interaction` | (create, update) Enable or disable user interaction telemetry. | + +## Response behavior + +`create` and `update` return structured JSON with `browser` and `next_actions`. If you request SSH forwarding, the response includes `ssh_port_forwarding` with the CLI command, prerequisites, and the URL to use after the tunnel is running. + +`list` returns compact browser summaries and omits routine connection details such as `cdp_ws_url`. Use `get` with `session_id` when your agent needs full details. -## Example +## Create a browser ```json { "action": "create", "stealth": true, "proxy_id": "proxy_residential_us", + "profile_name": "work-accounts", + "save_profile_changes": true, + "start_url": "https://app.example.com/dashboard", + "viewport_width": 1440, + "viewport_height": 900, + "telemetry_network": true, "timeout_seconds": 3600 } ``` + +## Update a browser + +```json +{ + "action": "update", + "session_id": "browser_2vDb5kRmZ4nP8xQ1cA7", + "viewport_width": 1280, + "viewport_height": 720, + "viewport_force": true, + "clear_proxy": true +} +``` diff --git a/reference/mcp-server/tools/manage-credential-providers.mdx b/reference/mcp-server/tools/manage-credential-providers.mdx new file mode 100644 index 0000000..afe4720 --- /dev/null +++ b/reference/mcp-server/tools/manage-credential-providers.mdx @@ -0,0 +1,63 @@ +--- +title: "Manage Credential Providers" +description: "Connect external credential providers for managed auth" +--- + +Use `manage_credential_providers` when your organization already stores login credentials in an external vault. Kernel can reference provider items during managed auth flows without storing the secret values directly in Kernel. + +The current provider type is `onepassword`. After you create a provider, use `list_items` to find the provider-specific credential paths that can be passed to `manage_auth_connections`. + +For 1Password setup and service-account requirements, see [1Password Integration](/integrations/1password). + +## Actions + +| Action | Description | +|--------|-------------| +| `list` | List configured providers. | +| `get` | Retrieve one provider by ID. | +| `create` | Configure a provider with a service-account token. | +| `update` | Change provider name, token, priority, enabled state, or cache TTL. | +| `delete` | Remove a provider. | +| `list_items` | List available credential items from the provider. | +| `test` | Validate the provider token and list accessible vaults. | + +## Recommended flow + +1. Call `create` with a service-account token for the provider. +2. Call `test` to confirm Kernel can access the vaults you expect. +3. Call `list_items` to discover credential item paths. +4. Use `credential_provider` with either `credential_path` or `credential_auto` when creating an auth connection. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform. Required. | +| `id` | Credential provider ID. Required for `get`, `update`, `delete`, `list_items`, and `test`. | +| `name` | (create, update) Human-readable provider name. Must be unique per organization. | +| `token` | (create) Service-account token. (update) New token to rotate credentials. | +| `provider_type` | (create) Provider type. Currently `onepassword`. | +| `cache_ttl_seconds` | (create, update) How long to cache credential lists. Default 300. | +| `enabled` | (update) Whether the provider is enabled for credential lookups. | +| `priority` | (update) Priority order for credential lookups. Lower numbers are checked first. | + +## Create a 1Password provider + +```json +{ + "action": "create", + "name": "engineering-1password", + "provider_type": "onepassword", + "token": "fake-1password-service-account-token", + "cache_ttl_seconds": 300 +} +``` + +## List provider items + +```json +{ + "action": "list_items", + "id": "credprov_2vE4bN8xLmQ1pR6sT0Y3" +} +``` diff --git a/reference/mcp-server/tools/manage-credentials.mdx b/reference/mcp-server/tools/manage-credentials.mdx new file mode 100644 index 0000000..f91cdf5 --- /dev/null +++ b/reference/mcp-server/tools/manage-credentials.mdx @@ -0,0 +1,66 @@ +--- +title: "Manage Credentials" +description: "Store and manage credentials for Kernel managed auth" +--- + +Use `manage_credentials` when managed auth needs a username, password, or TOTP secret that Kernel can supply during login. Credential values are never returned by `get`; reads return metadata only. + +Store credentials here when you want Kernel to own the secret material. If your team already keeps secrets in an external vault, use [Manage Credential Providers](/reference/mcp-server/tools/manage-credential-providers) instead. + +For credential concepts and field types, see [Credentials](/auth/credentials). + +## Actions + +| Action | Description | +|--------|-------------| +| `list` | Discover credentials, optionally filtered by domain. | +| `get` | Return credential metadata. | +| `totp_code` | Return the current 6-digit TOTP code for credentials with a configured TOTP secret. | +| `create` | Store a new credential. | +| `update` | Rename a credential or merge new values. | +| `delete` | Remove a credential by ID or name. | + +## Recommended flow + +1. Call `create` with the domain, a stable name, and the credential fields. +2. Use the credential name in `manage_auth_connections` when creating a managed login. +3. Call `totp_code` only when the agent needs the current code for a manual step. +4. Call `update` to rotate values or clear optional fields. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform. Required. | +| `id_or_name` | (get, totp_code, update, delete) Credential ID or name. | +| `domain` | (list) Filter by domain. (create) Target domain this credential is for. | +| `name` | (create) Unique credential name. (update) New name. | +| `values` | (create, update) Field name to value mapping, such as `username` and `password`. On update, values merge with existing values. | +| `sso_provider` | (create, update) SSO provider, such as `google`, `github`, or `microsoft`. On update, an empty string clears it. | +| `totp_secret` | (create, update) Base32-encoded TOTP secret for automatic 2FA. On update, an empty string clears it. | +| `limit` | (list) Max results per page. Must be 1-100. | +| `offset` | (list) Pagination offset. Must be 0 or greater. | + +## Create a login credential + +```json +{ + "action": "create", + "domain": "accounts.example.com", + "name": "example-work-login", + "values": { + "username": "ops@example.com", + "password": "fake-password-for-docs" + }, + "totp_secret": "JBSWY3DPEHPK3PXP" +} +``` + +## Get a TOTP code + +```json +{ + "action": "totp_code", + "id_or_name": "example-work-login" +} +``` diff --git a/reference/mcp-server/tools/manage-extensions.mdx b/reference/mcp-server/tools/manage-extensions.mdx index b2a27e8..326a338 100644 --- a/reference/mcp-server/tools/manage-extensions.mdx +++ b/reference/mcp-server/tools/manage-extensions.mdx @@ -1,9 +1,9 @@ --- -title: "manage_extensions" +title: "Manage Extensions" description: "List and delete uploaded browser extensions" --- -Manage browser extensions uploaded to your organization. +Use `manage_extensions` to list and delete browser extensions uploaded to your organization. ## Actions diff --git a/reference/mcp-server/tools/manage-profiles.mdx b/reference/mcp-server/tools/manage-profiles.mdx index ab8cbd9..047b7a9 100644 --- a/reference/mcp-server/tools/manage-profiles.mdx +++ b/reference/mcp-server/tools/manage-profiles.mdx @@ -1,9 +1,11 @@ --- -title: "manage_profiles" +title: "Manage Profiles" description: "Set up, list, and delete browser profiles" --- -Manage browser profiles that persist cookies, logins, and session data across browser sessions. +Use `manage_profiles` when a browser needs saved login state across sessions. A profile persists cookies and session data, so your agent can reuse authenticated state instead of asking the user to sign in every time. + +For profile concepts and SDK examples, see [Profiles](/auth/profiles). ## Actions @@ -13,6 +15,13 @@ Manage browser profiles that persist cookies, logins, and session data across br | `list` | List all profiles. | | `delete` | Remove a profile. | +## Recommended flow + +1. Call `setup` with a memorable `profile_name`. +2. Open the returned live view URL and sign in to the target accounts. +3. Delete the setup browser when you're done so Kernel saves the profile changes. +4. Use `profile_name` or `profile_id` with `manage_browsers` or `manage_browser_pools` when launching future sessions. + ## Parameters | Parameter | Description | @@ -21,8 +30,15 @@ Manage browser profiles that persist cookies, logins, and session data across br | `profile_name` | (setup, delete) Profile name. For setup: 1–255 chars. For delete: name of the profile to remove. | | `profile_id` | (delete) Profile ID to delete. Alternative to `profile_name`. | | `update_existing` | (setup) If true, update an existing profile. Default false. | +| `query` | (list) Search profiles by name or ID. | +| `limit` | (list) Max results per page. Must be 1-100. | +| `offset` | (list) Pagination offset. Must be 0 or greater. | -## Example +## Response behavior + +By default, `list` returns the full matching profile inventory so agents can choose a profile without paging. When you pass `limit` or `offset`, `list` returns structured pagination JSON with `items`, `has_more`, and `next_offset`, including explicit empty pages. + +## Set up a profile ```json { @@ -30,3 +46,14 @@ Manage browser profiles that persist cookies, logins, and session data across br "profile_name": "work-accounts" } ``` + +## Search profiles + +```json +{ + "action": "list", + "query": "work", + "limit": 20, + "offset": 0 +} +``` diff --git a/reference/mcp-server/tools/manage-projects.mdx b/reference/mcp-server/tools/manage-projects.mdx new file mode 100644 index 0000000..5edc6dd --- /dev/null +++ b/reference/mcp-server/tools/manage-projects.mdx @@ -0,0 +1,59 @@ +--- +title: "Manage Projects" +description: "Create, list, update, and delete Kernel projects" +--- + +Use `manage_projects` to manage resource isolation inside one Kernel organization. Projects let agents create scoped API keys and organize workloads without switching organizations. + +Create a project before provisioning project-scoped keys or grouping browser automation resources by environment, customer, or workflow. + +For project concepts, request scoping, and SDK examples, see [Projects](/info/projects). + +## Actions + +| Action | Description | +|--------|-------------| +| `create` | Create a project. | +| `list` | Discover projects. | +| `get` | Retrieve one project. | +| `update` | Rename or archive a project. | +| `delete` | Delete an empty project. | + +## Recommended flow + +1. Call `list` with `query` to check whether the project already exists. +2. Call `create` for a new workload or environment. +3. Use the returned `project_id` when creating project-scoped API keys. +4. Call `update` with `status: "archived"` when the project is no longer active. +5. Call `delete` only after project resources have been removed. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform. Required. | +| `project_id` | Project ID. Required for `get`, `update`, and `delete`. | +| `name` | (create, update) Project name. | +| `status` | (update) Project status: `active` or `archived`. | +| `query` | (list) Case-insensitive substring match against project name. | +| `limit` | (list) Max results per page. Must be 1-100. | +| `offset` | (list) Pagination offset. Must be 0 or greater. | + +## Create a project + +```json +{ + "action": "create", + "name": "checkout-agent-prod" +} +``` + +## Archive a project + +```json +{ + "action": "update", + "project_id": "proj_2vE0M7bLwX9kQ4nP3sY8", + "status": "archived" +} +``` diff --git a/reference/mcp-server/tools/manage-proxies.mdx b/reference/mcp-server/tools/manage-proxies.mdx index 1392854..53eb8c3 100644 --- a/reference/mcp-server/tools/manage-proxies.mdx +++ b/reference/mcp-server/tools/manage-proxies.mdx @@ -1,9 +1,9 @@ --- -title: "manage_proxies" +title: "Manage Proxies" description: "Create, list, and delete proxy configurations" --- -Manage proxy configurations for routing browser traffic. Proxy quality for bot detection avoidance, best to worst: mobile > residential > ISP > datacenter. +Use `manage_proxies` to create, list, and delete proxy configurations for browser traffic. Proxy quality for bot detection avoidance, best to worst, is mobile > residential > ISP > datacenter. ## Actions diff --git a/reference/mcp-server/tools/search-docs.mdx b/reference/mcp-server/tools/search-docs.mdx index 91789e4..f747eda 100644 --- a/reference/mcp-server/tools/search-docs.mdx +++ b/reference/mcp-server/tools/search-docs.mdx @@ -1,9 +1,9 @@ --- -title: "search_docs" +title: "Search Docs" description: "Search Kernel platform documentation and guides" --- -Search Kernel platform documentation for guides, tutorials, and API references. Use it when you need to understand how Kernel features work or to troubleshoot issues. +Use `search_docs` to search Kernel platform documentation for guides, tutorials, and API references. Use it when you need to understand how Kernel features work or troubleshoot issues. ## Parameters