MCP 运行时

Agent Plugins 定义 mcp.json 如何选择传输方式并提供运行时配置。MCP 定义消息成帧、初始化、能力协商、授权和生命周期。

支持 MCP 的 Agent Plugins 客户端必须至少支持 stdio 和 Streamable HTTP 中的一种，并且应支持两者。旧版 HTTP+SSE 支持是可选的。

配置模型

mcp.json 包含一个 mcpServers 对象，其成员是相互独立配置的服务器。每个条目声明一个 type，并且只能包含该传输方式允许的字段：

mcp.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-tools": {
      "type": "stdio",
      "command": "./bin/server",
      "args": ["--data", "${PLUGIN_DATA}"]
    },
    "remote-tools": {
      "type": "streamable-http",
      "url": "https://tools.example.com/mcp"
    }
  }
}

所有字段和限制请参阅面向插件作者的 MCP 服务器参考。

选择声明的传输方式

type 字段选择首次连接尝试所用的传输方式，并不是与传输无关的 URL 提示。读取 type 后实例化对应的 MCP 传输。如果尝试失败，Agent Plugins 不定义回退行为。实现回退的客户端可以遵循 MCP 的向后兼容指南。

Streamable HTTP 内使用的 SSE 响应和流仍属于 streamable-http，与已弃用的 HTTP+SSE 传输不同。重定向仍受已选传输方式和下述标头转发规则约束。

分两阶段验证

首先验证顶层 mcp.json：JSON 有效、$schema 与受支持的值匹配、插件规范版本一致、包含必需的 mcpServers，且不存在未知顶层字段。顶层验证失败会禁用该插件的 MCP。

然后按照条目所声明 type 的要求分别验证各服务器条目。传输类型未知、字段未知或传输字段缺失或无效时，只会使该条目无效。跳过它，但不禁用有效的同级条目或其他组件类型。规范 Schema 为此提供了 #/$defs/server。

启动 stdio 服务器

将 command 视为单个可执行文件标记，并单独传递 args。
按平台的可执行文件搜索规则解析纯命令。
相对于插件根目录解析以 ./ 开头的命令，并强制执行目录包含约束。参数和环境变量值即使看起来像路径，仍是不透明字符串。
cwd 的默认值为插件根目录。
启动前创建专用的可写 PLUGIN_DATA 目录，并在插件更新时保留它。
将配置的 env 叠加到客户端选定的基础环境中，最后设置由客户端控制的 PLUGIN_ROOT 和 PLUGIN_DATA。
仅在 args、env 值和 cwd 中展开插件变量。

客户端可以继承、省略或清理环境中的变量。可移植插件不能依赖未规定的环境变量，也不能依赖配置的 PATH 来影响纯命令的解析。

启动后，遵循 MCP 的 stdio 传输和生命周期要求。

连接远程服务器

连接前验证 URL 和字面量标头。未经用户明确授权，绝不能通过重定向或旧版 SSE 端点事件将配置的标头转发到其他来源。

遵循 MCP 的 Streamable HTTP 传输、生命周期和授权要求。Agent Plugins 没有定义可移植的 OAuth 或凭据引用字段；授权发现、凭据存储和用户交互由客户端管理。身份验证失败属于连接失败，不代表包配置无效。

运行时故障

如果某个服务器无法启动、连接、通过身份验证或完成 MCP 握手，继续加载其他服务器和组件。在可行时报告该故障。