Skip to content

Document durable MCP tool contracts #489

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
IlyaasK wants to merge 4 commits into
base: main
Choose a base branch
from
+51 −17
Open

Document durable MCP tool contracts #489

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b180f7a
document durable MCP tool contracts
IlyaasK Aug 6, 2026
7c895e7
Clarify durable MCP parameter constraints
IlyaasK Aug 7, 2026
d3b724c
Clarify profile rename character set
IlyaasK Aug 7, 2026
05536f6
Correct durable MCP reference contracts
IlyaasK Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 25 additions & 9 deletions reference/mcp-server/tools/manage-browser-pools.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand All @@ -22,20 +23,35 @@ 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`. |
| `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. 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. |
| `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. Requires `viewport_width` and `viewport_height`. |
| `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. |

@masnwilliams masnwilliams Aug 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this leaves out the lifecycle behavior most likely to produce a mixed-configuration pool. only browsers idle at update time are discarded; acquired browsers retain the old configuration, and releasing one with the default reuse: true puts that old configuration back into the pool. please include that warning here or link directly to the canonical browser-pool update section, which already explains the reuse: false and later flush/discard recovery paths.

@IlyaasK IlyaasK Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 05536f6. The reference now explains that only currently idle browsers are discarded, that acquired browsers can return the old configuration under reuse: true, and links to the canonical update section for reuse: false and later flush/discard recovery.

| `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.

`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
Expand Down
20 changes: 16 additions & 4 deletions reference/mcp-server/tools/manage-profiles.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -11,16 +11,28 @@ 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. 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. 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.

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

Expand Down
14 changes: 10 additions & 4 deletions reference/mcp-server/tools/manage-proxies.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -11,23 +11,29 @@ 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. |
| `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) 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`. |
| `custom_host` | (create, custom type) Proxy host address. |
| `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 instead of Kernel's default check target. |

## Example

Expand Down
Loading