Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Vertex AI docs omit MCP tool search default disablement [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#52617•Fetched 2026-04-24 06:02:20
View on GitHub
Comments
0
Participants
1
Timeline
5
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×5

Error Message

Tool search is now disabled by default on Vertex AI to avoid an unsupported beta header error (opt in with ENABLE_TOOL_SEARCH) Update the MCP and environment variable docs to document the Vertex AI exception explicitly. Exact changelog entry: Tool search is now disabled by default on Vertex AI to avoid an unsupported beta header error (opt in with ENABLE_TOOL_SEARCH)

Root Cause

"Tool search is enabled by default: MCP tools are deferred and discovered on demand. When ANTHROPIC_BASE_URL points to a non-first-party host, tool search is disabled by default because most proxies do not forward tool_reference blocks. Set ENABLE_TOOL_SEARCH explicitly if your proxy does."

RAW_BUFFERClick to expand / collapse

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

"Configure tool search" in the MCP guide, plus the related Vertex AI setup and environment variable reference pages.

Current Documentation

The docs currently say:

"Tool search is enabled by default: MCP tools are deferred and discovered on demand. When ANTHROPIC_BASE_URL points to a non-first-party host, tool search is disabled by default because most proxies do not forward tool_reference blocks. Set ENABLE_TOOL_SEARCH explicitly if your proxy does."

And the environment variable reference says:

"ANTHROPIC_BASE_URL ... When set to a non-first-party host, MCP tool search is disabled by default. Set ENABLE_TOOL_SEARCH=true if your proxy forwards tool_reference blocks"

"ENABLE_TOOL_SEARCH ... Unset: all MCP tools deferred by default, but loaded upfront when ANTHROPIC_BASE_URL points to a non-first-party host."

The Vertex AI setup page documents CLAUDE_CODE_USE_VERTEX=1, ANTHROPIC_VERTEX_PROJECT_ID, and optional ANTHROPIC_VERTEX_BASE_URL, but it does not mention that Vertex AI disables tool search by default or that users must opt in with ENABLE_TOOL_SEARCH.

What's Wrong or Missing?

Changelog v2.1.119 says:

Tool search is now disabled by default on Vertex AI to avoid an unsupported beta header error (opt in with ENABLE_TOOL_SEARCH)

The current docs still describe tool search as enabled by default except for non-first-party ANTHROPIC_BASE_URL proxy hosts. That leaves out the Vertex AI-specific default and the reason for it.

As written, the docs can mislead Vertex AI users into expecting deferred MCP tool loading to work automatically, even though the current behavior requires explicitly setting ENABLE_TOOL_SEARCH to opt in.

Suggested Improvement

Update the MCP and environment variable docs to document the Vertex AI exception explicitly.

Suggested changes:

  1. In mcp → "Configure tool search", note that Vertex AI disables tool search by default to avoid unsupported beta header errors, and that users can opt in with ENABLE_TOOL_SEARCH.
  2. In the ENABLE_TOOL_SEARCH and related base URL rows in env-vars, clarify how the unset/default behavior changes on Vertex AI.
  3. In google-vertex-ai, add a short note or example such as:

Optional: Vertex AI disables MCP tool search by default to avoid unsupported beta header errors. If your Vertex setup supports tool search, opt in explicitly with ENABLE_TOOL_SEARCH=true (or auto / auto:N as appropriate).

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageContext
https://code.claude.com/docs/en/mcpPrimary "Configure tool search" explanation and behavior table
https://code.claude.com/docs/en/env-varsANTHROPIC_BASE_URL, ANTHROPIC_VERTEX_BASE_URL, and ENABLE_TOOL_SEARCH reference entries
https://code.claude.com/docs/en/google-vertex-aiVertex AI setup instructions and configuration notes
https://code.claude.com/docs/en/third-party-integrationsVertex AI gateway configuration guidance

Total scope: 4 pages affected

Source: Changelog v2.1.119

Exact changelog entry: Tool search is now disabled by default on Vertex AI to avoid an unsupported beta header error (opt in with ENABLE_TOOL_SEARCH)

extent analysis

TL;DR

Update the MCP and environment variable documentation to reflect that Vertex AI disables tool search by default, requiring users to opt in with ENABLE_TOOL_SEARCH.

Guidance

  • Review the suggested improvements for the MCP, environment variable, and Vertex AI documentation to ensure accuracy and clarity.
  • Verify that the updated documentation correctly reflects the default behavior of Vertex AI and the requirement to set ENABLE_TOOL_SEARCH to enable tool search.
  • Check the affected pages (MCP, environment variables, Vertex AI setup, and third-party integrations) to ensure consistency in the documentation.
  • Consider adding examples or notes to the documentation to help users understand the implications of the default behavior and how to opt in to tool search.

Example

No code snippet is necessary for this issue, as it is related to documentation updates.

Notes

The suggested improvements should be reviewed and tested to ensure that they accurately reflect the current behavior of the system and provide clear guidance to users.

Recommendation

Apply the suggested improvements to the documentation to ensure that users are aware of the default behavior of Vertex AI and can opt in to tool search if needed. This will help to avoid confusion and make the feature easier to understand.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#output truncation#response parsing#generation error#database connection#environment variable

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] Vertex AI docs omit MCP tool search default disablement [1 participants]