MCP指南

# MCP指南

OneSay MCP服务器让AI客户端通过Model Context Protocol读取你在OneSay中的项目、设备、房间、任务、日志和用量，并请求少量有限的更改。它是公开Control API之上的薄层：每个工具都调用一个公开API接口或操作，你的账号能做什么由Control API决定。该服务器已在Staging上提供，详见[可用范围](#availability)。

MCP从不传输音频。语音走SDK：通过OneSay Realtime WebSocket使用语音任务，或使用实时语音（RTC）。

## 连接

- **端点：**`https://<mcp host>/mcp`，每个环境一个。Staging上为`https://mcp.staging.onesay.com/mcp`。
- **传输：**无状态的Streamable HTTP。服务器在请求之间不保留会话。
- **协议：**仅支持MCP `2026-07-28`。每个请求都要发送`Mcp-Protocol-Version: 2026-07-28`；服务器会拒绝其他版本，返回`mcp_protocol_version_unsupported`并注明受支持的版本。
- **请求头：**`Mcp-Method`必须与请求体中的方法一致；对于`tools/call`、`prompts/get`和`resources/read`，`Mcp-Name`必须与工具名、提示词名或资源URI一致。不一致时，服务器在读取任何Token之前就返回HTTP 400和JSON-RPC错误`-32020`。

## 登录

服务器是OAuth 2.1受保护资源。它的受保护资源元数据（Protected Resource Metadata）发布在`/.well-known/oauth-protected-resource`（以及`/.well-known/oauth-protected-resource/mcp`），其中指明该环境的授权服务器。

- 公开发现**无需Token**：包括R0工具、快速入门资源、提示词，以及工具、资源和提示词列表。
- **账号数据需要Token。**R1或R2工具，以及快速入门以外的资源，都需要受众（audience）为本MCP资源的Bearer访问Token。没有Token时，服务器返回HTTP 401，并附带指向上述元数据的`WWW-Authenticate`质询。响应体是带有你的请求id的JSON-RPC错误，其data为`oauth_resource_invalid`错误结构。
- **你的Token不会传到Control API。**每次调用Control API时，服务器都会用它换取（OAuth 2.0 Token Exchange，RFC 8693）一个短期Token，其主体（subject）是你，执行方（actor）是MCP服务。你的Token过期后不再换取，任何Token都不会写入日志或返回。

## 工具

每个工具都有风险等级。只读工具会向客户端标记为只读；`rooms.close`和`tasks.cancel`标记为破坏性操作。

| 风险 | 工具 | 所需条件 |
|---|---|---|
| R0 | `onesay.capabilities.list`、`onesay.capabilities.get`、`onesay.quickstarts.get` | 无：公开元数据 |
| R1 | `onesay.projects.list`、`onesay.projects.get`、`onesay.applications.list`、`onesay.devices.list`、`onesay.devices.get`、`onesay.devices.diagnose`、`onesay.rooms.get`、`onesay.tasks.get`、`onesay.logs.search`、`onesay.logs.timeline`、`onesay.usage.summary` | Token，以及对应API接口要求的授权 |
| R2 | `onesay.rooms.create`、`onesay.rooms.close`、`onesay.tasks.cancel` | Token、授权和用户同意 |

R2工具只有在用户于OneSay中同意之后，才会执行对应的操作。没有用户同意时，调用返回`mcp_confirmation_required`，不做任何更改。在Staging上，R2工具目前处于关闭状态：调用会返回`mcp_tool_not_exposed`，不做任何更改。

## 资源

| URI模板 | 读取内容 |
|---|---|
| `onesay://projects/{project_id}` | 项目，同`onesay.projects.get` |
| `onesay://devices/{device_id}` | 设备的状态，同`onesay.devices.get` |
| `onesay://tasks/{task_id}` | 任务状态，同`onesay.tasks.get` |
| `onesay://docs/quickstarts/{name}` | 快速入门页面（`javascript`或`esp32`）；公开 |

服务器只列出模板。每个读取结果的`ttlMs`都是0，因此客户端会把它视为立即过时。

## 提示词

- `build_voice_app`按照[JavaScript快速入门](JAVASCRIPT_QUICKSTART.md)进行。
- `diagnose_device`按照[设备诊断](DEVICE_DIAGNOSTICS.md)指南进行。

## 错误

工具错误使用OneSay错误结构，与Control API的错误相同：

| 错误码 | 含义 |
|---|---|
| `oauth_resource_invalid` | Token缺失、无效、属于其他资源，或在Token交换时被拒绝。 |
| `capability_authority_unavailable` | OneSay暂时无法检查你的访问权限。请重试。 |
| `mcp_confirmation_required` | R2调用尚未获得用户同意。 |
| `consent_required` | Control API要求的用户同意，该账号尚未给出。 |
| `mcp_tool_input_invalid` | 缺少参数，或参数与工具的schema不符。 |
| `mcp_tool_not_exposed` | 此服务器未启用该工具。 |
| `mcp_tool_output_invalid` | Control API返回的内容不能作为该工具的结果返回。 |

Control API自身的错误（例如缺少授权或资源不存在）会连同原有错误码直接透传。[官方参考](../reference/generated/catalog.md)列出了所有错误码。

## 可用范围

- 服务器运行在Staging上，地址为`https://mcp.staging.onesay.com/mcp`。生产环境尚不可用。
- 在Staging上，R2工具处于关闭状态，调用会返回`mcp_tool_not_exposed`。
- 工具、提示词和资源在每个版本中固定不变，因此服务器不会发送列表变更通知。