perf(mcp): fast external MCP capability search

[reachjalil]

Summary

Speeds up Den /mcp/agent external MCP capability discovery by adding bounded tools/list, a derived manifest cache, stale-while-revalidate refresh, and batched connection status reads.

Before this branch, search listed tools sequentially for every granted external MCP connection and had no hard per-connection deadline. One slow or unavailable MCP could stall the whole external capability stage.

What Changed

Area	Change
Search latency	Adds per-connection timeout and bounded concurrency for live MCP tools/list.
Manifest cache	Adds external_mcp_tool_manifest for derived, non-secret tool metadata keyed by connection + principal.
Stale handling	Fresh cache serves directly; stale cache serves immediately and schedules bounded background revalidation.
Refresh control	Adds manual refresh at POST /v1/mcp-connections/:connectionId/refresh-tools; returns 202 in_progress when another worker owns the lease.
Maintenance	Background maintenance refreshes stale/error manifests and seeds shared rows with an anti-join.
API status	GET /v1/mcp-connections includes caller-relevant tool status and batches manifest/account lookups.
Safety hardening	Refresh failures and leases no longer stamp current config hashes over old-config rows.

Reviewer Focus

Please check	Why
Manifest trust boundary	Manifests must remain derived cache data only; credentials stay in connection/account tables.
Principal isolation	Shared credentials use shared; per-member OAuth uses the member principal so users never share cached tool lists.
Config changes	config_hash should make URL/auth/credential-mode changes cache misses even if invalidation is missed.
Refresh contention	Lease handling should avoid duplicate refresh work and surface in_progress for manual refresh.
Connection list performance	List endpoints should batch manifest and connected-account reads instead of per-row queries.

Security / Correctness

• Grants are still computed live through existing External MCP Connection access checks.
• OAuth/API-key secrets are never stored in manifest rows.
• execute_capability still live-checks grant + credential and calls the upstream MCP server directly; the cache only affects discovery.
• Refresh/listing still uses the existing MCP transport and URL guard.

Runtime Controls

Env	Default
DEN_MCP_LIST_TOOLS_TIMEOUT_MS	3500
DEN_MCP_LIST_TOOLS_CONCURRENCY	5
DEN_MCP_MANIFEST_CACHE_ENABLED	true
DEN_MCP_MANIFEST_FRESH_TTL_MS	900000
DEN_MCP_MANIFEST_MAX_AGE_MS	86400000
DEN_MCP_MANIFEST_MAX_BYTES	262144
DEN_MCP_MANIFEST_REFRESH_INTERVAL_MS	300000
DEN_MCP_MANIFEST_REFRESH_BATCH_SIZE	20
DEN_MCP_MANIFEST_REFRESH_LEASE_MS	60000
DEN_MCP_MANIFEST_REVALIDATE_CONCURRENCY	3

Not Included

• No UI for cache/tool status yet.
• No persistent tools/list_changed watchers.
• No tool input-schema caching.
• No execution timeout changes.
• Benchmark/fraimz proof is not captured yet, so this should remain draft until we add before/after numbers and an end-to-end proof run.

Validation

Command	Result
pnpm --filter @openwork-ee/den-api build	Passed
pnpm --filter @openwork-ee/den-api exec tsc --noEmit	Passed
pnpm --filter @openwork-ee/den-api exec bun test test/external-mcp-manifests.test.ts	Passed, 4 tests
pnpm --filter @openwork-ee/den-api exec bun test test/external-capabilities-search-divergence.test.ts	Passed, 9 tests
pnpm --filter @openwork-ee/den-api exec bun test test/mcp-connections-connect-start.test.ts	Passed, 2 tests
pnpm --filter @openwork-ee/den-db db:push for openwork_test_searchdiv and openwork_test_pr7	Passed; used to provision local DB-backed test schemas

[vercel]

@reachjalil is attempting to deploy a commit to the Different AI Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
openwork-landing	Ready	Preview, Comment, Open in v0	Jul 8, 2026 2:19pm