输出限制、工具搜索与高级能力

版本要求与措辞以官方为准。

输出限制与警告

MCP 工具产生大输出时，Claude Code 帮助控制 token 用量：任一 MCP 工具输出超过 10,000 token 时显示警告；默认最大 25,000 token，用 MAX_MCP_OUTPUT_TOKENS 调整（如 MAX_MCP_OUTPUT_TOKENS=50000 claude）。该环境变量作用于没有声明自己限制的工具；声明了 anthropic/maxResultSizeChars 的工具对文本内容用该字符上限，不管 MAX_MCP_OUTPUT_TOKENS 如何；返回图片数据的工具仍受 token 限制。结果（不含图片内容）超过限制时，Claude Code 把它保存到会话 tool-results 目录下的文件，并在对话里用一条点名文件路径的消息替换它，Claude 需要内容时去读该文件。给某个工具调高上限（面向 MCP 服务器作者）：在工具的 tools/list 响应条目里设 _meta["anthropic/maxResultSizeChars"]，Claude Code 把该工具的阈值提高到标注值（有上限），适合返回本来就大而必要的输出的工具（如数据库 schema、完整文件树）；它独立于 MAX_MCP_OUTPUT_TOKENS 对文本生效，用户不必调高环境变量。经常遇到你不能控制的服务器的输出警告时，可以调高 MAX_MCP_OUTPUT_TOKENS，或请服务器作者加这个标注或做分页。工具结果里的图片：MCP 工具返回 PNG、JPEG、GIF、WebP 图片时，Claude 在对话里内联看到图片（内联副本可能被缩小或压缩以符合模型的图片大小限制），Claude Code 还把原始字节保存到会话 tool-results 目录下的文件（需要 v2.1.283+；用 --no-session-persistence 或 CLAUDE_CODE_SKIP_PROMPT_HISTORY 关闭会话持久化时不写图片文件，Claude 只收到内联副本）。

schema 处理

根级组合器：有些 MCP 服务器把工具输入 schema 声明为 JSON Schema 联合，在 schema 顶层用 anyOf、oneOf 或 allOf；Claude API 不接受这些关键字出现在 schema 根部（嵌套在 properties 里的组合器则原样发送）。这类工具仍然可用：Claude Code 在发给 API 之前把 schema 展平成单个对象，并在工具描述前加一句话告诉 Claude 哪些参数组属于一起——allOf 合并每个分支的属性且各分支的 required 仍然适用；anyOf/oneOf 合并每个分支的属性，各分支的 required 改为在描述里说明而不是由 schema 强制。服务器收到的是 Claude 选的任意参数，所以服务端仍要校验参数组合。Claude Code 产生不出 API 接受的 schema、或在没拿到启用该改写的远程配置的部署上，会跳过那一个工具、在服务器日志里记录原因，其他工具仍可用。无效 schema：Claude API 检查请求里每个工具的输入 schema，任何一个失败就拒绝整个请求（一个 schema 畸形的 MCP 工具会让包含它的每个请求都以 400 失败）。Claude Code 加载服务器工具时自己先做两项检查：顶层属性名长度 1 到 64 且只含 ASCII 字母、数字、_、.、-；schema 必须符合 JSON Schema draft 2020-12 元模式（对未声明 $schema 或声明 2020-12 的 schema 应用；声明其他方言的跳过这项，属性名检查仍适用）。排除某个工具时 Claude Code 在服务器日志里记录原因，并告诉 Claude 排除了哪些工具及原因（你可以问 Claude 为什么缺了某个工具）；服务器上修好 schema 后，下次加载工具时该工具就回来。该排除通过 Claude Code 从 Anthropic 拉取的功能开关开启；开关拉取关闭或从未到达（如隔离网络的机器）时仍运行检查，并在服务器日志里记录哪个工具会被拒绝；根级组合器处理是独立的。

对某个工具要求每次批准

MCP 服务器作者可以在工具的 tools/list 响应条目里把 _meta["anthropic/requiresUserInteraction"] 设为 JSON 布尔值 true（其他值被忽略），标记该工具每次调用都要明确批准：Claude Code 每次调用都显示它的权限提示，即使在 acceptEdits、auto、bypassPermissions 模式下，也不提供「不再询问」，匹配它的 allow 规则也不跳过；不会提示的 dontAsk 模式下该调用被拒绝。提示必须到达一个人：非交互模式带 --permission-prompt-tool 时，对被标记工具的提示工具返回 allow 会被转成拒绝，消息为 MCP tool requires user interaction; not supported via --permission-prompt-tool；Agent SDK 的 canUseTool 同理。用于权限提示本身就是重点的工具，如同意或授权步骤（自动批准意味着没有人真正同意过）；同一服务器的其他工具保持正常权限行为。需要 Claude Code v2.1.199+（更早版本忽略它）。Remote Control 和基于 Agent SDK 的应用等界面通常让你一键批准工具调用，对带此标注的工具，Claude Code 不提供一键动作而显示完整权限提示，使批准仍然来自人；对任何只有终端对话框才能完整呈现的权限请求（如带安全警告或远程界面显示不了的「总是允许」选项的请求）也同样不提供一键批准，你要在终端对话框里回答。

响应 elicitation 请求

MCP 服务器可以在任务中途用 elicitation 向你请求结构化输入：服务器需要它自己拿不到的信息时，Claude Code 显示交互对话框并把你的回应传回服务器，你这边不需要任何配置。两种方式：表单模式（对话框里是服务器定义的表单字段，如用户名和密码提示，填写并提交）；URL 模式（Claude Code 问你是否在浏览器里打开链接，你接受就打开；服务器用它做在终端之外完成的流程，如登录）。URL 模式下 Claude Code 把 URL 作为命令行参数传给系统的 URL 处理程序，并限制该参数的长度；URL 转义到命令行后超过上限，你只能拒绝该请求（需要转义的每个字符如 %、& 都计入长度）。想不显示对话框就自动响应 elicitation，用 Elicitation Hook。在使用协议修订 2026-07-28 的连接上，Claude Code 在客户端能力里声明 elicitation: {form: {}, url: {}}，所以服务器可以通过协议标准的 elicitation 请求要求任一模式。

资源与提示

资源：MCP 服务器可以暴露资源，用 @ 提及引用，类似引用文件。在提示里输入 @ 可看到所有已连接服务器的可用资源（与文件一起出现在补全菜单里）；用 @server:protocol://resource/path 格式引用，一个提示里可引用多个；被引用的资源会自动获取并作为附件包含；资源路径在 @ 补全里可模糊搜索；服务器支持时 Claude Code 自动提供列出和读取 MCP 资源的工具；资源可含服务器提供的任何类型的内容（文本、JSON、结构化数据等）。MCP Apps UI 资源（ui:// URI 或 text/html;profile=mcp-app 媒体类型的条目）是供宿主应用渲染的页面而不是给 Claude 读的内容，它们不出现在 @ 建议或资源列表工具的结果里，只提供 UI 资源的服务器也不会因此出现资源条目。提示：MCP 服务器可以暴露在 Claude Code 里成为命令的提示：输入 / 可看到可用命令，MCP 提示显示为 /servername:promptname (MCP)，输入 /mcp__servername__promptname 也能运行；许多提示接受参数，在命令后用空格分隔传入（按空白拆分，每个参数是单个 token）；MCP 提示从已连接服务器动态发现，参数按提示定义的参数解析，提示结果直接注入对话；/mcp__servername__promptname 形式里服务器名中 A-Z、a-z、0-9、_、- 之外的字符被替换为 _，提示名按服务器声明的使用。名为 anthropic-skills 的服务器的提示不会出现（该名称保留给从 claude.ai 同步的 Skill），它的工具仍可用，改名后就能列出提示。

用工具搜索扩展规模

工具搜索把 MCP 工具定义推迟到 Claude 需要时才加载，使上下文占用保持很低：会话开始只加载工具名和服务器说明，所以多添加 MCP 服务器对上下文窗口影响很小；Claude Code 不对每个服务器施加固定的工具数上限。给 MCP 服务器作者：启用工具搜索时服务器说明字段更有用，它帮助 Claude 判断何时去搜索你的工具（类似 Skill 的作用）；写清楚你的工具处理哪类任务、Claude 何时应搜索你的工具、服务器的关键能力。Claude Code 默认把每个工具描述和每个服务器说明截断在 2048 字符，要保持简洁并把关键细节放在开头；用 CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH（需要 v2.1.280+）改变所有服务器的限制。配置工具搜索：默认启用（MCP 工具被推迟并按需发现）；当 ANTHROPIC_BASE_URL 指向非第一方主机时 Claude Code 把它关闭（多数代理不转发 tool_reference 块），显式设置 ENABLE_TOOL_SEARCH 可覆盖这个回退；设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 会让它保持关闭，你自己设 ENABLE_TOOL_SEARCH 无法覆盖（组织可在 v2.1.227+ 通过托管设置让它保持开启）；它要求模型支持 tool_reference 块（Claude Sonnet 4.5、Haiku 4.5、Opus 4.5 及更新）；Azure 上托管的 Microsoft Foundry 部署在服务端拒绝工具搜索，Claude Code 检测到拒绝后改为预先加载 MCP 工具（ENABLE_TOOL_SEARCH 无法覆盖）；Agent Platform 上 Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 及更新默认开启，更早的模型预先加载所有 MCP 工具。ENABLE_TOOL_SEARCH 取值：

值	行为
未设置	所有 MCP 工具被推迟并按需加载；在 Agent Platform 早于 Claude 4.5 一代的模型、ANTHROPIC_BASE_URL 是非第一方主机、或 Azure 上托管的 Foundry 部署时回退为预先加载
true	所有 MCP 工具被推迟（Azure 上托管的 Foundry 部署和 Agent Platform 的旧模型仍强制预先加载）
auto	阈值模式：工具定义总量低于上下文窗口 10% 时预先加载本会被推迟的工具，达到 10% 时全部推迟
auto:N	自定义百分比的阈值模式，N 为 0 到 100，如 auto:5
false	所有 MCP 工具预先加载，不推迟

可以在 shell 里设置，也可以放进 settings.json 的 env 字段；也可以单独禁用 ToolSearch 工具。让某个服务器不被推迟：服务器的工具总要对 Claude 可见而不经搜索一步时，在该服务器配置里设 alwaysLoad: true，它的所有工具就在会话开始时加载进上下文，不受 ENABLE_TOOL_SEARCH 影响（适合 Claude 几乎每个回合都用的少量工具）；alwaysLoad 适用于所有服务器类型；MCP 服务器也可以在某个工具的 _meta 里写 "anthropic/alwaysLoad": true，效果只作用于该工具。设置 alwaysLoad: true 还会让启动等待该服务器的工具（上限为标准的 5 秒连接超时，因为构建第一个提示时它们必须就位）；有有效 cached 条目的远程服务器从缓存提供工具而不必连接，所以不会拖慢启动。

托管 MCP 配置

需要集中控制用户能连接哪些 MCP 服务器的组织，见托管 MCP 配置：用 managed-mcp.json 部署固定的服务器集合、用 managedMcpServers 向每个用户提供服务器、用 allowedMcpServers 和 deniedMcpServers 限制服务器，详见设置项参考里的 MCP 部分。