Document durable MCP tool contracts

[IlyaasK]

Summary

• document MCP browser-pool create/update validation and clear semantics
• document authoritative profile and extension IDs
• document exact profile setup, profile rename, and duplicate recovery
• document proxy retrieve, rename, and check actions

Why

The MCP reference lagged the durable API and updated MCP tool surface. This makes supported operations, validation, clear behavior, and destructive side effects explicit.

Merge order

Merge after kernel-mcp-server#139 and kernel-mcp-server#140, because this reference documents behavior introduced by those implementation PRs.

Verification

• Mint broken-links
• git diff --check
• documentation checked against the reviewed MCP implementation branches
• API limits and defaults checked against kernel/kernel merged origin/main

---

Note

Low Risk
Documentation-only changes with no runtime or security impact; accuracy depends on merging after the referenced MCP server implementation PRs.

Overview
Updates the MCP reference for manage_browser_pools, manage_profiles, and manage_proxies so it matches the durable API and expanded tool surface (intended to land after the corresponding MCP server PRs).

Browser pools — Documents the update action plus list pagination, many create/update fields (profile, extensions, proxy, start_url, viewport, chrome_policy, etc.), clear semantics (empty string/object, clear_profile, clear_extensions), validation/defaults (e.g. fill_rate_per_minute default 25, timeout_seconds bounds), authoritative profile_id / extension_ids in responses, and how discard_all_idle interacts with acquired browsers and reuse.

Profiles — Adds get and rename, list query / pagination, shared naming rules (including ID ambiguity), exact-name setup, duplicate-name recovery, and a warning not to rename while a browser is using the profile.

Proxies — Adds get, rename, and check (optional check_url), plus list pagination and name on rename.

^{Reviewed by Cursor Bugbot for commit 05536f6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	Aug 6, 2026, 10:07 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Error		Aug 7, 2026 7:52pm

[cursor]

Stale comment

Risk Assessment: Very Low

Verdict: Approval retained (no re-approval)

Re-evaluation trigger

PR was synchronized after a prior Very Low approval on b180f7a. Re-assessed head 7c895e7.

Summary

Still documentation-only. Three MCP tool reference MDX pages; no application code, infrastructure, auth, or runtime behavior changes. Delta since prior approval is small parameter-constraint wording only.

Evidence

Factor	Assessment
Codepaths modified	Docs only: manage-browser-pools.mdx, manage-profiles.mdx, manage-proxies.mdx
Diff size	3 files, +40 / −17 (full PR); incremental commit is clarification-only
Blast radius	Documentation site content only
Infra / security impact	None
Production logic	None
CODEOWNERS	None present

What changed (current head)

• Documents update and related clear/config parameters for browser pools
• Documents get / rename (and related notes) for profiles
• Documents get / rename / check for proxies
• Clarifies constraints (viewport_refresh_rate deps, new_name charset, check_url default wording)

Decision

Fits Very Low (documentation-only, small scoped diff, no shared systems or production logic). Risk did not increase vs. prior approval, so previous approval is left in place. Per policy, not re-approving an already-approved PR.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Stale comment

Risk Assessment: Very Low

Verdict: Approval retained (no re-approval)

Re-evaluation trigger

PR was synchronized after a prior Very Low approval. Re-assessed head d3b724c.

Summary

Still documentation-only. Three MCP tool reference MDX pages under reference/mcp-server/tools/; no application code, infrastructure, auth, or runtime behavior changes. Incremental delta since the last assessment is a one-word clarification (ASCII on the profile new_name charset).

Evidence

Factor	Assessment
Codepaths modified	Docs only: manage-browser-pools.mdx, manage-profiles.mdx, manage-proxies.mdx
Diff size	3 files, +40 / −17 (full PR); latest commit is wording-only
Blast radius	Documentation site content only
Infra / security impact	None
Production logic	None
CODEOWNERS	None present

What changed (current head)

• Documents update and related clear/config parameters for browser pools
• Documents get / rename (and related notes) for profiles
• Documents get / rename / check for proxies
• Clarifies parameter constraints (including ASCII charset for profile rename)

Decision

Fits Very Low (documentation-only, small scoped diff, no shared systems or production logic). Risk did not increase vs. prior approval, so previous approval is left in place. Per policy, not re-approving an already-approved PR.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[masnwilliams]

the new operations are useful, but the reference still does not accurately describe the durable contract. the create-only defaults and shared profile-name invariant need to be corrected before merge.

there is also a structural sync problem here: all three registered tools expose limit and offset for list, and manage_profiles exposes query, but these parameter tables omit them. since these pages manually duplicate the registered Zod schemas, they have already drifted while this PR is updating them. please add the missing fields in this PR; longer term, generating these tables from the schemas or adding a parity check would keep this contract durable.

git diff --check, broken-links, Mintlify preview, and BugBot pass. the separate Vercel deployment check is still failing.

[masnwilliams]

these defaults are create-only, but the row now scopes them to both create and update. updates are PATCH operations: omitting fill_rate_per_minute preserves the stored value rather than applying 25. the same issue appears on timeout_seconds at line 42. please say “on create, defaults to …; on update, omit to leave unchanged” for both fields. the API contract explicitly keeps create defaults out of PATCH schemas.

[IlyaasK]

Fixed in 05536f6. Both rows now distinguish create defaults from PATCH omission: create defaults to 25/600, while update omission preserves the stored value.

[masnwilliams]

this documents only part of the profile-name invariant, and the preceding profile_name row gives setup a weaker rule even though create and rename share the same API validator. both require 1–255 ASCII letters, numbers, ., _, or -; both reject 24-character lowercase alphanumeric names because they are ambiguous with profile IDs; and both require uniqueness within the logical project. can we state that invariant once and apply it to setup and rename so the two rows cannot drift?

[IlyaasK]

Fixed in 05536f6. Setup profile_name and rename new_name now point to one shared invariant covering length, ASCII character set, project uniqueness, and the 24-character lowercase-alphanumeric ID ambiguity.

[masnwilliams]

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]

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.

[IlyaasK]

Also fixed the schema-table drift from the review summary in 05536f6: limit and offset are documented for browser-pool, profile, and proxy list operations, and profile query is documented. Verification: git diff --check and mint broken-links passed.

[cursor]

Risk Assessment: Very Low

Verdict: Approval retained (no re-approval)

Re-evaluation trigger

PR was synchronized after a prior Very Low approval. Re-assessed head 05536f6.

Summary

Still documentation-only. Three MCP tool reference MDX pages under reference/mcp-server/tools/; no application code, infrastructure, auth, or runtime behavior changes. Incremental delta since the last assessment adds list pagination/query fields, create-vs-update default wording, shared profile-name rules, and discard_all_idle behavior notes.

Evidence

Factor	Assessment
Codepaths modified	Docs only: manage-browser-pools.mdx, manage-profiles.mdx, manage-proxies.mdx
Diff size	3 files, +51 / −17
Blast radius	Documentation site content only
Infra / security impact	None
Production logic	None
CODEOWNERS	None present

What changed (current head)

• Documents update and related clear/config parameters for browser pools
• Documents get / rename (and related notes) for profiles
• Documents get / rename / check for proxies
• Adds limit / offset (and profiles query) for list actions
• Clarifies create-only defaults, shared name invariants, and idle-discard semantics

Decision

Fits Very Low (documentation-only, small scoped diff, no shared systems or production logic). Risk did not increase vs. prior approval, so previous approval is left in place. Per policy, not re-approving an already-approved PR.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[masnwilliams]

all requested changes are addressed in 05536f6. the create/update defaults, shared profile-name invariant, list/search parameters, and mixed-configuration pool lifecycle are now documented accurately. re-checked the full diff and found no remaining actionable code-quality issues.