MCP

MCP（Model Context Protocol）让 Peri 连接外部工具和资源。工具是否可用取决于当前配置、插件启用状态以及 server 是否连接成功，并非所有会话都有相同的 MCP 工具集。

项目级配置

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/data"]
    }
  }
}

Peri 在启动会话宿主时读取 MCP 配置。当前没有经过验证的配置文件监听或用户可用的热重载入口；修改 .mcp.json 或全局 settings 后，请重启 Peri，再到 /mcp 面板检查状态。

三类配置来源

来源	位置	合并行为
全局	`~/.peri/settings.json` 中的 `config.mcpServers` 或顶层 `mcpServers`	先加载
已启用插件	插件 manifest	server 名会加插件命名空间
项目	`<cwd>/.mcp.json`	最后加载；与全局同名时覆盖整项

合并顺序是 global → plugin → project。插件 server 使用命名空间，不能仅凭原始短名称推断它会被项目配置覆盖；与手动配置内容相同的插件项还会按配置内容去重。项目与全局同名时，项目定义覆盖全局定义，不做字段级合并。

传输方式

配置	传输
含 `command`	stdio；`args` 与 `env` 可选
不含 `command`、含 `url`	streamable HTTP；`headers` 与 `oauth` 可选
两者都没有	配置无效

同时提供 command 和 url 时，当前实现优先选择 stdio。

stdio

{
  "mcpServers": {
    "my-tool": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": {
        "API_KEY": "${MY_TOOL_API_KEY}"
      }
    }
  }
}

HTTP 与 OAuth

{
  "mcpServers": {
    "remote-service": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${REMOTE_MCP_TOKEN}"
      },
      "oauth": {
        "enabled": true
      }
    }
  }
}

配置字符串支持 ${VAR} 环境变量展开。变量未设置时会被替换为空字符串并记录警告，因此连接失败时先检查启动 Peri 的进程环境。

Agent 如何使用 MCP 工具

MCP 工具属于 deferred tools：它们不会全部直接放进模型的常驻工具列表。Agent 通常先用 SearchExtraTools 按名称或关键词发现工具，再通过 ExecuteExtraTool 执行。用户只需描述任务，不需要手写这两步。

只有连接成功并完成工具发现的 server 才会贡献可执行工具。server 启动失败、认证未完成或连接断开时，对应工具可能不会出现在搜索结果中。

`/mcp` 面板

面板展示初始化阶段、连接数、server 状态、传输方式和工具数量。常规列表是只读状态视图：添加、删除或修改 server 仍需编辑 .mcp.json 或 settings.json，然后重启 Peri。

对于标记为需要认证的 HTTP server，面板提供 OAuth 详情与授权入口。这个入口只处理 OAuth 流程，不是通用的配置编辑或手动重连按钮。

排障

确认 JSON 能解析，server 至少配置 command 或 url。
stdio server 先在同一终端单独运行其命令，检查可执行文件、参数和环境变量。
HTTP server 检查 URL、代理、证书、header 和 OAuth 状态。
重启 Peri，在 /mcp 查看初始化状态和失败原因。
用自然语言要求 Agent 查找对应能力；不要假设一个未连接的工具仍可执行。

安全边界

stdio server 以当前用户权限运行；它能访问什么，取决于该进程和操作系统权限。
HTTP 返回内容可能包含 prompt injection。把远程工具输出当作不可信输入。
凭据优先通过环境变量传入，不要把 token 提交进 .mcp.json。
MCP 工具仍受 Peri 权限模式影响，但权限审批不是操作系统沙箱。