---
title: MCP 服务器
description: 配置可移植的 stdio、Streamable HTTP 和旧版 HTTP+SSE MCP 连接。
---

# MCP 服务器



Agent Plugins 定义了封闭的 `mcp.json` 格式，客户端可将其映射到自身的 MCP 配置。[Model Context Protocol 规范](https://modelcontextprotocol.io/specification)仍是 MCP 线路行为和生命周期的权威依据。

## 配置文档 [#配置文档]

`mcp.json` 位于插件根目录，其顶层字段只能是 `$schema` 和 `mcpServers`：

```json title="mcp.json"
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "validator": {
      "type": "stdio",
      "command": "./bin/validator",
      "args": ["--data", "${PLUGIN_DATA}/validator"],
      "env": {
        "CONFIG": "${PLUGIN_ROOT}/config.json"
      },
      "cwd": "${PLUGIN_ROOT}"
    },
    "deployment-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp",
      "headers": {
        "X-Tenant": "public-tenant"
      }
    }
  }
}
```

## 传输类型 [#传输类型]

| 类型                | 必填字段             | 说明                               |
| ----------------- | ---------------- | -------------------------------- |
| `stdio`           | `type`、`command` | 可选 `args`、`env` 和 `cwd`。         |
| `streamable-http` | `type`、`url`     | 当前的远程 MCP 传输；可带可选的字面量 `headers`。 |
| `sse`             | `type`、`url`     | 已弃用的 HTTP+SSE 传输；客户端可选择是否支持。     |

支持 MCP 的合规客户端至少支持 `stdio` 和 `streamable-http` 中的一种，并且建议两者都支持。`sse` 支持是可选的。客户端首次尝试连接时使用声明的传输方式。如果尝试失败，Agent Plugins 不定义回退行为。

## stdio 命令和路径 [#stdio-命令和路径]

`command` 是单个可执行文件标记，不是 shell 命令。它可以是由平台搜索规则解析的纯可执行文件名，也可以是以 `./` 开头的插件相对路径。占位符展开不适用于 `command`。

省略 `cwd` 时，其默认值为插件根目录。显式 `cwd` 必须是插件相对路径、以 `${PLUGIN_ROOT}` 为根的路径，或以 `${PLUGIN_DATA}` 为根的路径，并且必须留在相应目录内。

## 插件变量 [#插件变量]

客户端向 stdio 子进程提供两个环境变量：

* `PLUGIN_ROOT`：经过文件系统解析的插件根目录绝对路径。
* `PLUGIN_DATA`：跨插件更新保留的专用可写数据目录。

客户端在 `args`、`env` 值和 `cwd` 中展开这两个占位符。展开以文本方式进行，只执行一次，且不递归。环境变量键、`command`、远程 URL 和 HTTP 标头不进行展开。插件不能覆盖这些保留环境变量。

## 远程连接 [#远程连接]

远程 URL 必须是绝对 HTTP 或 HTTPS URL，不得包含用户信息或片段。非环回端点使用 HTTPS。配置的标头是字面量且在包中可见，不得包含凭据或密钥。

Agent Plugins 1.0.0 没有定义可移植的 OAuth 或凭据引用字段。身份验证仍由客户端管理。

## 失败隔离 [#失败隔离]

无效的顶层 `mcp.json` 会禁用该插件的 MCP。单个服务器无效或不可用时，只禁用对应条目。其他服务器、技能和客户端扩展继续加载。

下载 [`mcp.schema.json`](/schemas/1.0.0/mcp.schema.json)。


---

Source: [content/docs/plugin-authors/mcp-servers.mdx](https://github.com/agentplugins/agent-plugins-site/blob/237bbf575f5843214923419f9d0933852662f4f3/content/docs/plugin-authors/mcp-servers.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)