MCP
添加 stdio 和 HTTP 的 MCP 服务器,设置凭据、审批策略和暴露策略,连接并检查服务器。
MCP(Model Context Protocol)服务器可以把本地程序或远程服务的工具提供给模型。服务器可能访问文件、网络、数据库和第三方账号,因此请只添加你信任的服务器,并为它的工具设置合适的审批策略。
服务器保存在配置目录的 mcp.toml 中,完整的字段见配置参考。
添加服务器
由 Agent 启动的本地程序。程序和参数写在 -- 之后,--env 设置环境变量(可重复):
hanafubuki-agent mcp add files -- npx -y @modelcontextprotocol/server-filesystem /home/me/notes
hanafubuki-agent mcp add search --env SEARCH_REGION=cn -- /usr/local/bin/search-mcp --stdio程序可以是绝对路径,也可以是在 PATH 中查找的程序名。stdio 服务器继承 Agent 进程的完整环境。
- 服务器 ID 只能包含 1 到 128 个字母、数字、
-、_和.。读取mcp.toml时,ID 不符合要求的服务器会像其他无法使用的服务器一样被丢弃(见配置恢复),其他服务器保留。 - 新服务器使用默认设置:审批策略
ask、暴露策略deferred、调用超时 120 秒等。 - 启用的服务器添加后立即连接,命令打印连接结果,例如
files: ready。--disabled添加一个禁用的服务器。
插件的服务器
启用的已安装插件运行它声明的 MCP 服务器。它们属于插件:不在 mcp.toml 中,不能在那里编辑,随插件出现和消失,插件启用时连接、关闭时断开,无需重启。它们和你添加的服务器一样运行:同样的连接、重连和审批规则,使用新服务器的默认设置(审批 ask、暴露 deferred)。
- Codex、Claude Code 和 Cursor 的包在包根目录的
.mcp.json中声明它们,或在清单的mcpServers中声明(指向这样一个文件的路径,或者服务器本身),写成{"mcpServers": {"NAME": {...}}}或按名称排列的服务器映射本身。服务器有command、args、env和cwd(stdio)或url和headers(http_headers)(Streamable HTTP),还可以有type、enabled、required、startup_timeout_sec、tool_timeout_sec、enabled_tools、disabled_tools和oauth(允许登录)。相对的cwd或命令路径位于包内;${CLAUDE_PLUGIN_ROOT}、${CLAUDE_PLUGIN_DATA}、${PLUGIN_ROOT}和${PLUGIN_DATA}被替换为包的目录及其数据目录,stdio 服务器运行时设置这四个变量。其他字段被忽略;bearer_token_env_var和env_http_headers被拒绝。 - Agent Plugins 包在其根目录的
mcp.json中声明它们,按其 1.0.0 schema 严格读取:只有$schema和mcpServers;stdio服务器的command是裸名称或包内的./路径,它的args和env可以使用${PLUGIN_ROOT}和${PLUGIN_DATA}(env不能设置这两个变量),它的cwd是./…、${PLUGIN_ROOT}/…或${PLUGIN_DATA}/…,必须存在并留在其中;streamable-http服务器的 URL 必须是 HTTPS,除非在回环地址上,客户端自己的头(Authorization、Content-Type等)被丢弃;不支持sse。schema 未定义的字段会使该服务器失败。 - 一个坏服务器只影响它自己:它列在插件的问题中,其他服务器照常运行。
- **一个名称只运行一次。**你在
mcp.toml中的服务器优先:插件的同名服务器让出,在你删除自己的服务器后再次运行。插件之间,键的顺序(<plugin>@<marketplace>)中的第一个胜出。让出的服务器记为其插件的问题。 - 你可以限制插件的服务器,在
[plugins."PLUGIN@MARKETPLACE".mcpServers.NAME]中设置enabled、enabledTools和disabledTools(插件)。
门面的 MCP 快照把它们列为 pluginServers,每个带有它的插件、配置和状态。
在终端界面中
终端界面中的 /mcp 在 MCP 服务器处打开设置中心,逐个字段添加和编辑服务器,每个改动立即生效:
- 服务器列表:每个服务器显示命令或 URL、连接阶段(
starting、ready、failed等)、连接后的工具数量以及最近的错误。a添加一个(以 ID 命名;新服务器从默认设置开始),d确认后删除,Enter 打开。 - 服务器:传输方式(stdio:程序、以列表填写的参数、工作目录和环境变量;Streamable HTTP:URL、OAuth
Off、Optional或Required,以及请求头)、是否启用、是否必需、协议模式(legacy或v20260728)、默认审批和暴露策略、只允许和不允许的工具、按工具的列表:单次调用上限(TOOL=数字,1 到 64)、审批(TOOL=allow|ask|deny)和暴露(TOOL=direct|direct_model_only|deferred|hidden),以及各项超时和并发调用数。环境变量和请求头是NAME=VALUE形式的条目。下方是 Delete、Connect、Disconnect、Refresh、Log out 和 Log in(OAuth 登录)。 - MCP secrets:值需要保密的环境变量或请求头各自是一条记录
SERVER/NAME。它的值保存为服务器通过credentialEnvironment或credentialHeaders引用的凭据,以服务器和变量命名(github-GITHUB_TOKEN),默认显示为••••。Enter 打开已保存的值,Ctrl+R 显示或隐藏且不触发保存,Enter 保存编辑。删除机密、删除服务器或服务器换掉传输方式时,没有其他服务器使用的凭据会被删除。 - 每次写入都会带上设置中心读取时
mcp.toml的版本;如果设置在此期间被修改,写入会被拒绝,服务器会重新读取,改动保留,可以再次保存。 - 插件的 MCP 服务器(Tools 标签页中的 Plugins' MCP servers):已开启的已安装插件运行的每个服务器一条记录(
PLUGIN/SERVER),显示连接阶段、工具和最近的错误。它如何运行仍由插件决定;你可以开启或关闭它、收窄它的工具(只用这些、不用这些),写在config.toml的[plugins."<plugin>".mcpServers.<server>]下(配置参考),r让某个键回到插件自己的值。每次改动后插件会重新加载。 - 服务器工具的调用逐项显示它返回的内容(工具调用):文本(JSON 会排版);图片或音频显示为类型和大小(
image/png · 33.2 KiB),从不显示数据;链接或嵌入的资源显示为地址(渲染)。 /mcp verbose把服务器和它们的工具(包括已安装插件的)写入对话,/mcp login ID在设置中心中该服务器的记录上打开它的登录。
凭据
mcp add 不设置凭据。需要令牌的服务器,可以在 /mcp 的 MCP secrets 中添加(见上文),或者编辑 mcp.toml:把环境变量或请求头指向 [credentials] 中的一个键,凭据的值只保存在那里(文件只有自己可读)。
[[servers]]
id = "github"
# ……
[servers.transport]
type = "stdio"
program = "github-mcp-server"
argv = ["stdio"]
[servers.transport.credentialEnvironment]
GITHUB_PERSONAL_ACCESS_TOKEN = "github-token"
[credentials.github-token]
value = "ghp_..."
generation = 1- stdio 继承平台基础环境;
transport.environmentVariables列出额外继承的名称,显式配置的公开变量和凭据覆盖继承值。见环境变量。 - 不是秘密的变量和请求头写在
publicEnvironment和publicHeaders中。 - 修改凭据的值时,同时把
generation加一。 - 引用了不存在的凭据键的服务器无法连接。
- 编辑前请先退出正在运行的 Agent;修改在下次启动时生效。
mcp list 只打印环境变量和请求头的名字,以及哪些凭据已经设置,从不打印它们的值。
宿主可以一次设置或删除一个凭据(mcp_set_credential、mcp_remove_credential),见嵌入 Agent。
OAuth 登录
oauth 为 "optional" 或 "required" 的 Streamable HTTP 服务器可以用 OAuth 登录:
hanafubuki-agent mcp add docs --oauth required --url https://mcp.example.com/mcp
hanafubuki-agent mcp login docsmcp login打印授权 URL。请在同一台机器的浏览器中打开它:授权后浏览器会被带回http://127.0.0.1:端口/callback,这是命令只为这次登录监听的端口,页面提示可以关闭标签页。- 命令最多等待 5 分钟,之后打印
docs: logged in和服务器的状态。Ctrl-C 可以结束它。 - 令牌保存在平台的安全存储(钥匙串)中,不在
mcp.toml里;钥匙串不可用时(doctor会检查),登录无法保存令牌。 oauth为"disabled"(默认)的服务器拒绝登录:OAuth is disabled for this MCP server。- 在终端界面中,
/mcp login docs(或在/mcp中服务器的 Log in)以同样的方式登录:页面显示要打开的地址(c复制它;对话中也会保留),等待浏览器,按 Esc 取消登录。
审批和暴露策略
每个服务器有默认的策略,也可以为单个工具设置:
[[servers]]
id = "github"
approvalPolicy = "ask"
exposurePolicy = "deferred"
disabledTools = ["delete_repository"]
[servers.toolApprovalPolicies]
get_issue = "allow"
list_issues = "allow"
[servers.toolExposurePolicies]
search_code = "direct"审批策略(approvalPolicy、toolApprovalPolicies):
| 值 | 行为 |
|---|---|
"allow" | 工具声明自己没有破坏性(destructiveHint: false)时不需要审批;没有声明的工具视为有破坏性,仍然需要审批 |
"ask"(默认) | 按权限模式处理:手动模式下询问你 |
"deny" | 拒绝调用,任何权限模式下都不执行 |
暴露策略(exposurePolicy、toolExposurePolicies)决定模型如何看到工具:
| 值 | 行为 |
|---|---|
"direct" | 每次请求都把工具交给模型 |
"deferred"(默认) | 不直接交给模型,模型通过 tool_list 浏览名称,需要时用 search_tools 获取定义,节省上下文 |
"hidden" | 不提供给模型 |
"direct_model_only" | 与 direct 相同,用于只给模型、不给应用界面的工具 |
enabledTools 非空时只开放列出的工具;disabledTools 中的工具不开放。
模型看到的工具名形如 mcp__服务器__工具,名字中 [A-Za-z0-9_-] 以外的字符会被替换为 _。
连接
- Agent 启动时在后台连接所有启用的服务器,每次最多 4 个。
- 连接断开的服务器会在 2 秒、10 秒和 30 秒后重新连接,10 分钟内最多 3 次。
required = true的服务器是必需的:启动时连接失败会记录错误,它的工具无法使用时,回合的这一步失败。- 会启动 Agent 的管理命令(例如
sessions list)也会在后台连接服务器。
hanafubuki-agent mcp connect files # 连接并打印状态和工具数,例如 files: ready (11 tools)
hanafubuki-agent mcp list
hanafubuki-agent mcp remove files
hanafubuki-agent doctor --online # 连接每个启用的服务器并报告结果mcp connect 在服务器没有达到 ready 时以退出码 1 失败,并打印错误。
在终端界面中输入 /mcp,可以查看每个服务器的命令或 URL、连接状态、工具和最近的错误;/mcp verbose 把服务器、它们的错误和工具写入对话。
资源
服务器提供的资源通过 list_mcp_resources、list_mcp_resource_templates 和 read_mcp_resource 读取,不需要审批。
| 工具 | 参数与结果 |
|---|---|
list_mcp_resources | 可选的 server 和 cursor;返回 resources,即服务器分页结果的数组 |
list_mcp_resource_templates | 参数相同;返回 resourceTemplates,用于需要填入 URI 参数的资源 |
read_mcp_resource | 必填 server 和确切的 uri;返回该服务器提供的内容 |
不传 server 时,列表查询当前模型步骤绑定的服务器。每页都有 server、items 和 nextCursor。继续读取时,将该页不透明的 nextCursor 作为 cursor,同时传入所属 server;只有游标、没有服务器的请求会被拒绝。每个服务器独立翻页,不要解析或重建游标。
可选服务器失败时,错误出现在 failures,成功的分页结果仍然可用;必需服务器失败则使整个调用失败。较大的列表可能为了适应模型输出预算而省略条目,应检查 truncated、omittedItems 和 warning,不能直接视为完整列表。可以指定服务器缩小结果范围,并在有游标时继续翻页。
资源 URI 和模板描述是服务器提供的元数据。读取只把 URI 交给当前步骤捕获的指定 MCP 连接;即使是 file: 或 https: URI,Agent 也不会将其作为本地文件打开或另行抓取。嵌入应用的连接、OAuth 与 elicitation 控制见 MCP 管理。
MCP 与记忆
开启 memory.excludeExternalContext 后,会话一旦使用了网页或 MCP 工具的结果,就不再用于提取记忆,避免未经核实的外部内容进入记忆。见记忆。