From b180f7ab7302d4131f97f8b7a1cab6a9d2e19a31 Mon Sep 17 00:00:00 2001 From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com> Date: Thu, 6 Aug 2026 16:59:15 -0400 Subject: [PATCH 1/4] document durable MCP tool contracts --- .../mcp-server/tools/manage-browser-pools.mdx | 30 +++++++++++++------ .../mcp-server/tools/manage-profiles.mdx | 15 +++++++--- reference/mcp-server/tools/manage-proxies.mdx | 12 +++++--- 3 files changed, 40 insertions(+), 17 deletions(-) diff --git a/reference/mcp-server/tools/manage-browser-pools.mdx b/reference/mcp-server/tools/manage-browser-pools.mdx index e0449b25..607dfb84 100644 --- a/reference/mcp-server/tools/manage-browser-pools.mdx +++ b/reference/mcp-server/tools/manage-browser-pools.mdx @@ -10,6 +10,7 @@ Manage pools of pre-provisioned browser instances for fast acquisition. | Action | Description | |--------|-------------| | `create` | Set up a pool. | +| `update` | Change a pool's configuration. | | `list` | List pools. | | `get` | Inspect a specific pool. | | `acquire` | Get a browser from a pool. | @@ -22,20 +23,31 @@ Manage pools of pre-provisioned browser instances for fast acquisition. | 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 `get`, `update`, `delete`, `flush`, `acquire`, and `release`. | +| `name` | (create, update) Unique pool name. | +| `size` | (create, update) Number of browsers to maintain in the pool. | +| `fill_rate_per_minute` | (create, update) Integer pool fill rate percentage per minute. Default 25; use `0` to pause filling. | +| `headless` | (create, update) Headless mode for pool browsers. | +| `stealth` | (create, update) Stealth mode for pool browsers. | +| `profile_id` or `profile_name` | (create, update) Profile to load into pool browsers. | +| `clear_profile` | (update) Remove the pool's profile. Cannot be combined with `profile_id` or `profile_name`. | +| `proxy_id` | (create, update) Proxy for pool browsers. On update, pass an empty string to clear it. | +| `start_url` | (create, update) URL to open when a browser is warmed into the pool. On update, pass an empty string to clear it. | +| `extension_id` or `extension_name` | (create, update) Extension to load into pool browsers. | +| `clear_extensions` | (update) Remove all pool extensions. Cannot be combined with `extension_id` or `extension_name`. | +| `chrome_policy` | (create, update) Chrome enterprise policy overrides. On update, pass an empty object to clear it. | +| `kiosk_mode` | (create, update) Hide the address bar and tabs in live view. | +| `viewport_width` and `viewport_height` | (create, update) Window dimensions in pixels. Supply both together. | +| `viewport_refresh_rate` | (create, update) Display refresh rate in Hz. | +| `timeout_seconds` | (create, update) Idle timeout for acquired browsers. Must be between 10 and 259200 seconds. Default 600. | +| `discard_all_idle` | (update) Discard all idle browsers after applying the configuration. | | `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. | +`get`, `create`, and `update` responses report the authoritative `profile_id` and `extension_ids` stored on the pool. + ## Example ```json diff --git a/reference/mcp-server/tools/manage-profiles.mdx b/reference/mcp-server/tools/manage-profiles.mdx index ab8cbd95..71b00fac 100644 --- a/reference/mcp-server/tools/manage-profiles.mdx +++ b/reference/mcp-server/tools/manage-profiles.mdx @@ -1,6 +1,6 @@ --- title: "manage_profiles" -description: "Set up, list, and delete browser profiles" +description: "Set up, retrieve, rename, and delete browser profiles" --- Manage browser profiles that persist cookies, logins, and session data across browser sessions. @@ -11,17 +11,24 @@ Manage browser profiles that persist cookies, logins, and session data across br |--------|-------------| | `setup` | Create or update a profile with a guided live browser session. | | `list` | List all profiles. | +| `get` | Retrieve a profile by ID or exact name. | +| `rename` | Change a profile's name. | | `delete` | Remove a profile. | ## Parameters | Parameter | Description | |-----------|-------------| -| `action` | Operation to perform: `setup`, `list`, or `delete`. Required. | -| `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`. | +| `action` | Operation to perform: `setup`, `list`, `get`, `rename`, or `delete`. Required. | +| `profile_name` | (setup, get, rename, delete) Exact profile name. For setup: 1–255 chars. | +| `profile_id` | (get, rename, delete) Profile ID. Alternative to `profile_name`. | +| `new_name` | (rename) New profile name. | | `update_existing` | (setup) If true, update an existing profile. Default false. | +Name-based setup uses an exact match. If more than one profile has the same name, rename or delete duplicate profiles by ID, then retry setup. With `update_existing: true`, setup fails instead of creating a profile when no exact match exists. + +Do not rename a profile while a browser is using it. The active session may no longer be able to save changes back to that profile. + ## Example ```json diff --git a/reference/mcp-server/tools/manage-proxies.mdx b/reference/mcp-server/tools/manage-proxies.mdx index 1392854b..b2cae8af 100644 --- a/reference/mcp-server/tools/manage-proxies.mdx +++ b/reference/mcp-server/tools/manage-proxies.mdx @@ -1,6 +1,6 @@ --- title: "manage_proxies" -description: "Create, list, and delete proxy configurations" +description: "Create, retrieve, rename, check, and delete proxy configurations" --- Manage proxy configurations for routing browser traffic. Proxy quality for bot detection avoidance, best to worst: mobile > residential > ISP > datacenter. @@ -11,15 +11,18 @@ Manage proxy configurations for routing browser traffic. Proxy quality for bot d |--------|-------------| | `create` | Add a proxy. | | `list` | List all proxies. | +| `get` | Retrieve a proxy by ID. | +| `rename` | Change a proxy's name. | +| `check` | Test proxy connectivity. | | `delete` | Remove a proxy. | ## Parameters | Parameter | Description | |-----------|-------------| -| `action` | Operation to perform: `create`, `list`, or `delete`. Required. | +| `action` | Operation to perform: `create`, `list`, `get`, `rename`, `check`, or `delete`. Required. | | `type` | (create) Proxy type: `datacenter`, `isp`, `residential`, `mobile`, or `custom`. | -| `name` | (create) Readable name for the proxy. | +| `name` | (create, rename) Readable name for the proxy. | | `country` | (create) ISO 3166 country code (e.g., `US`). | | `state` | (create) Two-letter state code. | | `city` | (create) City name without spaces (e.g., `sanfrancisco`). Requires `country`. | @@ -27,7 +30,8 @@ Manage proxy configurations for routing browser traffic. Proxy quality for bot d | `custom_port` | (create, custom type) Proxy port. | | `custom_username` | (create, custom type) Auth username. | | `custom_password` | (create, custom type) Auth password. | -| `proxy_id` | (delete) Proxy ID to delete. | +| `proxy_id` | (get, rename, check, delete) Proxy ID. | +| `check_url` | (check) Optional HTTP or HTTPS URL to test through the proxy. | ## Example From 7c895e7203a585196a5e42b36841b69a2ae424a6 Mon Sep 17 00:00:00 2001 From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com> Date: Fri, 7 Aug 2026 14:01:13 -0400 Subject: [PATCH 2/4] Clarify durable MCP parameter constraints --- reference/mcp-server/tools/manage-browser-pools.mdx | 2 +- reference/mcp-server/tools/manage-profiles.mdx | 2 +- reference/mcp-server/tools/manage-proxies.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/mcp-server/tools/manage-browser-pools.mdx b/reference/mcp-server/tools/manage-browser-pools.mdx index 607dfb84..5c80ce72 100644 --- a/reference/mcp-server/tools/manage-browser-pools.mdx +++ b/reference/mcp-server/tools/manage-browser-pools.mdx @@ -38,7 +38,7 @@ Manage pools of pre-provisioned browser instances for fast acquisition. | `chrome_policy` | (create, update) Chrome enterprise policy overrides. On update, pass an empty object to clear it. | | `kiosk_mode` | (create, update) Hide the address bar and tabs in live view. | | `viewport_width` and `viewport_height` | (create, update) Window dimensions in pixels. Supply both together. | -| `viewport_refresh_rate` | (create, update) Display refresh rate in Hz. | +| `viewport_refresh_rate` | (create, update) Display refresh rate in Hz. Requires `viewport_width` and `viewport_height`. | | `timeout_seconds` | (create, update) Idle timeout for acquired browsers. Must be between 10 and 259200 seconds. Default 600. | | `discard_all_idle` | (update) Discard all idle browsers after applying the configuration. | | `acquire_timeout_seconds` | (acquire) Max seconds to wait for a browser. | diff --git a/reference/mcp-server/tools/manage-profiles.mdx b/reference/mcp-server/tools/manage-profiles.mdx index 71b00fac..0e07c3d6 100644 --- a/reference/mcp-server/tools/manage-profiles.mdx +++ b/reference/mcp-server/tools/manage-profiles.mdx @@ -22,7 +22,7 @@ Manage browser profiles that persist cookies, logins, and session data across br | `action` | Operation to perform: `setup`, `list`, `get`, `rename`, or `delete`. Required. | | `profile_name` | (setup, get, rename, delete) Exact profile name. For setup: 1–255 chars. | | `profile_id` | (get, rename, delete) Profile ID. Alternative to `profile_name`. | -| `new_name` | (rename) New profile name. | +| `new_name` | (rename) New profile name. Must be 1–255 characters using letters, numbers, dots, underscores, or hyphens. | | `update_existing` | (setup) If true, update an existing profile. Default false. | Name-based setup uses an exact match. If more than one profile has the same name, rename or delete duplicate profiles by ID, then retry setup. With `update_existing: true`, setup fails instead of creating a profile when no exact match exists. diff --git a/reference/mcp-server/tools/manage-proxies.mdx b/reference/mcp-server/tools/manage-proxies.mdx index b2cae8af..496d032a 100644 --- a/reference/mcp-server/tools/manage-proxies.mdx +++ b/reference/mcp-server/tools/manage-proxies.mdx @@ -31,7 +31,7 @@ Manage proxy configurations for routing browser traffic. Proxy quality for bot d | `custom_username` | (create, custom type) Auth username. | | `custom_password` | (create, custom type) Auth password. | | `proxy_id` | (get, rename, check, delete) Proxy ID. | -| `check_url` | (check) Optional HTTP or HTTPS URL to test through the proxy. | +| `check_url` | (check) Optional HTTP or HTTPS URL to test through the proxy instead of Kernel's default check target. | ## Example From d3b724c2ed202d837bd800a793c043a03bdac753 Mon Sep 17 00:00:00 2001 From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com> Date: Fri, 7 Aug 2026 14:27:32 -0400 Subject: [PATCH 3/4] Clarify profile rename character set --- reference/mcp-server/tools/manage-profiles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/mcp-server/tools/manage-profiles.mdx b/reference/mcp-server/tools/manage-profiles.mdx index 0e07c3d6..abb54456 100644 --- a/reference/mcp-server/tools/manage-profiles.mdx +++ b/reference/mcp-server/tools/manage-profiles.mdx @@ -22,7 +22,7 @@ Manage browser profiles that persist cookies, logins, and session data across br | `action` | Operation to perform: `setup`, `list`, `get`, `rename`, or `delete`. Required. | | `profile_name` | (setup, get, rename, delete) Exact profile name. For setup: 1–255 chars. | | `profile_id` | (get, rename, delete) Profile ID. Alternative to `profile_name`. | -| `new_name` | (rename) New profile name. Must be 1–255 characters using letters, numbers, dots, underscores, or hyphens. | +| `new_name` | (rename) New profile name. Must be 1–255 characters using ASCII letters, numbers, dots, underscores, or hyphens. | | `update_existing` | (setup) If true, update an existing profile. Default false. | Name-based setup uses an exact match. If more than one profile has the same name, rename or delete duplicate profiles by ID, then retry setup. With `update_existing: true`, setup fails instead of creating a profile when no exact match exists. From 05536f6ce9aa07cd9488565af2859e46458a3521 Mon Sep 17 00:00:00 2001 From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com> Date: Fri, 7 Aug 2026 15:52:28 -0400 Subject: [PATCH 4/4] Correct durable MCP reference contracts --- reference/mcp-server/tools/manage-browser-pools.mdx | 8 ++++++-- reference/mcp-server/tools/manage-profiles.mdx | 9 +++++++-- reference/mcp-server/tools/manage-proxies.mdx | 2 ++ 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/reference/mcp-server/tools/manage-browser-pools.mdx b/reference/mcp-server/tools/manage-browser-pools.mdx index 5c80ce72..f04b8f3b 100644 --- a/reference/mcp-server/tools/manage-browser-pools.mdx +++ b/reference/mcp-server/tools/manage-browser-pools.mdx @@ -24,9 +24,11 @@ Manage pools of pre-provisioned browser instances for fast acquisition. |-----------|-------------| | `action` | Operation to perform. Required. | | `id_or_name` | Pool ID or name. Required for `get`, `update`, `delete`, `flush`, `acquire`, and `release`. | +| `limit` | (list) Maximum results per page. Must be between 1 and 100. | +| `offset` | (list) Pagination offset. Must be 0 or greater. | | `name` | (create, update) Unique pool name. | | `size` | (create, update) Number of browsers to maintain in the pool. | -| `fill_rate_per_minute` | (create, update) Integer pool fill rate percentage per minute. Default 25; use `0` to pause filling. | +| `fill_rate_per_minute` | (create, update) Integer pool fill rate percentage per minute. On create, defaults to 25; on update, omit to leave unchanged. Use `0` to pause filling. | | `headless` | (create, update) Headless mode for pool browsers. | | `stealth` | (create, update) Stealth mode for pool browsers. | | `profile_id` or `profile_name` | (create, update) Profile to load into pool browsers. | @@ -39,7 +41,7 @@ Manage pools of pre-provisioned browser instances for fast acquisition. | `kiosk_mode` | (create, update) Hide the address bar and tabs in live view. | | `viewport_width` and `viewport_height` | (create, update) Window dimensions in pixels. Supply both together. | | `viewport_refresh_rate` | (create, update) Display refresh rate in Hz. Requires `viewport_width` and `viewport_height`. | -| `timeout_seconds` | (create, update) Idle timeout for acquired browsers. Must be between 10 and 259200 seconds. Default 600. | +| `timeout_seconds` | (create, update) Idle timeout for acquired browsers. Must be between 10 and 259200 seconds. On create, defaults to 600; on update, omit to leave unchanged. | | `discard_all_idle` | (update) Discard all idle browsers after applying the configuration. | | `acquire_timeout_seconds` | (acquire) Max seconds to wait for a browser. | | `session_id` | (release) Session ID of the browser to release. | @@ -48,6 +50,8 @@ Manage pools of pre-provisioned browser instances for fast acquisition. `get`, `create`, and `update` responses report the authoritative `profile_id` and `extension_ids` stored on the pool. +`discard_all_idle` affects only browsers that are idle when the update runs. Acquired browsers retain their old configuration, and releasing one with the default `reuse: true` returns that old configuration to the pool. See [Update a browser pool](/browsers/pools#update-a-browser-pool) for `reuse: false` and later flush or discard recovery options. + ## Example ```json diff --git a/reference/mcp-server/tools/manage-profiles.mdx b/reference/mcp-server/tools/manage-profiles.mdx index abb54456..4454773a 100644 --- a/reference/mcp-server/tools/manage-profiles.mdx +++ b/reference/mcp-server/tools/manage-profiles.mdx @@ -20,10 +20,15 @@ Manage browser profiles that persist cookies, logins, and session data across br | Parameter | Description | |-----------|-------------| | `action` | Operation to perform: `setup`, `list`, `get`, `rename`, or `delete`. Required. | -| `profile_name` | (setup, get, rename, delete) Exact profile name. For setup: 1–255 chars. | +| `profile_name` | (setup, get, rename, delete) Exact profile name. Names used for setup follow the rules below. | | `profile_id` | (get, rename, delete) Profile ID. Alternative to `profile_name`. | -| `new_name` | (rename) New profile name. Must be 1–255 characters using ASCII letters, numbers, dots, underscores, or hyphens. | +| `new_name` | (rename) New profile name. Follows the rules below. | | `update_existing` | (setup) If true, update an existing profile. Default false. | +| `query` | (list) Search profiles by name or ID. | +| `limit` | (list) Maximum results per page. Must be between 1 and 100. | +| `offset` | (list) Pagination offset. Must be 0 or greater. | + +`profile_name` for setup and `new_name` for rename share the same rules: 1–255 characters using ASCII letters, numbers, dots, underscores, or hyphens; unique within the project; and not exactly 24 lowercase alphanumeric characters, which would be ambiguous with a profile ID. Name-based setup uses an exact match. If more than one profile has the same name, rename or delete duplicate profiles by ID, then retry setup. With `update_existing: true`, setup fails instead of creating a profile when no exact match exists. diff --git a/reference/mcp-server/tools/manage-proxies.mdx b/reference/mcp-server/tools/manage-proxies.mdx index 496d032a..143a50f0 100644 --- a/reference/mcp-server/tools/manage-proxies.mdx +++ b/reference/mcp-server/tools/manage-proxies.mdx @@ -21,6 +21,8 @@ Manage proxy configurations for routing browser traffic. Proxy quality for bot d | Parameter | Description | |-----------|-------------| | `action` | Operation to perform: `create`, `list`, `get`, `rename`, `check`, or `delete`. Required. | +| `limit` | (list) Maximum results per page. Must be between 1 and 100. | +| `offset` | (list) Pagination offset. Must be 0 or greater. | | `type` | (create) Proxy type: `datacenter`, `isp`, `residential`, `mobile`, or `custom`. | | `name` | (create, rename) Readable name for the proxy. | | `country` | (create) ISO 3166 country code (e.g., `US`). |