---
title: "MCP"
description: "配置 MCP server、理解三层合并规则，并排查连接与 OAuth 状态"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

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

## 项目级配置

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

```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

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

### HTTP 与 OAuth

```json
{
  "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 流程，不是通用的配置编辑或手动重连按钮。

> **Note**
>
> 代码中存在供初始化或 OAuth 流程使用的 reconnect 能力，但当前面板没有面向任意 server 的通用“重新连接”操作。排障时以重启进程重新装配为准。

## 排障

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

## 安全边界

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

Source: https://konghayao.github.io/peri-cool/docs/features/mcp/index.mdx