fix(mcp): avoid repeated tool schema materialization

[mattzcarey]

Summary

• cache MCP input/output JSON Schema conversion for the current catalog on each live connection, discarding superseded converted schema graphs while continuing to return fresh AI tool records and execute closures
• add Think.includeMcpTools, defaulting to true, so applications that expose MCP tools through Code Mode or another mechanism outside Think's automatic tool set can skip direct MCP AI-tool materialization without disabling connection restore, discovery, waiting, raw listing, or calls
• add regression coverage for a 313-tool catalog, bounded catalog replacement, schema invalidation, failed conversions, and connector access with direct MCP exposure disabled
• document the new setting in this repository and in cloudflare/cloudflare-docs#32180, with patch changesets for agents and @cloudflare/think

Why

Think currently calls getAITools() before beforeTurn(), so an activeTools filter cannot prevent every MCP input and output schema from being converted to Zod. Large catalogs exposed through Code Mode therefore pay hundreds of conversions on every turn despite exposing no direct MCP tools to the model.

This change avoids conversion entirely when Think's automatic MCP exposure is disabled and reuses converted schemas for direct MCP exposure while each live connection retains its current catalog. Replacing the catalog drops the superseded converted schema graph.

Testing

• pnpm --filter agents exec vitest --run --project workers src/tests/mcp/client-manager.test.ts
• pnpm --filter @cloudflare/think exec vitest --run -c src/tests/vitest.config.ts src/tests/mcp-tool-materialization.test.ts
• full agents package test suite
• full @cloudflare/think package test suite
• pnpm exec nx affected -t build test --base=origin/main
• pnpm run check
• retained-catalog heap probe across 12 revisions: approximately 1 MiB growth after bounding the cache, compared with 139.5 MiB before

Closes #1938

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 116dd0a

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1959

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1959

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1959

create-think

npm i https://pkg.pr.new/create-think@1959

hono-agents

npm i https://pkg.pr.new/hono-agents@1959

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1959

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1959

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1959

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1959

commit: 116dd0a

[mattzcarey]

@agent-think we will need to document this on cloudflare-docs repo. pls make a pr there for this.

[cjol]

I hesitated over the description of