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`。環境ごとに1つです。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と一致する必要があります。一致しない場合は、トークンを読む前にHTTP 400とJSON-RPCエラー`-32020`で応答します。

## サインイン

サーバーはOAuth 2.1の保護リソースです。保護リソースメタデータは`/.well-known/oauth-protected-resource`（および`/.well-known/oauth-protected-resource/mcp`）で提供され、その環境の認可サーバーを示します。

- **トークンなし**で公開の検出ができます。R0ツール、クイックスタートのリソース、プロンプト、ツール・リソース・プロンプトの一覧です。
- **アカウントのデータにはトークンが必要です。**R1またはR2のツール、あるいはクイックスタート以外のリソースには、このMCPリソースを対象とするBearerアクセストークンが必要です。トークンがない場合、サーバーはメタデータを指す`WWW-Authenticate`チャレンジ付きのHTTP 401で応答します。本文はリクエストIDを含むJSON-RPCエラーで、dataには`oauth_resource_invalid`のエラーエンベロープが入ります。
- **自分のトークンがControl APIに届くことはありません。**Control APIを呼び出すたびに、サーバーはそのトークンを交換し（OAuth 2.0トークン交換、RFC 8693）、ユーザー本人を主体、MCPサービスをアクターとする短期トークンを取得します。元のトークンの期限が切れた後は交換を行いません。トークンを記録したり返したりすることもありません。

## ツール

各ツールにはリスク区分があります。クライアントに対して、読み取り専用のツールには読み取り専用のマークが、`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` | トークンと、対応するAPIオペレーションが求めるグラント |
| R2 | `onesay.rooms.create`、`onesay.rooms.close`、`onesay.tasks.cancel` | トークン、グラント、人間のユーザーの同意 |

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)ガイドに従います。

## エラー

ツールのエラーは、Control APIと同じOneSayエラーエンベロープを持ちます。

| コード | 意味 |
|---|---|
| `oauth_resource_invalid` | トークンがない、無効、別のリソース向け、またはトークン交換で拒否された。 |
| `capability_authority_unavailable` | OneSayが現在アクセス権を確認できない。再試行してください。 |
| `mcp_confirmation_required` | R2の呼び出しに、まだ人間の同意がない。 |
| `consent_required` | Control APIが、アカウントがまだ与えていない同意を必要としている。 |
| `mcp_tool_input_invalid` | 引数が欠けているか、ツールのスキーマと一致しない。 |
| `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`で応答します。
- ツール、プロンプト、リソースはリリースごとに固定されるため、サーバーは一覧の変更通知を送りません。