Expose deferred search content in MCP

[chruffins]

Summary

• add a contents action to web_search for fetching selected results from a retained search
• validate selector and browser-option constraints before calling the API
• avoid retries for retrieval requests and document possible browser charges

Testing

• bun test src/lib/mcp/tools/search.test.ts

---

Note

Medium Risk
Introduces a new billable/browser-backed API path on web_search, though it mirrors existing no-retry and validation patterns used for create.

Overview
Adds a contents action to the MCP web_search tool so clients can fetch page content for selected results from a retained search after the initial search, without re-running a billable query.

The tool schema now accepts a contents payload (pick results by result_ids or limit, plus optional browser/provider content options) with Zod checks such as exactly one selector and valid source / browser_id combinations. The handler POSTs to /search/{search_id}/contents with URL-encoded IDs, maxRetries: 0, and a timeout derived from the request; descriptions call out possible browser charges.

Tests cover a successful contents call (including reserved characters in search_id) and extend invalid-input cases so bad contents requests fail before any API call.

^{Reviewed by Cursor Bugbot for commit 91fd3ad. Configure here.}

[vercel]

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

Project	Deployment	Actions	Updated
mcp	Ready	Preview	Oct 2, 2026 2:05pm UTC

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 91fd3ad. Configure here.}

[rgarcia]

reviewed — approving, schema now lines up with the api after 5dcfc39. a few non-blocking things worth a look:

Questions

• src/lib/mcp/tools/search.ts:76-79, :95-97 — the shared searchContentOptions has no .describe() on format, max_chars, max_age_hours, timeout_ms, and result_ids/limit/the outer timeout_ms have none either. reusing it in create dropped descriptions create used to have ("zero forces a live fetch", per-result deadline, "Kernel does not delete it" on browser_id). worth porting those back, and making the 120s overall vs 60s per-result timeout_ms explicit.

Tests

• src/lib/mcp/tools/search.test.ts:194 — the 503 no-retry test only covers create. consider adding a contents case: the success test at :79 can't catch retries, and a retry here re-bills browser work.

Nits

• src/lib/mcp/tools/search.ts:95 — nit: the api requires result_ids to be unique (uniqueItems: true, 400 on duplicates). a set-size refine would catch duplicates before the api call.