AI 云盘 MCP 服务器

在 Claude Desktop 等外部 MCP 客户端中搜索并读取 Keural 云盘文档。

Keural 云盘以 MCP 服务器的形式提供。外部 MCP 客户端连接后，持有密钥的用户可以搜索自己有权查看的云盘文档，并按页读取。插件是将外部系统连接到 Keural，而本服务器是将 Keural 文档连接到外部 AI。

认证使用组织 API 密钥。组织 API 密钥由 Keural 运营方签发，请向接入负责人申请。密钥以获得密钥的单个用户的权限运行，并需要 drive:read 权限。回收密钥后，已有连接将在 1 分钟内被阻止。

连接信息

项目	值
传输方式	MCP Streamable HTTP
地址	`https://<各环境的智能体服务器域名>/core/v1/mcp-drive`
认证	`Authorization: Bearer <组织 API 密钥>`（所有请求）

请求方式

方法	用途
`POST`	一个 JSON-RPC 请求。响应始终为一个 `application/json`。通知（`notifications/*`）不带正文，返回 `202`。
`GET`	服务器事件流。需要 `Accept: text/event-stream` 和 `Mcp-Session-Id`。每 15 秒发送一次 keepalive，并可通过 `Last-Event-ID` 接续接收。
`DELETE`	结束会话。需要 `Mcp-Session-Id`，并返回 `204`。

initialize 成功后，会通过响应标头 Mcp-Session-Id 返回会话 ID。会话为可选项，不使用会话、仅发送 POST 也可以。会话在最后一次请求后保留 1 小时，并绑定到创建它的密钥。
MCP-Protocol-Version 标头为可选项，若发送，其值必须为 2025-06-18。
服务器信息为 keural-ai-drive，提供的功能仅有 tools。

HTTP 错误

HTTP 阶段的错误不是 JSON-RPC 格式，因此请通过状态码确认。

状态	原因
`401`	密钥缺失或错误，或密钥已被回收、已过期
`403`	密钥没有 `drive:read` 权限
`400`	不支持的 `MCP-Protocol-Version`，JSON 解析失败（`-32700`），`GET`·`DELETE` 缺少会话 ID
`404`	未知或已过期的会话 ID
`405`	`GET` 缺少 `Accept: text/event-stream`

JSON-RPC 阶段的错误会以 200 配合 error 返回。未知的方法或工具返回 -32601，请求格式错误返回 -32600。

工具

工具	输入	说明
`list_files`	无	可查看的文档列表（名称、id、上传日期、修改日期，若由他人上传则为上传者）。云盘文档与对话附件一同返回，并以 `origin` 区分。最多 500 个，超出时会附加 `truncated: true`
`search_drive`	`query`	按语义搜索文档内容，返回相关段落和引用信息
`read_document_page`	`file_id`、`page`	读取文档特定页的全文。`file_id` 从上述两个工具的结果中获取，`page` 从 1 开始计数

工具结果以 JSON 字符串的形式放在 content[0].text 中。

工具	`text` 中的 JSON
`list_files`	`{"files":[{"name","id","created_date","modified_date","owner_name","origin"}], "truncated": false}`。日期格式为 `yyyy-MM-dd HH:mm`
`search_drive`	`{"sources":[{"id","name","url","contents":[…]}]}`
`read_document_page`	`{"file_id","page","rows":[…]}`

工具执行失败时，返回 isError: true 和 {"error": "…"}（不是 JSON-RPC 错误）。无权查看或不存在的文档，统一返回 file not found or not accessible。

客户端配置示例

在支持远程 MCP 服务器的客户端中登记地址和标头。配置格式因客户端而异，请按所用客户端的远程 MCP 服务器添加方法进行设置。

{
  "mcpServers": {
    "keural-drive": {
      "type": "http",
      "url": "https://<各环境的智能体服务器域名>/core/v1/mcp-drive",
      "headers": { "Authorization": "Bearer <组织 API 密钥>" }
    }
  }
}

支持的 MCP 协议版本为 2025-06-18。

AI 云盘 MCP 服务器

连接信息复制锚点链接

请求方式复制锚点链接

HTTP 错误复制锚点链接

工具复制锚点链接

客户端配置示例复制锚点链接

本页目录

连接信息

请求方式

HTTP 错误

工具

客户端配置示例