MCP API リファレンス
AGENTIC STAR SaaS版が提供する MCP(Model Context Protocol) エンドポイントの詳細仕様です。MCP は MCP 対応 AI エージェント(Claude 等)から AGENTIC STAR に接続し、ツール呼び出しでタスク実行・ファイル取得・プロジェクトの操作を行うためのインターフェースです。
本リファレンスは SaaS 版の MCP の仕様です。マーケットプレイス版の MCP は MCP API リファレンス(マーケットプレイス版) を参照してください。
クライアントの設定とつなぎ方は AI クライアント接続ガイド(MCP)、接続方式の概要は 接続方式ガイド を参照してください。
ベース URL
すべてのリクエストは以下のベース URL に対して送信します。
https://api.fd.agenticstar.tm.softbank.jpエンドポイント
| メソッド | エンドポイント | 説明 |
|---|---|---|
| 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 の組は操作)は、あわせて持つスコープで決まります(提供ツール の各表の「必要スコープ」) |
mcp:connect を勧めます新しく作るアプリには、mcp:connect と、使うツールに要るスコープだけを付けてください。mcp:all は MCP のすべてのツールを使えるスコープです。
mcp:all を持つアプリで使えるツールが増えましたmcp:all を持つアプリは、ツールの組 で 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 キー)。
トークン取得方法は 認証 API リファレンス(SaaS) を参照してください。
ツールの組(?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 で呼び出せるツールは、ツールの組 ごとに次のとおりです。「必要スコープ」は、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 は内容を検査していません。
get_ui_resource は HTML をそのまま返し、そのぶんコンテキストを使います。uiResources[].size(バイト)を先に確かめ、大きいときは利用者に確かめてから呼んでください。size は無いことがあります。
下書き(drafts[])
チャットで Playbook・Skill・プロジェクト・Agent の直し・定期実行の下書きを頼むと、execute_chat の structuredContent.drafts[] に下書きが出た順に入り、そのときだけ structuredContent.draftsNote(モデル向けの英文の注)が付きます。下書きが 1 つも無い応答には、drafts と draftsNote の鍵は付きません(uiResources と同じ)。各要素の形と作り方は ストリーミングガイド — 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 リファレンス の同じ口と同じ引数・応答・エラーコードで動きます(例外は、表の下の「引数」と「応答」)。プロジェクトのメンバー・オーナーなどの確かめも、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(次の工程に渡す値と資料の役割。工程の項目)を、project_writeのcreateはsteps[].outputConfigを受けます。run_read・execution_read・workitem_readの答えのhandoff(工程の間で渡った値と資料)の意味は、実行状況の取得・実行の結果の取得・確認依頼の取得の項目の表にあります - 応答: 成功したときは、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)で返ります(提供ツール)。
| HTTP Status | 説明 |
|---|---|
400 Bad Request | 例: MCP-Protocol-Version ヘッダーの値が 対応プロトコルバージョン に無い |
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 | リクエストの本文が上限(制限)を超えた |
503 Service Unavailable | 認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください |
関連ドキュメント
- AI クライアント接続ガイド(MCP) — クライアントの設定とつなぎ方
- 接続方式ガイド - MCP — 接続方式の概要
- 認証 API リファレンス(SaaS) — トークン取得
- ユーザー API リファレンス — チャットの組の REST の口
- プロジェクト API リファレンス — project の組の REST の口
- Model Context Protocol 仕様 — プロトコルの詳細