第 6 章 · 03 权限、Prompts 与进阶用法

第 6 章 · 03 权限、Prompts 与进阶用法

本节摘要:MCP 接进来之后,有三件事决定用得好不好:权限(按服务器/工具粒度授予 ask/allow/deny)、Prompts 与资源(MCP 提示词变成 /mcp__server__prompt 斜杠命令,资源可用 @server:resource 引用)、性能与排查(工具搜索防上下文膨胀、输出限制防溢出、HTTP 状态码定位故障)。最后给出安全最佳实践清单。

学习目标

阅读完本节,你应当能够:

1. 用 mcp__服务器__工具 三级粒度配置工具权限,并说出 ask/allow/deny 的含义。
2. 调用 MCP 暴露的提示词(/mcp__server__prompt)与资源(@server:resource)。
3. 说出工具搜索机制、输出三层限制与自动后台化,并解释"代码执行解决上下文膨胀"的思路。
4. 按"先看状态码"的排查顺序定位 MCP 连接故障,并背出安全最佳实践要点。

一、工具权限:三级粒度与三态动作

MCP 工具出现在提示词里时,命名遵循 mcp__服务器__工具 模式(如 mcp__github__list_prs)。权限配置按同样的命名空间分三级粒度:

mcp__github__list_prs     # 工具级:精确到单个工具
mcp__github               # 服务器级:该服务器的全部工具
mcp__*                    # 全局:所有 MCP 服务器
​

每一级都可以授予三种权限动作之一:

• ask:每次调用前询问用户(默认态,最稳妥)。
• allow:自动放行,不打断流程。
• deny:禁止调用,直接拒绝。

实践建议:平时保持 ask;对完全信任、只读的服务器(如只查天气的 API)降为 allow;对来源不明或需要写操作的服务器保持 ask 甚至 deny。粒度越小越安全——只给实现任务必需的几个工具放行,而不是整服务器 allow。

二、MCP Prompts:斜杠命令与资源引用

Prompts 变成斜杠命令

MCP 服务器可以暴露提示词,它们以斜杠命令的形式出现在 Claude Code 里,命名规则:

/mcp__<server>__<prompt>
​

例如服务器 github 暴露了一个 review 提示词,调用方式就是 /mcp__github__review。这让你把"外部服务定义好的工作流"直接当命令用。

资源用 @ 引用

MCP 资源可以直接在提示词里引用,语法:

@server-name:protocol://resource/path
​

例如引用数据库里的特定资源:

@database:postgres://mydb/users
​

Claude 会抓取该资源内容,内联进对话上下文参与推理。

三、与权限相关的执行环境

几个让 MCP 融入工作流的机制:

子代理作用域 MCP:MCP 服务器可以写进子代理 frontmatter 的 mcpServers: 字段,只对该代理生效,父代理和兄弟代理都看不到——适合"某个代理需要专用工具"的场景:

---
mcpServers:
  my-tool:
    type: http
    url: https://my-tool.example.com/mcp
---

You are an agent with access to my-tool for specialized operations.
​

插件自带 MCP:插件可以在根目录放独立的 .mcp.json,或在 plugin.json 内联定义,安装即用;用 ${CLAUDE_PLUGIN_ROOT} 引用插件安装目录下的相对路径。注意插件子代理的沙箱限制:MCP 服务器对插件子代理不可用。

Claude.ai 连接器:在 Claude.ai 账号里配置的 MCP 服务器自动出现在 Claude Code 中(--print 模式也支持,v2.1.83+);本地与云端服务器默认并发连接减少启动延迟(v2.1.117+);用环境变量 ENABLE_CLAUDEAI_MCP_SERVERS=false 可关闭。这个特性仅对 Claude.ai 账号登录用户生效。

动态工具更新:服务器可以发 list_changed 通知动态增删工具,Claude Code 自动调整工具列表,无需重连或重启。

MCP Apps 与 Elicitation:MCP 调用可以返回内联 UI 组件(仪表盘、表单、可视化,官方第一个 MCP 扩展);服务器还能在流程中通过交互对话框向用户请求结构化输入(v2.1.49+)。

四、防上下文膨胀:工具搜索与输出限制

工具搜索

MCP 工具描述超过上下文窗口 10% 时,自动启用工具搜索,按需挑选相关工具而不是全量加载。环境变量 ENABLE_TOOL_SEARCH:

注意:工具搜索要求 Sonnet 4 或 Opus 4 及以上模型,Haiku 不支持。如果某台服务器的工具每轮都要用,配置 "alwaysLoad": true 跳过延迟加载——但慎用,每个常驻工具都在消耗上下文。

输出三层限制

上限可用 MAX_MCP_OUTPUT_TOKENS 调整。另外(v2.1.212+)超过 2 分钟的 MCP 调用自动转后台,会话不被阻塞;阈值用 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 调整。v2.1.84 起,每个服务器的工具描述与指令有 2 KB 上限,防止冗长定义吃掉上下文。

终极方案:代码执行替代直接调用

接几十个服务器、上千个工具后,最大的问题是上下文膨胀——工具定义先占一大块,中间结果再来回过两遍(比如把会议纪要转进 Salesforce,全文在上下文里进出两次,2 小时纪要 ≈ 5 万+ tokens)。Anthropic 工程团队的解法:让代理写代码,把 MCP 工具当 API 调。工具以类型化函数文件树呈现,数据在沙箱执行环境里直接流转,只有最终结果回到模型——实测 token 用量从约 15 万降到约 2 千(降 98.7%)。开源运行时 MCPorter(npx mcporter)把 MCP 服务器变成类型化 API 与 CLI,开箱即用。代价是需要安全的沙箱执行环境与监控;只有几个服务器时,直接调用反而更简单。

五、故障排查:先看状态码

第一步永远是看输出(v2.1.219+):claude mcp list(或会话内 /mcp)会在失败服务器旁打印 HTTP 状态码和服务器错误文本,不再是无信息量的 "failed to connect":

• 401 / 403 → 凭据错误或过期,claude mcp login <name> 重新认证。
• 404 → URL 错误,最常见是少了 /mcp 或 /sse 路径后缀。
• 5xx / 超时 → 远端服务挂了,查网络连通性与限流。

隐蔽空白字符(v2.1.219+):从浏览器/聊天里复制粘贴的 token 常带尾部空格或换行,原样塞进 Authorization 头就认证失败。Claude Code 会对配置值的前后空白给出警告,用 printf '[%s]\n' "$GITHUB_TOKEN" 检查并修剪。

无头运行的静默掉线(v2.1.219+):--mcp-config 传入的服务器若校验失败会被跳过而不是中止——-p 运行可能"看起来正常但少了半个工具集"。stream-json 的 init 事件带 mcp_server_errors 字段列出被跳过的条目,跑完务必检查:

claude -p "list my tools" --mcp-config ./servers.json \
  --output-format stream-json --verbose \
  | jq -r 'select(.type == "system" and .subtype == "init") | .mcp_server_errors'
​

其他常见问题:服务器未安装(npm list -g 验证)、环境变量未设置(echo $GITHUB_TOKEN)、端口冲突(查 ~/.claude/logs/)。

六、安全最佳实践

Do's:凭据一律走环境变量;token 定期轮换(建议每月);优先只读 token;MCP 访问范围最小化;监控请求与访问日志;能 OAuth 就 OAuth;请求限流;上线前测试;文档化所有活跃连接;保持服务器包更新。

Don'ts:不在配置文件写死凭据;不把 token 提交进 git;不在聊天/邮件里共享 token;团队项目不用个人 token;不给多余权限;不忽略认证错误;不公开暴露 MCP 端点;不用 root/admin 跑 MCP 服务器;不在日志缓存敏感数据;不关闭认证机制。

企业托管(managed-mcp.json):IT 管理员可以通过系统级配置文件强制服务器白名单(allowedMcpServers)与黑名单(deniedMcpServers,支持通配符,deny 优先于 allow),组织级策略先于用户配置生效,防止私自连接未授权服务器。位置:macOS /Library/Application Support/ClaudeCode/、Linux ~/.config/ClaudeCode/、Windows %APPDATA%\ClaudeCode\。

生命周期修复(v2.1.136):两个长期 bug 已修复,多服务器环境值得升级——/clear 后 .mcp.json/插件/Claude.ai 配置的服务器不再丢失(以前会静默消失需重启);多服务器 OAuth 并发刷新不再丢 refresh token("每天早上都要重新认证"的问题消失)。

小结

MCP 的三件进阶事:权限按 mcp__服务器__工具 三级粒度配 ask/allow/deny,越小越安全;能力上提示词变斜杠命令、资源可用 @ 引用,子代理/插件/Claude.ai 各有接入方式;性能上工具搜索、输出三层限制与代码执行方案共同对抗上下文膨胀。出问题时先看状态码,再查空白字符与 headless 静默跳过;安全清单十做十不做,企业场景用 managed-mcp.json 兜底。

下一节预告:MCP 是"向外接",第 7 章 Hooks 是"向内钩"——在工具调用、会话生命周期上挂自动化脚本。