Tìm kiếm công cụ trong Claude Code: Tác tử tìm công cụ MCP cần dùng như thế nào

Nếu bạn đã kết nối một số máy chủ MCP với Claude Code, tính năng tìm kiếm công cụ cho phép tải theo yêu cầu những công cụ cần dùng mà không phải tải trước mọi định nghĩa. Khi khởi động, tác tử nhận tên các công cụ được hoãn tải và hướng dẫn của máy chủ, sau đó tìm kiếm trong danh mục những gì cần thiết. Cách này giúp tác tử làm việc với một bộ công cụ lớn: tài liệu của Anthropic cho biết độ chính xác khi lựa chọn giảm xuống khi tải đồng thời hơn 30-50 công cụ. Đây là hướng dẫn chung, không phải số liệu đo trong phiên của bạn. Tính năng tìm kiếm công cụ được bật theo mặc định khi mô hình hỗ trợ, nhưng nền tảng, proxy hoặc cài đặt có thể tắt tính năng này.

Tài liệu Ailoot: API, khóa và thiết lập.

Điều gì xảy ra với ngữ cảnh khi không có tìm kiếm công cụ#

Mỗi máy chủ MCP được kết nối sẽ thêm các công cụ của nó vào danh sách những thứ tác tử có thể gọi. Khi không có tìm kiếm công cụ, các định nghĩa của chúng — tên, mô tả và lược đồ tham số — được tải trước vào ngữ cảnh. Máy chủ kết nối trong nền khi phiên bắt đầu. Nếu cần một công cụ từ máy chủ chưa kết nối xong, Claude Code sẽ chờ thông qua công cụ nội bộ WaitForMcpServers. Bạn có thể đánh giá riêng số lượng công cụ và token mà một máy chủ cụ thể bổ sung cho từng kết nối.

Tài liệu chính thức của Anthropic đưa ra hai con số ước tính (số liệu chung, không nêu phương pháp đo):

• 50 công cụ có thể chiếm 10-20 nghìn token ngữ cảnh;
• độ chính xác khi chọn đúng công cụ giảm xuống khi tải đồng thời hơn 30-50 công cụ.

Cách đánh giá tính năng tìm kiếm công cụ qua cài đặt#

Để xác định liệu tính năng tìm kiếm công cụ có hoạt động trong phiên hiện tại hay không, hãy kiểm tra các điều kiện sau:

• mô hình nào đang trả lời — Sonnet/Haiku/Opus 4.5 trở lên: cơ chế này khả dụng; mô hình cũ hơn: không khả dụng;
• ANTHROPIC_BASE_URL có được đặt thành một máy chủ không chuẩn hay không — trong trường hợp đó, cơ chế này mặc định tắt trừ khi được bật rõ ràng qua ENABLE_TOOL_SEARCH;
• giá trị của biến ENABLE_TOOL_SEARCH — false tắt hoàn toàn cơ chế; auto/auto:N chỉ bật cơ chế khi lượng định nghĩa đạt đến một ngưỡng;
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS có được đặt hay không — nếu không có cài đặt được tổ chức quản lý, biến này giữ tính năng tìm kiếm công cụ ở trạng thái tắt ngay cả khi người dùng đã đặt ENABLE_TOOL_SEARCH;
• công cụ ToolSearch có bị chặn qua permissions.deny trong cài đặt hay không — hạn chế như vậy sẽ tắt chức năng tìm kiếm;
• nền tảng nào đang được sử dụng — cơ chế này không khả dụng trên các triển khai Microsoft Foundry trong Azure, còn trên Google Cloud Agent Platform, hành vi phụ thuộc vào phiên bản Claude Code và mô hình.

Việc kiểm tra này giúp bạn đánh giá trạng thái từ cấu hình, nhưng không thể quan sát trạng thái ngay trong phiên. Phần MCP và phần tìm kiếm công cụ trong tài liệu Agent SDK không mô tả chỉ báo trực tiếp trong giao diện như “tìm kiếm công cụ: bật/tắt”. Việc hai tài liệu này không đề cập đến chỉ báo đó không chứng minh rằng không có chỉ báo như vậy ở bất kỳ nơi nào khác.

Bạn có thể đặt biến trước khi bắt đầu phiên, chẳng hạn ENABLE_TOOL_SEARCH=auto:15 claude. Để đảm bảo các công cụ của một máy chủ cụ thể luôn được tải, hãy dùng trường alwaysLoad: true trong cấu hình của máy chủ đó. Trường này khả dụng với mọi loại máy chủ; các điều kiện và giới hạn được mô tả trong phần alwaysLoad bên dưới.

Cách hoạt động của tính năng tìm kiếm công cụ#

Khi tính năng tìm kiếm công cụ được bật, lúc phiên bắt đầu, chỉ tên các công cụ được hoãn tải và hướng dẫn của máy chủ được tải vào ngữ cảnh. Hướng dẫn của máy chủ mô tả những tác vụ mà máy chủ hữu ích. Khi một tác vụ cần đến khả năng chưa có trong ngữ cảnh, tác tử sẽ tự tìm công cụ phù hợp trong danh mục.

Tài liệu Agent SDK mô tả chi tiết hơn về cơ chế tìm kiếm: theo mặc định, mỗi lần tìm kiếm tải tối đa năm công cụ phù hợp nhất từ danh mục. Các công cụ này vẫn khả dụng trong những lượt tiếp theo của phiên cho đến khi SDK rút gọn các tin nhắn mà trong đó tác tử đã tìm thấy chúng. Sau khi rút gọn, các công cụ được phát hiện trước đó có thể bị loại khỏi ngữ cảnh và tác tử sẽ tìm lại khi cần dùng chúng lần sau. Danh mục hỗ trợ tối đa 10 000 công cụ. Tài liệu MCP của chính Claude Code không đưa ra những con số cụ thể này, nhưng mô tả cùng nguyên tắc tải theo yêu cầu.

Theo tài liệu Agent SDK, mỗi lần tìm kiếm bổ sung một lượt trao đổi. Tài liệu không nêu chính xác lượt trao đổi đó bao gồm những gì. Với Claude Code, tài liệu MCP cũng mô tả một khác biệt về cách báo lỗi: khi không có tìm kiếm công cụ, Claude Code không báo cho mô hình biết các kết nối máy chủ bị lỗi. Khi bật tìm kiếm, mô hình nhận được thông tin về máy chủ không kết nối được và lỗi xảy ra là gì.

Claude Code không áp đặt giới hạn cố định về số lượng công cụ từ một máy chủ. Giới hạn thực tế là ngân sách cửa sổ ngữ cảnh của phiên cụ thể.

Cấu hình công cụ là một trong những tác vụ liên quan đến việc quản lý ngữ cảnh của tác tử AI.

Khi nào tính năng tìm kiếm công cụ bị tắt theo mặc định#

Cơ chế này được bật theo mặc định, nhưng hoạt động của nó phụ thuộc vào mô hình, máy chủ API và nền tảng.

Mô hình. Tính năng tìm kiếm công cụ yêu cầu một mô hình hỗ trợ các khối tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 hoặc phiên bản mới hơn. Với các mô hình cũ hơn, Claude Code tải trước định nghĩa công cụ.

Máy chủ API. Claude Code tắt tính năng tìm kiếm công cụ khi biến ANTHROPIC_BASE_URL trỏ đến máy chủ của bên thứ ba: hầu hết proxy không chuyển tiếp các khối tool_reference đặc biệt. Điều này áp dụng khi kết nối với Claude thông qua cổng kết nối hoặc máy chủ proxy riêng của bạn thay vì kết nối trực tiếp qua địa chỉ của Anthropic. Lý do tính năng bị tắt là ANTHROPIC_BASE_URL không chuẩn; cách thanh toán gói đăng ký tự nó không gây ra điều này. Bạn có thể đặt rõ ràng ENABLE_TOOL_SEARCH để ghi đè hành vi này. Nếu bản thân proxy không hỗ trợ các khối tool_reference, việc buộc bật cơ chế sẽ khiến yêu cầu báo lỗi. Trong trường hợp này, hệ thống sẽ không chuyển về tải trước các định nghĩa.

Nền tảng triển khai. Tính năng tìm kiếm công cụ không hoạt động trên các triển khai Microsoft Foundry được lưu trữ trên Azure: máy chủ từ chối yêu cầu và ENABLE_TOOL_SEARCH không thể ghi đè điều này. Trên Google Cloud Agent Platform, trước Claude Code phiên bản 2.1.221, cơ chế này tắt với mọi mô hình trừ khi ENABLE_TOOL_SEARCH=true được đặt rõ ràng. Kể từ phiên bản đó, tính năng được bật theo mặc định cho Opus/Sonnet/Haiku 4.5 trở lên. Với các mô hình cũ hơn trên nền tảng này, Claude Code vẫn tải trước tất cả công cụ vì hạ tầng máy chủ của chúng từ chối tiêu đề nội bộ cần thiết.

Biến ENABLE_TOOL_SEARCH có năm tùy chọn:

• không được đặt — hành vi tiêu chuẩn, với các ngoại lệ nêu trên;
• true — bật cơ chế trên các mô hình hỗ trợ, ngoại trừ hai trường hợp: Azure Foundry và các mô hình Agent Platform cũ hơn; các yêu cầu gửi qua proxy không hỗ trợ khối tool_reference sẽ thất bại;
• auto — Claude Code tải trước công cụ khi tổng dung lượng định nghĩa của chúng chiếm dưới 10% cửa sổ ngữ cảnh, rồi chuyển sang tải theo yêu cầu khi đạt ngưỡng đó;
• auto:N — áp dụng nguyên tắc tương tự, với ngưỡng phần trăm do người dùng đặt;
• false — tắt hoàn toàn cơ chế và tải trước tất cả công cụ.

Ngoài ra còn có biến CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: nếu biến này được đặt, tính năng tìm kiếm công cụ vẫn tắt và việc người dùng đặt ENABLE_TOOL_SEARCH không làm thay đổi điều đó. Ngoại lệ là khi tổ chức giữ tính năng tìm kiếm công cụ ở trạng thái bật thông qua cài đặt được quản lý, bắt đầu khả dụng từ Claude Code phiên bản 2.1.227.

alwaysLoad làm gì và ảnh hưởng đến ngữ cảnh cũng như thời gian khởi động ra sao#

Trường alwaysLoad: true trong cấu hình của máy chủ khả dụng với mọi loại máy chủ. Với trường này, tất cả công cụ của máy chủ đó được tải vào ngữ cảnh khi khởi động, bất kể cài đặt ENABLE_TOOL_SEARCH. Tác tử không cần tìm kiếm các công cụ đó trước khi sử dụng.

Việc luôn tải công cụ có hai hệ quả. Mỗi công cụ được tải trước chiếm một phần ngữ cảnh vốn có thể dành cho chính tác vụ. Ngoài ra, lúc khởi động phiên sẽ chờ máy chủ này kết nối, trong giới hạn thời gian chờ tiêu chuẩn là năm giây.

Ngoại lệ là máy chủ từ xa có mục hợp lệ trong bộ nhớ đệm: máy chủ cung cấp công cụ từ bộ nhớ đệm mà không cần kết nối và không làm chậm quá trình khởi động. Bộ nhớ đệm khám phá mặc định tắt, trừ khi đã được bật cho tài khoản trong quá trình triển khai dần tính năng này. Bạn cũng có thể bật rõ ràng bằng MCP_DISCOVERY_CACHE=1. Ngoại lệ khởi động nhanh áp dụng khi bộ nhớ đệm đang hoạt động và chứa mục hợp lệ. Công cụ có alwaysLoad vẫn chiếm chỗ trong ngữ cảnh lâu dài, bất kể tác tử có cần đến chúng khi làm việc bằng tính năng tìm kiếm hay không.

Dành cho những người tự viết máy chủ MCP: hướng dẫn của máy chủ giúp Claude hiểu khi nào cần tìm công cụ của máy chủ, tương tự như Skills. Theo mặc định, Claude Code cắt ngắn mô tả của từng công cụ và hướng dẫn của từng máy chủ xuống còn 2048 ký tự, vì vậy hãy đặt những chi tiết quan trọng ở phần đầu.

Việc chọn cách mở rộng Claude Code phụ thuộc vào nhiều yếu tố hơn là số lượng máy chủ MCP được kết nối. Các hướng dẫn Claude Code: nên giữ bao nhiêu tiện ích mở rộng cùng lúc và Nên chọn gì trong Claude Code: Skills, Subagents, MCP hay Plugins xem xét Skills, Subagents, MCP và Plugins cho các tác vụ khác nhau. Để thiết lập từng bước các máy chủ MCP cụ thể, hãy xem Máy chủ MCP cho Claude Code: các tổ hợp có sẵn.

Tiếp theo nên làm gì#

Với một bộ dưới khoảng 10 công cụ có định nghĩa vừa vặn trong ngữ cảnh mà không gặp khó khăn, tài liệu Agent SDK lưu ý rằng tải tất cả cùng lúc thường nhanh hơn. Tuy nhiên, trong hành vi mặc định của Claude Code, khi biến không được đặt và không có giới hạn nào ở trên áp dụng, tính năng tìm kiếm công cụ được bật và việc tải công cụ MCP được hoãn lại cho đến lúc tìm kiếm, ngoại trừ các máy chủ có alwaysLoad.

Trong trường hợp này, bạn có thể đặt rõ ràng ENABLE_TOOL_SEARCH=auto: các định nghĩa sẽ được tải trước khi tổng dung lượng của chúng nhỏ hơn 10% cửa sổ ngữ cảnh, và tính năng tìm kiếm sẽ được bật khi đạt ngưỡng. Một lựa chọn khác là ENABLE_TOOL_SEARCH=false nếu bạn biết bộ công cụ sẽ không tăng lên. Khi đó, Claude Code sẽ ngừng báo cho mô hình biết các kết nối máy chủ bị lỗi như mô tả ở trên.

Trong các trường hợp khác, hãy kiểm tra lại điều kiện hoạt động khi môi trường thay đổi:

• chuyển sang Sonnet/Haiku/Opus 4.5 trở lên nếu phiên đang dùng mô hình cũ hơn;
• nếu kết nối sử dụng ANTHROPIC_BASE_URL không chuẩn, chỉ đặt rõ ràng ENABLE_TOOL_SEARCH=true khi chính proxy chuyển tiếp được các khối tool_reference;
• bảo đảm nền tảng triển khai không thuộc danh sách ngoại lệ: Azure Foundry hoặc các mô hình Google Cloud Agent Platform cũ hơn.

Nếu đáp ứng các điều kiện và cài đặt không chặn chức năng tìm kiếm, bạn có thể kết nối các máy chủ MCP cần thiết. Chỉ dùng alwaysLoad cho những máy chủ có công cụ cần thiết trong mọi lượt của phiên; để các máy chủ còn lại tải thông qua tìm kiếm.

Nếu bạn cần truy cập các mô hình AI thông qua Ailoot, hãy ghé thăm Ailoot.