Expose capability-gated Search API tools

[chruffins]

Summary

• Add web_search with create, get, and providers operations, portable search parameters, provider-native options, project selection, and API response preservation.
• Resolve entitlements for tools/list and calls to entitlement-gated tools only. Cache the full entitlement snapshot per credential and MCP connection for up to 30 minutes; transient failures are not cached.
• Continue authenticating requests and rely on the Kernel API to authorize gated tool execution. Fail closed on entitlement lookup errors without hiding unrelated tools.
• Honor deployment allow/deny configuration. Disable retries for billable search creation, propagate cancellation, and provide timeout headroom for result persistence.
• Use live provider slugs, inline MCP schemas, and non-empty identifier validation.

API assumptions and scope

GET /org/entitlements provides the explicit Search feature flag. The MCP server does not use /search/providers as an access probe; that operation remains available for live provider discovery when the Search tool is enabled.

The pinned SDK does not yet include generated Search resources, so these calls use its public authenticated transport. Deferred content retrieval is not exposed; this change covers implemented search, retained-result, and provider-discovery endpoints only.

Tests

• Full suite: 723 passed, 0 failed.
• Focused Search/entitlement/registration/route tests: 64 passed, 0 failed.
• TypeScript check, Prettier, and git diff --check pass.
• bun run build compiled and passed TypeScript, then stopped during page-data collection because required KERNEL_CLI_PROD_CLIENT_ID environment configuration is absent.
• No live billable search or production end-to-end test was run.

[vercel]

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

Project	Deployment	Actions	Updated
mcp	Ready	Preview	Sep 24, 2026 7:06pm UTC

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 4 potential issues.

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

^{Reviewed by Cursor Bugbot for commit 400688a. Configure here.}

[rgarcia]

reviewed — the tool shape and non-retryable search call look good, but i'd change capability discovery and improve the advertised request contract before merging.

Changes requested

• src/app/[transport]/route.ts:195-203, src/lib/mcp/search-access.ts:7-37 — please determine whether this credential can call POST /search from the capabilities/entitlements endpoint once per MCP connection, then use that result to decide whether web_search appears in tools/list. Do not preflight GET /search/providers or recheck Search capability on every MCP request: provider discovery describes configured providers and options, not entitlement, and the current probe adds an upstream request (up to a five-second wait) to unrelated calls. If /org/entitlements is the intended source, please add an explicit Search entitlement there (and to its API schema), since it currently advertises vaults but not search. Keep providers as an explicit action for live provider discovery; update the README and routing tests to reflect connection-time gating.

• src/lib/mcp/tools/search.ts:36-95 — please carry the key packages/api/openapi.yaml semantics into descriptions on the nested MCP request fields, especially the default/behavior of strategy, best-effort filters versus strict_params, and what content: true and browser options do. The action shape matches other MCP tools, but without those descriptions clients see valid types without enough guidance to choose safe and effective inputs.

[rgarcia]

one follow-up on entitlement lookup behavior — sorry for asking you to clean up the pre-existing per-request vault lookup i introduced while working on this search PR.

src/app/[transport]/route.ts:176-187, src/lib/mcp/entitlements.ts:39-79 — please resolve entitlements on every tools/list and on calls to entitlement-gated tools, but not on unrelated tool calls. Cache the entitlement snapshot in memory per credential + MCP connection for 30 minutes (credential-bound TTL for stateless clients), rather than caching only the Search boolean for five minutes while still fetching /org/entitlements on every request. Keep the cache bounded and evict expired entries so it cannot grow indefinitely; don't retain transient lookup failures for the full TTL. The cache should control MCP tool exposure only: keep authenticating requests and let the Kernel API enforce access when a gated tool is invoked.

[rgarcia]

re-reviewed the latest changes: entitlement lookups are scoped to tools/list and gated tool calls, the bounded 30-minute cache covers vaults and Search, and the requested Search API descriptions are in place. focused tests pass.