---
title: "MCP 支持"
description: "从配置合并到工具执行，了解 Peri 如何接入 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 在 Peri 架构中的位置是外部能力接入层。它不负责 Agent 的推理循环，也不决定某个工具是否应该执行；它负责把 server 配置转换成连接，把连接上的工具和资源转换成当前 session 可以使用的能力。

Peri 在 `peri-middlewares` 中维护 `McpClientPool`。配置合并后形成冻结的 server 配置，连接句柄保存工具、资源和状态快照，运行中的 service 负责传输。TUI、print 和 stdio 入口共用这套装配结果，因此连接生命周期不会因入口不同而复制一份。

## MCP 在 Agent 链路中的位置

一次工具调用至少经过三层：MCP client 与 server 通信，MCP middleware 建立本地工具 bridge，Agent loop 决定是否调用以及如何处理结果。这样分层后，server 的连接失败不会被伪装成模型错误，模型没有选择某个工具也不会被误判为 MCP 连接失败。

工具发现和工具执行是两个阶段。连接初始化时 Peri 取得工具列表，随后根据 direct/deferred 属性决定工具如何进入当前工具视图。延迟工具由 ToolSearch 提供搜索和执行入口，模型先找到工具，再通过 `ExecuteExtraTool` 调用实际 bridge。

## 配置如何变成连接

MCP 配置来自全局、项目和插件等来源，Peri 在装配阶段完成合并，并保留 server 名称、类型、启动参数、环境和认证配置。stdio server 由本地命令启动；streamable HTTP server 则通过 URL 建立远程连接。

连接建立包含 transport 初始化、协议握手、能力协商和工具/资源发现。启动超时、握手失败、server 退出和 OAuth 未完成会分别记录状态；连接池不会因为一个 server 失败而丢弃其他 server 的结果。

## MCP 之上的两点处理

MCP 规定了工具和资源的交换方式，但没有替 Peri 解决两个宿主问题：怎样控制模型当前可见的工具数量，以及怎样把授权和连接失败放进会话状态。Peri 用 middleware 装配和 ToolSearch 处理前者，用独立的连接状态与 OAuth 流程处理后者。

这意味着“配置里有 server”不等于“模型现在能调用工具”。至少还要满足连接成功、工具列表取得、工具被当前 middleware 注册，以及模型通过直接工具或 ToolSearch 选中它。

## 失败边界

普通 MCP 连接失败只影响对应 server。OAuth server 可能先进入等待授权状态，完成授权后再建立连接；如果授权、回调或凭据读取失败，工具不会被注册为可调用能力。

订阅是连接后的可选能力，不是普通工具调用的前置条件。资源更新可以使资源缓存失效，并向注册 session 发送待处理消息；工具列表或资源列表变化主要使对应缓存失效，后续请求再决定是否回源。订阅流的异常恢复也不等于普通 MCP 连接自动重连。

## 这层设计带来的结果

MCP server 只需要遵守协议并提供工具，Peri 负责把它放进统一的 Agent 装配和会话生命周期。用户因此可以分别检查配置、连接、工具注册和实际调用，而不必把所有问题归结为“模型没有用工具”。

Source: https://konghayao.github.io/peri-cool/posts/engineering/mcp-support/index.mdx