--- title: MCP 运行时 description: 将可移植 MCP 配置映射到原生连接，并隔离服务器故障。 --- # MCP 运行时 Agent Plugins 定义 `mcp.json` 如何选择传输方式并提供运行时配置。MCP 定义消息成帧、初始化、能力协商、授权和生命周期。 支持 MCP 的 Agent Plugins 客户端必须至少支持 stdio 和 Streamable HTTP 中的一种，并且应支持两者。旧版 HTTP+SSE 支持是可选的。 ## 配置模型 [#配置模型] `mcp.json` 包含一个 `mcpServers` 对象，其成员是相互独立配置的服务器。每个条目声明一个 `type`，并且只能包含该传输方式允许的字段： ```json title="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 服务器参考](/zh/plugin-authors/mcp-servers)。 ## 选择声明的传输方式 [#选择声明的传输方式] `type` 字段选择首次连接尝试所用的传输方式，并不是与传输无关的 URL 提示。读取 `type` 后实例化对应的 MCP 传输。如果尝试失败，Agent Plugins 不定义回退行为。实现回退的客户端可以遵循 MCP 的[向后兼容指南](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#backwards-compatibility)。 Streamable HTTP 内使用的 SSE 响应和流仍属于 `streamable-http`，与已弃用的 HTTP+SSE 传输不同。重定向仍受已选传输方式和下述标头转发规则约束。 ## 分两阶段验证 [#分两阶段验证] 首先验证顶层 `mcp.json`：JSON 有效、`$schema` 与受支持的值匹配、插件规范版本一致、包含必需的 `mcpServers`，且不存在未知顶层字段。顶层验证失败会禁用该插件的 MCP。 然后按照条目所声明 `type` 的要求分别验证各服务器条目。传输类型未知、字段未知或传输字段缺失或无效时，只会使该条目无效。跳过它，但不禁用有效的同级条目或其他组件类型。规范 Schema 为此提供了 `#/$defs/server`。 ## 启动 stdio 服务器 [#启动-stdio-服务器] * 将 `command` 视为单个可执行文件标记，并单独传递 `args`。 * 按平台的可执行文件搜索规则解析纯命令。 * 相对于插件根目录解析以 `./` 开头的命令，并强制执行目录包含约束。参数和环境变量值即使看起来像路径，仍是不透明字符串。 * `cwd` 的默认值为插件根目录。 * 启动前创建专用的可写 `PLUGIN_DATA` 目录，并在插件更新时保留它。 * 将配置的 `env` 叠加到客户端选定的基础环境中，最后设置由客户端控制的 `PLUGIN_ROOT` 和 `PLUGIN_DATA`。 * 仅在 `args`、`env` 值和 `cwd` 中展开插件变量。 客户端可以继承、省略或清理环境中的变量。可移植插件不能依赖未规定的环境变量，也不能依赖配置的 `PATH` 来影响纯命令的解析。 启动后，遵循 MCP 的 [stdio 传输](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#stdio)和[生命周期](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)要求。 ## 连接远程服务器 [#连接远程服务器] 连接前验证 URL 和字面量标头。未经用户明确授权，绝不能通过重定向或旧版 SSE 端点事件将配置的标头转发到其他来源。 遵循 MCP 的 [Streamable HTTP 传输](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http)、[生命周期](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)和[授权](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)要求。Agent Plugins 没有定义可移植的 OAuth 或凭据引用字段；授权发现、凭据存储和用户交互由客户端管理。身份验证失败属于连接失败，不代表包配置无效。 ## 运行时故障 [#运行时故障] 如果某个服务器无法启动、连接、通过身份验证或完成 MCP 握手，继续加载其他服务器和组件。在可行时报告该故障。 --- Source: [content/docs/client-implementers/mcp-runtime.mdx](https://github.com/agentplugins/agent-plugins-site/blob/237bbf575f5843214923419f9d0933852662f4f3/content/docs/client-implementers/mcp-runtime.mdx) Source commit: 237bbf575f5843214923419f9d0933852662f4f3 --- For a semantic overview of all documentation, see [/zh/sitemap.md](/zh/sitemap.md) For an index of all available documentation, see [/zh/llms.txt](/zh/llms.txt)