# MCP API リファレンス

AGENTIC STAR SaaS版が提供する **MCP（Model Context Protocol）** エンドポイントの詳細仕様です。MCP は MCP 対応 AI エージェント（Claude 等）から AGENTIC STAR に接続し、ツール呼び出しでタスク実行・ファイル取得・プロジェクトの操作を行うためのインターフェースです。

> **SaaS 版の仕様**
>
> 本リファレンスは SaaS 版の MCP の仕様です。マーケットプレイス版の MCP は [MCP API リファレンス（マーケットプレイス版）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/mcp-ref.md) を参照してください。
>
> クライアントの設定とつなぎ方は [AI クライアント接続ガイド（MCP）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/ai-client-guide.md)、接続方式の概要は [接続方式ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/connection-guide.md#mcpmodel-context-protocol) を参照してください。

## ベース URL

すべてのリクエストは以下のベース URL に対して送信します。

SaaS

`https://api.fd.agenticstar.tm.softbank.jp`

## エンドポイント

SaaS

| メソッド | エンドポイント       | 説明                                                   |
| ---- | ------------- | ---------------------------------------------------- |
| POST | `/api/v1/mcp` | MCP JSON-RPC エンドポイント（Streamable HTTP, Stateless モード） |

**プロトコル:** JSON-RPC 2.0 over Streamable HTTP

**モード:** Stateless（セッションを持ちません）

## 認証

すべてのリクエストには `Authorization: Bearer <access_token>` ヘッダーが必須です。トークンには次のどちらかのスコープが必要です。どちらも無いトークンは `403 Forbidden` になります。

| スコープ          | 用途                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `mcp:all`     | MCP のすべてのツールを使えます。ほかのスコープは要りません                                                                                           |
| `mcp:connect` | MCP に接続できます。使えるツール（project の組は操作）は、あわせて持つスコープで決まります（[提供ツール](#%E6%8F%90%E4%BE%9B%E3%83%84%E3%83%BC%E3%83%AB) の各表の「必要スコープ」） |

> **新しく作るアプリには mcp:connect を勧めます**
>
> 新しく作るアプリには、`mcp:connect` と、使うツールに要るスコープだけを付けてください。`mcp:all` は MCP のすべてのツールを使えるスコープです。

> **mcp:all を持つアプリで使えるツールが増えました**
>
> `mcp:all` を持つアプリは、[ツールの組](#%E3%83%84%E3%83%BC%E3%83%AB%E3%81%AE%E7%B5%84toolsets) で `project` を指定すると project の組のツールを使えます。会話を読む `list_conversation_messages` は、指定しなくても使えます。

システム連携（Client Credentials フロー）では、`mcp:connect` と `project:read`・`project:run` を選べます。システム連携で使えるのは、project の組の 5 つの操作（`project_read` の `list`・`run_read` の `get`・`project_run` の `start_run`・`fire_trigger`・`cancel_run`）と、チャットの組の `list_personas` です。対象はシステム連携のプロジェクト制限の範囲だけです。

システム連携は、Console で発行した API キーを `Authorization: Bearer` で送ってもつなげます（[Console ガイド — API キー](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#api-key)）。

トークン取得方法は [認証 API リファレンス（SaaS）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/auth-saas-ref.md) を参照してください。

## ツールの組（`?toolsets=`）

エンドポイントの URL のクエリ `toolsets` で、使うツールの組を選びます。

| 指定                       | 使えるツール           |
| ------------------------ | ---------------- |
| 指定なし・`?toolsets=chat`    | チャットの組（6 本）      |
| `?toolsets=project`      | project の組（27 本） |
| `?toolsets=chat,project` | 両方（33 本）         |

例: `https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project`

- 知らない名前は無視し、`initialize`（または `server/discover`）の応答の `instructions` の先頭で知らせます。知っている名前が 1 つも無いときは、チャットの組だけになります
- `tools/list` で返るツールは、組の指定だけで決まります。トークンのスコープでは変わりません。スコープが足りないツールを呼ぶと、ツールのエラー（`isError: true`）で、要るスコープと次にやることを返します

## 対応プロトコルバージョン

本エンドポイントが受理する MCP プロトコルリビジョンは次のとおりです。新旧どちらの形のクライアントも接続できます。

| リビジョン        | 接続の形                                                 |
| ------------ | ---------------------------------------------------- |
| `2026-07-28` | リクエストごとにプロトコルバージョンとクライアント機能を送る形（`initialize` を使いません） |
| `2025-11-25` | `initialize` でバージョンを決める形                             |
| `2025-06-18` | `initialize` でバージョンを決める形                             |
| `2025-03-26` | `initialize` でバージョンを決める形                             |
| `2024-11-05` | `initialize` でバージョンを決める形                             |
| `2024-10-07` | `initialize` でバージョンを決める形                             |

## 提供ツール

`tools/call` で呼び出せるツールは、[ツールの組](#%E3%83%84%E3%83%BC%E3%83%AB%E3%81%AE%E7%B5%84toolsets) ごとに次のとおりです。「必要スコープ」は、`mcp:all` のトークンでは問われません。`mcp:connect` のトークンでは、そのスコープも要ります。

### チャットの組

| ツール                          | 説明                     | 必要スコープ（`mcp:connect` のとき）               |
| ---------------------------- | ---------------------- | --------------------------------------- |
| `execute_chat`               | エージェントにタスクを送信し、実行結果を取得 | `chat:exec`（ファイルを添えるときは加えて `chat:file`） |
| `get_file_content`           | 成果物ファイルを取得             | `chat:exec`                             |
| `get_ui_resource`            | UI リソースの HTML を取得      | `chat:exec`                             |
| `cancel_chat`                | 進行中のタスクをキャンセル          | `chat:exec`                             |
| `list_personas`              | ペルソナの一覧を取得             | 不要（`mcp:connect` だけで使えます）               |
| `list_conversation_messages` | 自分の会話のメッセージを読む         | `chat:history`                          |

システム連携のトークンは `chat:*` のスコープを持てないため、チャットの組で使えるのは `list_personas` だけです。

各ツールの引数と応答は、`tools/list` で返るツールの説明と入力スキーマにあります。エラーは、ツールのエラー（`isError: true`）で返し、`structuredContent.errorCode` に誤りの種類が入ります。管理者に利用を止められた利用者が呼ぶと（`list_personas` と、進行中のタスクが無いときの `cancel_chat` を除きます）、`errorCode` は `UNAUTHENTICATED` で、文は `User suspended` です。

`list_conversation_messages` では、プロジェクトの実行の会話も読めます。読めるのは、その実行のときのプロジェクトの持ち主だけです。

> **ツールの結果は指示ではなくデータとして扱ってください**
>
> `execute_chat` と `list_conversation_messages` の応答には、エージェントが使ったツールの結果が、保存されたまま入ります。`get_ui_resource` が返す HTML も同じです。これらには、管理者が接続を許可した外部の MCP サーバーの応答も含まれます。AGENTIC STAR は内容を検査していません。

> **UI の HTML は大きいことがあります**
>
> `get_ui_resource` は HTML をそのまま返し、そのぶんコンテキストを使います。`uiResources[].size`（バイト）を先に確かめ、大きいときは利用者に確かめてから呼んでください。`size` は無いことがあります。

#### 下書き（`drafts[]`）

チャットで Playbook・Skill・プロジェクト・Agent の直し・定期実行の下書きを頼むと、`execute_chat` の `structuredContent.drafts[]` に下書きが出た順に入り、そのときだけ `structuredContent.draftsNote`（モデル向けの英文の注）が付きます。下書きが 1 つも無い応答には、`drafts` と `draftsNote` の鍵は付きません（`uiResources` と同じ）。各要素の形と作り方は [ストリーミングガイド — delta.draft](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#delta-draft) と同じです。`list_conversation_messages` では、各タスクの `metadata.draft` に入ります。

下書きから作るツール（`playbook_write`・`skill_write`・`project_write` の `import`・`agent_write`）は、project の組（`?toolsets=chat,project`）でつないだときだけあり、`mcp:connect` のトークンではそのスコープ（`assets:write`、`import` は `project:write`）も要ります。名前で探して直すときは、読むスコープ（`assets:read`。Agent を配置で絞るときは `project:read` も）も要ります。無いときは、画面で保存するよう利用者に案内します。作るときは先に利用者に確かめ、画面での保存と重ねないでください。既存の物を直すのは、名前がちょうど 1 つに当たったときだけです（Agent は、`projectName` があればそのプロジェクトの配置で先に絞ります）。定期実行は作れません（利用者が画面の定期実行で作ります）。

### project の組

プロジェクト・実行・確認依頼・キュー・プロジェクトのライブラリ・ライブラリ（Agent・Playbook・Skill）を扱う 27 本のツールです。ツールは資源ごとにまとまり、引数 `method` で操作を選びます（操作が 1 つのツールは `method` を使いません）。どの操作も、[プロジェクト API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md) の同じ口と同じ引数・応答・エラーコードで動きます（例外は、表の下の「引数」と「応答」）。プロジェクトのメンバー・オーナーなどの確かめも、REST と同じです。

| ツール                   | 用途                                                                                                  | `method`                       | 対応する REST                                                                | 必要スコープ（`mcp:connect` のとき）   | システム連携 |
| --------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------ | --------------------------- | ------ |
| `project_read`        | プロジェクトを読む                                                                                           | `list`                         | `GET /v1/projects`                                                       | `project:read`              | ✅      |
|                       |                                                                                                     | `list_shared`                  | `GET /v1/projects/shared`                                                | `project:read`              |        |
|                       |                                                                                                     | `get`                          | `GET /v1/projects/{projectId}`                                           | `project:read`              |        |
|                       |                                                                                                     | `get_control`                  | `GET /v1/projects/{projectId}/control`                                   | `project:read`              |        |
|                       |                                                                                                     | `list_organizations`           | `GET /v1/projects/organizations`                                         | `project:read`              |        |
|                       |                                                                                                     | `list_automation_destinations` | `GET /v1/projects/automation-destinations`                               | `project:read`              |        |
|                       |                                                                                                     | `export_definition`            | `GET /v1/projects/{projectId}/definition`                                | `project:read`              |        |
|                       |                                                                                                     | `get_definition_approval`      | `GET /v1/projects/{projectId}/definition-approval`                       | `project:read`              |        |
| `project_status_read` | キュー・KPI・記録 (証跡) を読む                                                                                 | `list_my_queue`                | `GET /v1/queue`                                                          | `project:read`              |        |
|                       |                                                                                                     | `list_queue`                   | `GET /v1/projects/{projectId}/queue`                                     | `project:read`              |        |
|                       |                                                                                                     | `get_kpi`                      | `GET /v1/projects/{projectId}/kpi`                                       | `project:read`              |        |
|                       |                                                                                                     | `get_kpi_trends`               | `GET /v1/projects/{projectId}/kpi/trends`                                | `project:read`              |        |
|                       |                                                                                                     | `list_audit_events`            | `GET /v1/projects/{projectId}/audit`                                     | `project:read`              |        |
| `project_file_read`   | プロジェクトのライブラリとファイルの中身を読む                                                                             | `list`                         | `GET /v1/projects/{projectId}/library`                                   | `project:read`              |        |
|                       |                                                                                                     | `list_versions`                | `GET /v1/projects/{projectId}/library/{fileId}/versions`                 | `project:read`              |        |
|                       |                                                                                                     | `get_content`                  | `GET /v1/projects/{projectId}/files/content`                             | `project:read`              |        |
| `placement_read`      | エージェントの配置を読む                                                                                        | `list`                         | `GET /v1/projects/{projectId}/placements`                                | `project:read`              |        |
|                       |                                                                                                     | `get`                          | `GET /v1/projects/{projectId}/placements/{placementId}`                  | `project:read`              |        |
|                       |                                                                                                     | `get_memory_candidates`        | `GET /v1/projects/{projectId}/memory-candidates`                         | `project:read`              |        |
| `run_read`            | ワークフローの実行（run）を読む                                                                                   | `list`                         | `GET /v1/projects/{projectId}/runs`                                      | `project:read`              |        |
|                       |                                                                                                     | `get`                          | `GET /v1/projects/{projectId}/runs/{runId}`                              | `project:read`              | ✅      |
|                       |                                                                                                     | `get_config`                   | `GET /v1/projects/{projectId}/runs/{runId}/config`                       | `project:read`              |        |
|                       |                                                                                                     | `get_resume_options`           | `GET /v1/projects/{projectId}/runs/{runId}/resume`                       | `project:read`              |        |
| `execution_read`      | エージェントの実行を読む                                                                                        | `list`                         | `GET /v1/projects/{projectId}/executions`                                | `project:read`              |        |
|                       |                                                                                                     | `get`                          | `GET /v1/projects/{projectId}/executions/{executionId}`                  | `project:read`              |        |
|                       |                                                                                                     | `list_operations`              | `GET /v1/projects/{projectId}/executions/{executionId}/operations`       | `project:read`              |        |
|                       |                                                                                                     | `get_timeline`                 | `GET /v1/projects/{projectId}/executions/{executionId}/timeline`         | `project:read`              |        |
| `workitem_read`       | 確認依頼を読む                                                                                             | `list`                         | `GET /v1/workitems`                                                      | `project:read`              |        |
|                       |                                                                                                     | `get`                          | `GET /v1/workitems/{workItemId}`                                         | `project:read`              |        |
| `connector_read`      | 連携先（MCP サーバー・A2A AIエージェント）を読む                                                                       | `get_mcp`                      | `GET /v1/connectors/mcp/{connectionId}`                                  | `project:read`              |        |
|                       |                                                                                                     | `get_a2a`                      | `GET /v1/connectors/a2a/{connectionId}`                                  | `project:read`              |        |
| `webhook_read`        | プロジェクトの Webhook と配送の結果を読む                                                                           | `list`                         | `GET /v1/projects/{projectId}/webhooks`                                  | `project:read`              |        |
|                       |                                                                                                     | `list_deliveries`              | `GET /v1/projects/{projectId}/webhooks/{webhookId}/deliveries`           | `project:read`              |        |
| `agent_read`          | ライブラリの Agent を読む                                                                                    | `list`                         | `GET /v1/agents`                                                         | `assets:read`               |        |
|                       |                                                                                                     | `list_shared`                  | `GET /v1/agents/shared`                                                  | `assets:read`               |        |
|                       |                                                                                                     | `get`                          | `GET /v1/agents/{agentId}`                                               | `assets:read`               |        |
| `playbook_read`       | ライブラリの Playbook を読む                                                                                 | `list`                         | `GET /v1/playbooks`                                                      | `assets:read` か `chat:exec` |        |
|                       |                                                                                                     | `list_shared`                  | `GET /v1/playbooks/shared`                                               | `assets:read` か `chat:exec` |        |
|                       |                                                                                                     | `get`                          | `GET /v1/playbooks/{playbookId}`                                         | `assets:read`               |        |
| `skill_read`          | ライブラリの Skill を読む                                                                                    | `list`                         | `GET /v1/skills`                                                         | `assets:read` か `chat:exec` |        |
|                       |                                                                                                     | `list_shared`                  | `GET /v1/skills/shared`                                                  | `assets:read` か `chat:exec` |        |
|                       |                                                                                                     | `get`                          | `GET /v1/skills/{skillId}`                                               | `assets:read`               |        |
|                       |                                                                                                     | `list_versions`                | `GET /v1/skills/{skillId}/versions`                                      | `assets:read`               |        |
|                       |                                                                                                     | `list_files`                   | `GET /v1/skills/{skillId}/files`                                         | `assets:read`               |        |
|                       |                                                                                                     | `get_file`                     | `GET /v1/skills/{skillId}/files/content`                                 | `assets:read`               |        |
| `project_write`       | プロジェクトを作る・変える                                                                                       | `create`                       | `POST /v1/projects`                                                      | `project:write`             |        |
|                       |                                                                                                     | `update`                       | `PATCH /v1/projects/{projectId}`                                         | `project:write`             |        |
|                       |                                                                                                     | `import`                       | `POST /v1/projects/import`                                               | `project:write`             |        |
|                       |                                                                                                     | `dismiss_relink`               | `DELETE /v1/projects/{projectId}/relink`                                 | `project:write`             |        |
|                       |                                                                                                     | `withdraw_definition`          | `DELETE /v1/projects/{projectId}/definition-approval`                    | `project:write`             |        |
| `project_file_write`  | プロジェクトのライブラリのファイルを足す・変える・消す                                                                         | `upload`                       | `POST /v1/projects/{projectId}/library`                                  | `project:write`             |        |
|                       |                                                                                                     | `copy`                         | `POST /v1/projects/{projectId}/library/copy`                             | `project:write`             |        |
|                       |                                                                                                     | `update_content`               | `PUT /v1/projects/{projectId}/library/{fileId}/content`                  | `project:write`             |        |
|                       |                                                                                                     | `restore`                      | `POST /v1/projects/{projectId}/library/{fileId}/restore`                 | `project:write`             |        |
|                       |                                                                                                     | `import_latest`                | `POST /v1/projects/{projectId}/library/{fileId}/import-latest`           | `project:write`             |        |
|                       |                                                                                                     | `delete`                       | `DELETE /v1/projects/{projectId}/library/{fileId}`                       | `project:write`             |        |
| `step_write`          | ステップを足す・変える・並べ替える・消す                                                                                | `create`                       | `POST /v1/projects/{projectId}/steps`                                    | `project:write`             |        |
|                       |                                                                                                     | `update`                       | `PATCH /v1/projects/{projectId}/steps/{stepId}`                          | `project:write`             |        |
|                       |                                                                                                     | `reorder`                      | `PUT /v1/projects/{projectId}/steps/order`                               | `project:write`             |        |
|                       |                                                                                                     | `delete`                       | `DELETE /v1/projects/{projectId}/steps/{stepId}`                         | `project:write`             |        |
| `placement_write`     | エージェントを配置する・配置を変える・工程にファイルを対応づける                                                                    | `create`                       | `POST /v1/projects/{projectId}/placements`                               | `project:write`             |        |
|                       |                                                                                                     | `delete`                       | `DELETE /v1/projects/{projectId}/placements/{placementId}`               | `project:write`             |        |
|                       |                                                                                                     | `update_steps`                 | `PUT /v1/projects/{projectId}/placements/{placementId}/steps`            | `project:write`             |        |
|                       |                                                                                                     | `update_memory`                | `PATCH /v1/projects/{projectId}/placements/{placementId}/memory`         | `project:write`             |        |
|                       |                                                                                                     | `update_instruction`           | `PATCH /v1/projects/{projectId}/placements/{placementId}/instruction`    | `project:write`             |        |
|                       |                                                                                                     | `update_schedule`              | `PATCH /v1/projects/{projectId}/placements/{placementId}/schedule`       | `project:write`             |        |
|                       |                                                                                                     | `update_library_bindings`      | `PUT /v1/projects/{projectId}/placements/{placementId}/library-bindings` | `project:write`             |        |
| `trigger_write`       | トリガーを作る・変える・消す                                                                                      | `create`                       | `POST /v1/projects/{projectId}/triggers`                                 | `project:write`             |        |
|                       |                                                                                                     | `update`                       | `PATCH /v1/projects/{projectId}/triggers/{triggerId}`                    | `project:write`             |        |
|                       |                                                                                                     | `delete`                       | `DELETE /v1/projects/{projectId}/triggers/{triggerId}`                   | `project:write`             |        |
| `webhook_write`       | プロジェクトの Webhook を作る・変える・消す（`secret` は返りません）                                                         | `create`                       | `POST /v1/projects/{projectId}/webhooks`                                 | `project:write`             |        |
|                       |                                                                                                     | `update`                       | `PATCH /v1/projects/{projectId}/webhooks/{webhookId}`                    | `project:write`             |        |
|                       |                                                                                                     | `delete`                       | `DELETE /v1/projects/{projectId}/webhooks/{webhookId}`                   | `project:write`             |        |
| `project_run`         | ワークフローの実行を始める・トリガーを発火する・失敗した巡回の実行をもう一度動かす・ワークフローの実行の確認担当者と締め切りを変える・閉じたワークフローの実行を再開する・ワークフローの実行を中断する | `start_run`                    | `POST /v1/projects/{projectId}/runs`                                     | `project:run`               | ✅      |
|                       |                                                                                                     | `fire_trigger`                 | `POST /v1/projects/{projectId}/triggers/{triggerId}/fire`                | `project:run`               | ✅      |
|                       |                                                                                                     | `rerun_execution`              | `POST /v1/projects/{projectId}/executions/{executionId}/rerun`           | `project:run`               |        |
|                       |                                                                                                     | `reassign_approvers`           | `PUT /v1/projects/{projectId}/runs/{runId}/approvers`                    | `project:write`             |        |
|                       |                                                                                                     | `set_deadline`                 | `PATCH /v1/projects/{projectId}/runs/{runId}`                            | `project:write`             |        |
|                       |                                                                                                     | `resume_run`                   | `POST /v1/projects/{projectId}/runs/{runId}/resume`                      | `project:run`               |        |
|                       |                                                                                                     | `cancel_run`                   | `POST /v1/projects/{projectId}/runs/{runId}/cancel`                      | `project:run`               | ✅      |
| `project_delete`      | プロジェクトを消す                                                                                           | —                              | `DELETE /v1/projects/{projectId}`                                        | `project:delete`            |        |
| `workitem_decide`     | 確認依頼を判断する・期限を延ばす                                                                                    | `decide`（省略可）                  | `POST /v1/workitems/{workItemId}/decision`                               | `project:decide`            |        |
|                       |                                                                                                     | `extend`                       | `PATCH /v1/workitems/{workItemId}`                                       | `project:decide`            |        |
| `agent_write`         | Agent を作る・変える・コピーする                                                                                 | `create`                       | `POST /v1/agents`                                                        | `assets:write`              |        |
|                       |                                                                                                     | `update`                       | `PATCH /v1/agents/{agentId}`                                             | `assets:write`              |        |
|                       |                                                                                                     | `copy`                         | `POST /v1/agents/{agentId}/copy`                                         | `assets:write`              |        |
| `playbook_write`      | Playbook を作る・変える・コピーする                                                                              | `create`                       | `POST /v1/playbooks`                                                     | `assets:write`              |        |
|                       |                                                                                                     | `update`                       | `PATCH /v1/playbooks/{playbookId}`                                       | `assets:write`              |        |
|                       |                                                                                                     | `copy`                         | `POST /v1/playbooks/{playbookId}/copy`                                   | `assets:write`              |        |
| `skill_write`         | Skill を作る・ファイルと設定を変える・コピーする                                                                         | `create`                       | `POST /v1/skills`                                                        | `assets:write`              |        |
|                       |                                                                                                     | `replace_files`                | `PUT /v1/skills/{skillId}/files`                                         | `assets:write`              |        |
|                       |                                                                                                     | `edit_files`                   | `PATCH /v1/skills/{skillId}/files`                                       | `assets:write`              |        |
|                       |                                                                                                     | `update_settings`              | `PATCH /v1/skills/{skillId}`                                             | `assets:write`              |        |
|                       |                                                                                                     | `copy`                         | `POST /v1/skills/{skillId}/copy`                                         | `assets:write`              |        |
| `agent_delete`        | Agent を消す                                                                                           | —                              | `DELETE /v1/agents/{agentId}`                                            | `assets:delete`             |        |
| `playbook_delete`     | Playbook を消す                                                                                        | —                              | `DELETE /v1/playbooks/{playbookId}`                                      | `assets:delete`             |        |
| `skill_delete`        | Skill を消す                                                                                           | —                              | `DELETE /v1/skills/{skillId}`                                            | `assets:delete`             |        |

- **引数**: パスの値（`projectId` など）・クエリ・本文の項目を、それぞれ 1 つずつの引数で渡します（本文を `body` にまとめません）。名前と意味は、`tools/list` で返る各ツールの入力スキーマにあります。例外: `project_file_write` の `upload`・`update_content` は、ファイルを `multipart/form-data` ではなく、引数 `content`（中身）と `encoding`（`utf-8` か `base64`。既定は `utf-8`）で送ります。`upload` は `filename`（ライブラリでの名前）も送ります。`workitem_decide` の `method` は省けます（省くと `decide`）。読むツール 12 本（名前が `_read` で終わるもの）と消すツール 4 本（`_delete` で終わるもの）は、入力スキーマに無い引数を断ります。書くツール 11 本は MCP では断りませんが、使えるのは入力スキーマにある引数だけです。本文を受ける操作では、知らない引数も本文の項目として REST に渡し、REST が判断します。本文を受けない 10 の操作（`step_write` の `delete`、`placement_write` の `delete`、`trigger_write` の `delete`、`webhook_write` の `delete`、`project_run` の `rerun_execution`、`agent_write` と `playbook_write` の `copy`、`project_file_write` の `upload`・`update_content`・`delete`）では使いません `project_read` の `get`・`get_control` と `placement_read` の `list`・`get` は、引数 `definition`（`"pending"`）で、定義の変更の承認待ちを重ねた見え方を読めます。`project_write` の `withdraw_definition` は、引数 `pendingDigest` で取り消す承認待ちを指定します。`step_write` の `create`・`update` は、引数 `automationConfig`（外部の自動化の設定）を受けます。`defaultZone` は `"branch"` も受け、`update` は引数 `branchConfig`（条件分岐の設定）も受けます。
- **次の工程に渡す値と資料**: `step_write` の `create`・`update` は工程の `outputConfig`（次の工程に渡す値と資料の役割。[工程の項目](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#step-fields)）を、`project_write` の `create` は `steps[].outputConfig` を受けます。`run_read`・`execution_read`・`workitem_read` の答えの `handoff`（工程の間で渡った値と資料）の意味は、[実行状況の取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#get-run)・[実行の結果の取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#get-execution)・[確認依頼の取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#get-workitem)の項目の表にあります
- **応答**: 成功したときは、REST と同じ JSON を、構造化した結果（`structuredContent`）と、それを JSON にした文 1 つで返します。例外: `project_file_read` の `get_content` は、REST と同じ JSON ではなく、`get_file_content` と同じ形（文・画像・base64。5 MB を超えたら、MCP と同じトークンで取れる REST の口の URL）で返します 定義の変更に承認が要るテナントでは、書くツール（`project_write`・`step_write`・`placement_write`・`trigger_write`）の結果に、REST と同じく `definitionApproval` が入ります（承認待ちになった変更は、承認されるまで実行に効きません）。
- **エラー**: REST と同じ形（`{"error":{"type","message","code","param","suggested_action"}}`。`param`・`suggested_action` は、あるときだけ）を、ツールのエラー（`isError: true`）で返します。`type`・`code` は REST と同じです。`message`・`param`・`suggested_action` は、MCP の引数とツールの名前で書きます。ただし、本体から返った `message` はそのまま返します。入力スキーマに合わない引数（型の違い・無い名前・`schedule` の形の違いなど）は、REST の形ではなく、文 `Input validation error: …`（項目名つき）のツールのエラーで返します（構造化した結果はありません）。管理者に利用を止められた利用者が呼ぶと、`code` は `account_suspended` です
- **印**: 読むツールは `readOnlyHint: true`、書くツールと消すツールは `destructiveHint: true` です。project の組のツールは、どれも `openWorldHint: false` です。よく使う読むツール 5 本（`project_read`・`project_status_read`・`workitem_read`・`execution_read`・`run_read`）には `_meta["anthropic/alwaysLoad"]` があり、ツールを後から読み込むクライアントでも最初から読み込まれます。`workitem_decide` には `_meta["anthropic/requiresUserInteraction"]` があり、Claude Code では呼ぶたびに利用者の承認を求めます（`dontAsk` のモードや、`--permission-prompt-tool` を使う非対話の実行では断られます）。AGENTIC STAR のチャットの Agent にこの MCP をつないだときは、Agent に、呼ぶ前に毎回、何をどう決めるかを示して利用者に確かめ、承認を受けてから呼ぶよう指示が付きます（利用者に確かめられない実行では呼ばないことも指示に含まれます）。
- **送り直しのキー**: REST の `Idempotency-Key` ヘッダーは、引数 `idempotencyKey` で渡します
- **システム連携**: 「システム連携」に ✅ がある 5 つの操作だけを使えます。ほかの操作は、スコープにかかわらずエラーになります

## 制限

表の値は既定の値です。環境の設定で変わることがあります。

| 対象                                                                 | 上限                                                                                                                                                                              |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| リクエストの本文                                                           | 30 MB まで。超えると `413 Payload Too Large`                                                                                                                                           |
| `execute_chat` に添えるファイル                                            | 5 個まで・1 個 5 MB まで・合わせて 20 MB まで（base64 にする前の大きさ）                                                                                                                                |
| `project_file_write` の `upload`・`update_content` のファイル             | base64 を戻して約 22 MB まで。それより大きいファイル（512 MB まで）は REST で送ってください                                                                                                                     |
| ファイルの中身を読む（`get_file_content`・`project_file_read` の `get_content`） | 5 MB を超えると、中身の代わりに、同じトークンで取れるダウンロードの URL を返します                                                                                                                                  |
| 同じ会話の `execute_chat`                                               | 1 つずつ。前の呼び出しが動いている間に送るとエラー（`CONVERSATION_BUSY`）                                                                                                                                 |
| `execute_chat` の所要時間                                               | 簡単なタスクは約 30 秒、複雑なタスクは 2〜5 分です。クライアントの待ち時間は 6 分以上にしてください。途中の動きが約 30 分無いとき、または始めてから 2 時間たったときは打ち切り、エラー（`EXECUTION_TIMEOUT`）を返します。打ち切っても結果は保存され、`list_conversation_messages` で読めます |

## エラー

つなぐときに HTTP で返るエラーです。ツールを呼んだ結果のエラーは、ツールのエラー（`isError: true`）で返ります（[提供ツール](#%E6%8F%90%E4%BE%9B%E3%83%84%E3%83%BC%E3%83%AB)）。

| HTTP Status               | 説明                                                                                                                                                                                                          |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`         | 例: `MCP-Protocol-Version` ヘッダーの値が [対応プロトコルバージョン](#%E5%AF%BE%E5%BF%9C%E3%83%97%E3%83%AD%E3%83%88%E3%82%B3%E3%83%AB%E3%83%90%E3%83%BC%E3%82%B8%E3%83%A7%E3%83%B3) に無い                                         |
| `401 Unauthorized`        | アクセストークンが無効・期限切れ                                                                                                                                                                                            |
| `403 Forbidden`           | トークンに `mcp:all`・`mcp:connect` のどちらも無い。ツールごとのスコープの不足は、HTTP の 403 ではなく、ツールのエラー（`isError: true`）で返します。前段の仕組み（WAF）で止められた場合も `403` で、本文は JSON（`error.code` が `waf_blocked`。参照番号があるときは `error.reference` に入ります）です |
| `405 Method Not Allowed`  | `POST` 以外のメソッド（`GET` など）。本エンドポイントはサーバーからのストリーム（SSE）を `GET` で開く方式とセッションを提供しません                                                                                                                               |
| `413 Payload Too Large`   | リクエストの本文が上限（[制限](#%E5%88%B6%E9%99%90)）を超えた                                                                                                                                                                  |
| `503 Service Unavailable` | 認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください                                                                                                                                                  |

## 関連ドキュメント

- [AI クライアント接続ガイド（MCP）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/ai-client-guide.md) — クライアントの設定とつなぎ方
- [接続方式ガイド - MCP](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/connection-guide.md#mcpmodel-context-protocol) — 接続方式の概要
- [認証 API リファレンス（SaaS）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/auth-saas-ref.md) — トークン取得
- [ユーザー API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md) — チャットの組の REST の口
- [プロジェクト API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md) — project の組の REST の口
- [Model Context Protocol 仕様](https://modelcontextprotocol.io/specification) — プロトコルの詳細
