# MCP クライアントを接続する

[MCP エンドポイント](/ja/products/ai-studio/agent-channels/mcp-endpoints)は、共有作業フォルダを1つ、リモートの MCP サーバーとして公開します。接続したクライアントが使えるツールは6つです。フォルダで何ができるかを調べるツールが2つ、作業を開始・継続するツールが3つ、結果を受け取るツールが1つです。作業はクライアントではなく Treasure AI Studio で行われます。クライアントがツールを呼ぶと、Studio がそのフォルダで実行者の権限とコネクションを使ってチャットを開始し、エージェントの回答がツールの結果として返ります。

このページでは、クライアントの設定、各ツールの役割、返ってくる結果の読み方を扱います。クライアントを設定する人と、エンドポイントに対して直接エージェントを実装する人に向けた内容です。エンドポイントの作成と、URL・トークンの取得は [MCP エンドポイントの作成と管理](/ja/products/ai-studio/agent-channels/mcp-endpoints)を参照してください。

## ツールの呼び出しが Studio の作業になるまで

```mermaid
flowchart LR
    A["MCP client<br/>holds the token"] -->|"POST to the endpoint URL<br/>Authorization: Bearer"| B["Agent Gateway"]
    B -->|"Check the token<br/>on every request"| C["Treasure AI Studio"]
    C -->|"Start or continue a chat<br/>in the shared work folder"| D["Agent<br/>runs as the executor"]
    D -->|"Answer"| B
    B -->|"Tool result"| A
```

1. **クライアントがツールを呼び出します。** エンドポイントの URL に、`Authorization` ヘッダーでトークンを付けて送ります。
2. **Treasure AI Studio がリクエストごとにトークンを確認します。** トークンがこのエンドポイントのもので期限切れ・失効していないこと、エンドポイントが有効で実行者がいること、実行者がまだフォルダにアクセスできることを確かめます。
3. **作業を開始するツールは、エンドポイントのフォルダでチャットを開きます。** チャットは実行者として動き、フォルダを読み取り専用で参照し、書き込めるのはチャットとともに破棄される一時作業領域だけです。
4. **ゲートウェイが回答を待ち、ツールの結果として返します。** 待機時間内にエージェントの作業が終わらなかった場合は、その旨と、後で結果を取りに来るためのチャット ID が返ります。チャットはそのまま動き続けます。


資格情報は1つだけです。エンドポイントの Gateway Token を毎回のリクエストのヘッダーに付け、チャットごとのトークンの発行や交換はありません。発行・ローテーション・失効は [Gateway Token と Chat Access Token](/ja/products/ai-studio/agent-channels/tokens)で扱います。

## クライアントを設定する

エンドポイントは **Streamable HTTP** で MCP を話します。クライアントには、毎回のリクエストに固定のヘッダーを付けられるものが必要です。エンドポイントの完了画面に表示された値を、次のように設定してください。

| 設定  | 値  |
|  --- | --- |
| **サーバー URL** | エンドポイントの **接続 URL**。`https://<アカウントの Agent Gateway>/v1/mcp/<エンドポイント ID>` |
| **トランスポート** | Streamable HTTP |
| **ヘッダー** | `Authorization: Bearer tasgwt_<シークレット>` |


認証はこの固定ヘッダーだけで行います。OAuth には対応していないため、ブラウザでのサインインを前提とするクライアントでは接続できません。ヘッダーは固定値としてクライアントの設定に入力するか、トークンをシークレット管理ツールに置いてください。Web ページのコードには埋め込まないでください。

クライアントを設定する前に値を確かめたい場合は、シェルから [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) でツールの一覧を取得できます。

```bash
npx @modelcontextprotocol/inspector --cli "$MCP_SERVER_URL" \
  --transport http \
  --header "Authorization: Bearer $MCP_TOKEN" \
  --method tools/list
```

先に `MCP_SERVER_URL` にエンドポイントの **接続 URL** を、`MCP_TOKEN` に `tasgwt_` で始まるトークンを設定してください。正しく動いているエンドポイントは、後述の6つのツールを返します。`401` はトークンが拒否されたこと、`403` はエンドポイントが無効か動作できない状態、またはリクエストに `Origin` ヘッダーが付いていたことを示します。[トラブルシューティング](#%E3%83%88%E3%83%A9%E3%83%96%E3%83%AB%E3%82%B7%E3%83%A5%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0)を参照してください。

## ツール

| ツール  | 役割  | 引数  |
|  --- | --- | --- |
| `list_work_folders` | 接続で利用できる作業フォルダを一覧します。1つのエンドポイントが公開するフォルダは1つなので、結果は常に1件で、`id` と `name` を返します | なし |
| `list_actions` | フォルダのアクションを、それぞれの `name` と `description` とともに名前順で一覧します | `work_folder_id` |
| `run_action` | アクションを保存済みの指示で実行する新しいチャットを開始し、結果を待ちます。呼び出すたびに別の実行になります | `work_folder_id`、`action_name` |
| `start_chat` | `message` に書いたタスクで新しいチャットを開始し、結果を待ちます。合うアクションがないときに使います | `work_folder_id`、`message` |
| `continue_chat` | 既存のチャットに新しい指示を送り、追加の作業や修正を依頼して、返答を待ちます | `chat_id`、`message` |
| `get_chat_result` | チャットの最新の指示（`continue_chat` で送ったものを含む）の結果を、何も送らずに読み取ります。チャットが実行中なら結果を待ちます | `chat_id` |


6つのツールはすべてのエンドポイントで使え、一部だけを隠すことはできません。引数は実行前に各ツールが公開しているスキーマで検証されます。未知の引数は無視されずに拒否され、1回の呼び出しの問題はまとめて1つのエラーとして返ります。

### 一覧に出るアクション

`list_actions` は、エンドポイントの共有作業フォルダに定義されている[アクション](/ja/products/ai-studio/skills/actions)を返します。返る `name` を `run_action` に渡してください。一覧はツールを呼んだ時点で読み込まれるため、フォルダに追加したアクションはすぐにクライアントから使えます。

### アクションの実行とチャットの開始

`run_action` に渡せるのはアクションの名前だけで、引数や追加の指示は受け付けません。アクションを保存済みの内容どおりに実行するので結果が予測しやすく、ツールの説明もまずこちらを使うようクライアントに促しています。

`start_chat` は、代わりにタスクを自然文で受け取ります。Studio 側のエージェントにはクライアントでの会話が見えないため、`message` にはタスクに必要なことをすべて書いてください。前提となる文脈、使うデータ、結果に期待する形です。

既存のチャットに指示を送るには `continue_chat`、作業中の回答を待つには `get_chat_result` を使います。同じタスクで開始系のツールをもう一度呼ぶと、別の実行がもう1つ始まります。

## 結果を読む

どのツールも、テキストブロック1つに JSON オブジェクトを1つ入れて返します。`list_work_folders` と `list_actions` はデータをそのまま返します。チャットを扱う4つのツールは、何が起きたかを `status` で示すオブジェクトを返します。

| `status`  | 意味  | 次にすること  |
|  --- | --- | --- |
| `completed` | ターンが完了しました。`result` にエージェントの回答がテキストで入っています | `result` を読む |
| `running` | ゲートウェイの待機時間が終わった時点で、エージェントはまだ作業中でした。チャットは止まっていません | `chat_id` を指定して `get_chat_result` を呼ぶ。別の実行を始めたり、指示を送り直したりしない |
| `question` | エージェントが回答の代わりに質問をしました。`question` に質問が入っています。ゲートウェイが代わりに辞退し、それが確認できたかは `declined` で分かります。`true` なら、エージェントは回答なしで作業を続けます | `get_chat_result` で結果を読む。作業の方向を変えたい場合は `continue_chat` を送る |
| `failed` | ターンが失敗で終わりました。`error` は決まった文言のいずれかで、具体的な原因はプラットフォームの外には出ません | 再試行するかを判断する。この結果から読み取れることはこれ以上ない |
| `unknown` | 結果を読み取れませんでした。チャットはまだ動いている可能性があります | `chat_id` を指定して `get_chat_result` を呼ぶ。元の指示を繰り返さない |


待機があるのは、MCP クライアントがツール呼び出しに時間制限を設けていて、アクションがそれより長くかかることがあるためです。ゲートウェイは最大 200 秒待ち、クライアント側でタイムアウトさせる代わりに、チャット ID とともに `running` を返します。ステータスが変わるまで `get_chat_result` を繰り返し呼ぶクライアントであれば、最終的なステータスまでたどり着けます。

返るのはエージェントのテキストだけです。エージェントの推論、呼び出したツールとその出力は含まれず、書き出したファイルも作業領域とともに破棄されるため返りません。クライアントが必要とするものは回答の本文に含まれている必要があります。ファイルを生成するアクションでは、何を生成したかを回答に書かせてください。

### 続きの指示は同じエンドポイントで

`continue_chat` と `get_chat_result` が扱えるのは、同じエンドポイントから開始したチャットだけです。あるトークンで開始したチャットは同じエンドポイントの別のトークンでも続けられるため、トークンをローテーションしても会話は途切れません。別のエンドポイントのチャット ID や、Studio で開始したチャットの ID を渡すと、フォルダが同じでも `not_found` が返ります。

チャット自体は実行者のもので、Studio の実行者のチャット一覧に **MCP** のラベルと、吹き出しが2つ重なったアイコン付きで表示されます。

サイドバーの最近のチャット。タイトルの上に MCP というラベルが付き、吹き出しが2つ重なったアイコンのチャットが表示されている
## 制限値

| 制限  | 値  |
|  --- | --- |
| **チャットの新規作成** | エンドポイントごとに 1 分あたり 30 件。`run_action` と `start_chat` の合計で、エンドポイントのすべてのトークンをまとめて数えます。超えるとツールが `rate_limited` を返します |
| **メッセージの長さ** | `start_chat` と `continue_chat` で 1〜32,768 文字 |
| **ツール呼び出しごとの待機** | 最大 200 秒。その後は `running` を返します |
| **エンドポイントあたりのフォルダ数** | 1つ |
| **1回の HTTP リクエストに含められるもの** | JSON-RPC メッセージ1つ。バッチは拒否されます |


接続はステートレスです。開いたり閉じたりする MCP セッションはないため、受け付ける HTTP メソッドは `POST` だけです。また、呼び出しの途中でクライアントが接続を切っても、開始したチャットは止まりません。

## サポートされないもの

- **エージェントの質問への回答。** 質問は常に自動で辞退され、結果は `status: "question"` として返ります。
- **アクションへの引数。** `run_action` は保存済みの内容どおりに実行します。入力を渡したい場合は、`start_chat` でタスクを説明してください。
- **呼び出しごとのフォルダや実行者の指定。** どちらもエンドポイントで固定されています。
- **リソース、プロンプトなどの MCP の機能。** エンドポイントが提供するのはツールだけです。
- **OAuth によるサインイン。** 認証は固定ヘッダーだけです。
- **ブラウザからの呼び出し。** `Origin` ヘッダーの付いたリクエストは拒否されます。


## エラー

失敗には2つの段階があります。資格情報が拒否されると HTTP リクエスト全体が失敗し、個々のツール呼び出しの問題は `isError` 付きのツール結果として返ります。

| 応答  | 意味  |
|  --- | --- |
| HTTP `401`（`invalid_token`） | トークンが不明・失効済み・期限切れ、別のエンドポイントのトークン、またはエンドポイントが削除されています。外からはどれも同じに見えます |
| HTTP `403`（`mcp_disabled`） | エンドポイントが無効か実行者が空席、または実行者がフォルダへのアクセスを失っています |
| HTTP `403`（`browser_refused`） | リクエストに `Origin` ヘッダーが付いていました |
| HTTP `405` | `GET` または `DELETE` で呼び出しました。受け付けるのは `POST` だけです |
| HTTP `406` | リクエストの `Accept` ヘッダーに `application/json` と `text/event-stream` の両方が含まれていませんでした |
| JSON-RPC エラー *「The service is temporarily unavailable.」* | この呼び出しで Treasure AI Studio に到達できませんでした。何も開始されていないので、再試行してください |
| ツールのエラー `invalid_request` | 引数がツールのスキーマに合いませんでした。メッセージにすべての問題が列挙されます |
| ツールのエラー `not_found` | フォルダ ID、アクション名、チャット ID が存在しないか、このエンドポイントからは扱えません |
| ツールのエラー `rate_limited` | このエンドポイントで直近 1 分間に開始されたチャットが多すぎます。時間をおいて再試行してください |
| ツールのエラー `dispatch_failed` | アクション、チャット、続きの指示を開始できませんでした。再試行してください |
| ツールのエラー `folder_unavailable` | その時点でフォルダの内容を読み込めませんでした。再試行してください |


## トラブルシューティング

| 症状  | 原因と対処  |
|  --- | --- |
| すべてのリクエストが `401` で拒否される | ヘッダーが `Authorization: Bearer <トークン>` の形でトークン全体を含んでいるか、URL とトークンが同じエンドポイントのものかを確認してください。どちらも問題なければ、トークンが期限切れか失効しています。エンドポイントの詳細ページで新しく発行してください |
| すべてのリクエストが `403` で拒否される | **設定 → エージェントチャネル**でエンドポイントを開き、ステータスを確認してください。**無効** または **停止中（実行者が必要）** なら、再び有効にする必要があります。**有効** の場合は、実行者がフォルダへのアクセスを失っている可能性があります |
| `list_actions` が何も返さない、または期待したアクションが出てこない | そのアクションがエンドポイントの共有作業フォルダに定義されていません。Studio でフォルダを開き、**アクションとスキル** セクションにアクションとして表示されているか確認してください（[アクション](/ja/products/ai-studio/skills/actions)を参照） |
| ツールが `running` を返し続ける | チャットはまだ作業中です。同じ `chat_id` で `get_chat_result` を呼び続けてください。進み具合は、実行者が Studio でチャットを開くと確認できます |
| 自分で開始したチャットに `continue_chat` を送ると `not_found` が返る | そのチャットは別のエンドポイントから開始されたか、削除されています。続きの指示は、チャットを開始したエンドポイントでしか送れません |


## 次のステップ

- [MCP エンドポイントの作成と管理](/ja/products/ai-studio/agent-channels/mcp-endpoints) — エンドポイント、実行者、トークン
- [アクション](/ja/products/ai-studio/skills/actions) — クライアントが実行するアクションを書く
- [エージェントチャネルのチャットが到達できる範囲](/ja/products/ai-studio/agent-channels/channel-chats) — 各チャットの作業領域、資格情報、制限
- [Gateway Token と Chat Access Token](/ja/products/ai-studio/agent-channels/tokens) — エンドポイントのトークンのローテーションと失効