メインコンテンツまでスキップ

MCP API リファレンス

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

SaaS 版の仕様

本リファレンスは SaaS 版の MCP の仕様です。マーケットプレイス版の MCP は MCP API リファレンス(マーケットプレイス版) を参照してください。

クライアントの設定とつなぎ方は AI クライアント接続ガイド(MCP)、接続方式の概要は 接続方式ガイド を参照してください。

ベース URL​

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

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

エンドポイント​

SaaS
メソッドエンドポイント説明
POST/api/v1/mcpMCP JSON-RPC エンドポイント(Streamable HTTP, Stateless モード)

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

モード: Stateless(セッションを持ちません)

認証​

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

スコープ用途
mcp:allMCP のすべてのツールを使えます。ほかのスコープは要りません
mcp:connectMCP に接続できます。使えるツール(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=projectproject の組(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-25initialize でバージョンを決める形
2025-06-18initialize でバージョンを決める形
2025-03-26initialize でバージョンを決める形
2024-11-05initialize でバージョンを決める形
2024-10-07initialize でバージョンを決める形

提供ツール​

tools/call で呼び出せるツールは、ツールの組 ごとに次のとおりです。「必要スコープ」は、mcp:all のトークンでは問われません。mcp:connect のトークンでは、そのスコープも要ります。

チャットの組​

ツール説明必要スコープ(mcp:connect のとき)
execute_chatエージェントにタスクを送信し、実行結果を取得chat:exec(ファイルを添えるときは加えて chat:file)
get_file_content成果物ファイルを取得chat:exec
get_ui_resourceUI リソースの 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 と同じです。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プロジェクトを読むlistGET /v1/projectsproject:read✅
list_sharedGET /v1/projects/sharedproject:read
getGET /v1/projects/{projectId}project:read
get_controlGET /v1/projects/{projectId}/controlproject:read
list_organizationsGET /v1/projects/organizationsproject:read
list_automation_destinationsGET /v1/projects/automation-destinationsproject:read
export_definitionGET /v1/projects/{projectId}/definitionproject:read
get_definition_approvalGET /v1/projects/{projectId}/definition-approvalproject:read
project_status_readキュー・KPI・記録 (証跡) を読むlist_my_queueGET /v1/queueproject:read
list_queueGET /v1/projects/{projectId}/queueproject:read
get_kpiGET /v1/projects/{projectId}/kpiproject:read
get_kpi_trendsGET /v1/projects/{projectId}/kpi/trendsproject:read
list_audit_eventsGET /v1/projects/{projectId}/auditproject:read
project_file_readプロジェクトのライブラリとファイルの中身を読むlistGET /v1/projects/{projectId}/libraryproject:read
list_versionsGET /v1/projects/{projectId}/library/{fileId}/versionsproject:read
get_contentGET /v1/projects/{projectId}/files/contentproject:read
placement_readエージェントの配置を読むlistGET /v1/projects/{projectId}/placementsproject:read
getGET /v1/projects/{projectId}/placements/{placementId}project:read
get_memory_candidatesGET /v1/projects/{projectId}/memory-candidatesproject:read
run_readワークフローの実行(run)を読むlistGET /v1/projects/{projectId}/runsproject:read
getGET /v1/projects/{projectId}/runs/{runId}project:read✅
get_configGET /v1/projects/{projectId}/runs/{runId}/configproject:read
get_resume_optionsGET /v1/projects/{projectId}/runs/{runId}/resumeproject:read
execution_readエージェントの実行を読むlistGET /v1/projects/{projectId}/executionsproject:read
getGET /v1/projects/{projectId}/executions/{executionId}project:read
list_operationsGET /v1/projects/{projectId}/executions/{executionId}/operationsproject:read
get_timelineGET /v1/projects/{projectId}/executions/{executionId}/timelineproject:read
workitem_read確認依頼を読むlistGET /v1/workitemsproject:read
getGET /v1/workitems/{workItemId}project:read
connector_read連携先(MCP サーバー・A2A AIエージェント)を読むget_mcpGET /v1/connectors/mcp/{connectionId}project:read
get_a2aGET /v1/connectors/a2a/{connectionId}project:read
webhook_readプロジェクトの Webhook と配送の結果を読むlistGET /v1/projects/{projectId}/webhooksproject:read
list_deliveriesGET /v1/projects/{projectId}/webhooks/{webhookId}/deliveriesproject:read
agent_readライブラリの Agent を読むlistGET /v1/agentsassets:read
list_sharedGET /v1/agents/sharedassets:read
getGET /v1/agents/{agentId}assets:read
playbook_readライブラリの Playbook を読むlistGET /v1/playbooksassets:read か chat:exec
list_sharedGET /v1/playbooks/sharedassets:read か chat:exec
getGET /v1/playbooks/{playbookId}assets:read
skill_readライブラリの Skill を読むlistGET /v1/skillsassets:read か chat:exec
list_sharedGET /v1/skills/sharedassets:read か chat:exec
getGET /v1/skills/{skillId}assets:read
list_versionsGET /v1/skills/{skillId}/versionsassets:read
list_filesGET /v1/skills/{skillId}/filesassets:read
get_fileGET /v1/skills/{skillId}/files/contentassets:read
project_writeプロジェクトを作る・変えるcreatePOST /v1/projectsproject:write
updatePATCH /v1/projects/{projectId}project:write
importPOST /v1/projects/importproject:write
dismiss_relinkDELETE /v1/projects/{projectId}/relinkproject:write
withdraw_definitionDELETE /v1/projects/{projectId}/definition-approvalproject:write
project_file_writeプロジェクトのライブラリのファイルを足す・変える・消すuploadPOST /v1/projects/{projectId}/libraryproject:write
copyPOST /v1/projects/{projectId}/library/copyproject:write
update_contentPUT /v1/projects/{projectId}/library/{fileId}/contentproject:write
restorePOST /v1/projects/{projectId}/library/{fileId}/restoreproject:write
import_latestPOST /v1/projects/{projectId}/library/{fileId}/import-latestproject:write
deleteDELETE /v1/projects/{projectId}/library/{fileId}project:write
step_writeステップを足す・変える・並べ替える・消すcreatePOST /v1/projects/{projectId}/stepsproject:write
updatePATCH /v1/projects/{projectId}/steps/{stepId}project:write
reorderPUT /v1/projects/{projectId}/steps/orderproject:write
deleteDELETE /v1/projects/{projectId}/steps/{stepId}project:write
placement_writeエージェントを配置する・配置を変える・工程にファイルを対応づけるcreatePOST /v1/projects/{projectId}/placementsproject:write
deleteDELETE /v1/projects/{projectId}/placements/{placementId}project:write
update_stepsPUT /v1/projects/{projectId}/placements/{placementId}/stepsproject:write
update_memoryPATCH /v1/projects/{projectId}/placements/{placementId}/memoryproject:write
update_instructionPATCH /v1/projects/{projectId}/placements/{placementId}/instructionproject:write
update_schedulePATCH /v1/projects/{projectId}/placements/{placementId}/scheduleproject:write
update_library_bindingsPUT /v1/projects/{projectId}/placements/{placementId}/library-bindingsproject:write
trigger_writeトリガーを作る・変える・消すcreatePOST /v1/projects/{projectId}/triggersproject:write
updatePATCH /v1/projects/{projectId}/triggers/{triggerId}project:write
deleteDELETE /v1/projects/{projectId}/triggers/{triggerId}project:write
webhook_writeプロジェクトの Webhook を作る・変える・消す(secret は返りません)createPOST /v1/projects/{projectId}/webhooksproject:write
updatePATCH /v1/projects/{projectId}/webhooks/{webhookId}project:write
deleteDELETE /v1/projects/{projectId}/webhooks/{webhookId}project:write
project_runワークフローの実行を始める・トリガーを発火する・失敗した巡回の実行をもう一度動かす・ワークフローの実行の確認担当者と締め切りを変える・閉じたワークフローの実行を再開する・ワークフローの実行を中断するstart_runPOST /v1/projects/{projectId}/runsproject:run✅
fire_triggerPOST /v1/projects/{projectId}/triggers/{triggerId}/fireproject:run✅
rerun_executionPOST /v1/projects/{projectId}/executions/{executionId}/rerunproject:run
reassign_approversPUT /v1/projects/{projectId}/runs/{runId}/approversproject:write
set_deadlinePATCH /v1/projects/{projectId}/runs/{runId}project:write
resume_runPOST /v1/projects/{projectId}/runs/{runId}/resumeproject:run
cancel_runPOST /v1/projects/{projectId}/runs/{runId}/cancelproject:run✅
project_deleteプロジェクトを消す—DELETE /v1/projects/{projectId}project:delete
workitem_decide確認依頼を判断する・期限を延ばすdecide(省略可)POST /v1/workitems/{workItemId}/decisionproject:decide
extendPATCH /v1/workitems/{workItemId}project:decide
agent_writeAgent を作る・変える・コピーするcreatePOST /v1/agentsassets:write
updatePATCH /v1/agents/{agentId}assets:write
copyPOST /v1/agents/{agentId}/copyassets:write
playbook_writePlaybook を作る・変える・コピーするcreatePOST /v1/playbooksassets:write
updatePATCH /v1/playbooks/{playbookId}assets:write
copyPOST /v1/playbooks/{playbookId}/copyassets:write
skill_writeSkill を作る・ファイルと設定を変える・コピーするcreatePOST /v1/skillsassets:write
replace_filesPUT /v1/skills/{skillId}/filesassets:write
edit_filesPATCH /v1/skills/{skillId}/filesassets:write
update_settingsPATCH /v1/skills/{skillId}assets:write
copyPOST /v1/skills/{skillId}/copyassets:write
agent_deleteAgent を消す—DELETE /v1/agents/{agentId}assets:delete
playbook_deletePlaybook を消す—DELETE /v1/playbooks/{playbookId}assets:delete
skill_deleteSkill を消す—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_chat1 つずつ。前の呼び出しが動いている間に送るとエラー(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 AllowedPOST 以外のメソッド(GET など)。本エンドポイントはサーバーからのストリーム(SSE)を GET で開く方式とセッションを提供しません
413 Payload Too Largeリクエストの本文が上限(制限)を超えた
503 Service Unavailable認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください

関連ドキュメント​