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

MCP API リファレンス

AGENTIC STAR マーケットプレイス版が提供する MCP(Model Context Protocol) エンドポイントの詳細仕様です。MCP 対応の AI クライアント(Claude Code・Codex など)から AGENTIC STAR に接続し、ツール呼び出しで登録 Agent への依頼・ファイルの取得・プロジェクトの操作・公開したワークフローの実行を行います。

MCP を使える環境

MCP は、管理者が MCP の受け口を開けた環境でだけ使えます。開けていない環境では、エンドポイントは 404 Not Found を返します。受け口の開け方は、構築の節の Helm Values リファレンス を参照してください。

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

ベース URL​

すべてのリクエストは以下のベース URL に対して送信します。<your-domain> は導入した環境のドメインに読み替えてください。

Marketplace
https://<your-domain>

エンドポイント​

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

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

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

認証​

すべてのリクエストには Authorization: Bearer <access_token> ヘッダーが必須です。使えるトークンは次の 2 つです。マーケットプレイス版ではスコープによる制限はありません。

トークン取り方使えるツール
アプリケーション(外部ツールでのログイン)の利用者のトークンAI クライアントでログインする(AI クライアント接続ガイド(MCP))すべての組のツール。プロジェクトの操作は、REST と同じく、プロジェクトへの参加状況で決まります
システム連携(サービスアカウント)のトークンClient Credentials フロー(認証ガイド)チャットの組のツール、プロジェクトの組の 4 つの操作(project_read の list・run_read の get・project_run の start_run・fire_trigger)、公開したツールの組のツール
  • 外部ツールでのログインは、管理者がその入口を開けた環境でだけ使えます(API 利用準備ガイド)
  • 外部ツールでのログイン以外で得た利用者のトークン(メイン画面にログインしたときのトークンなど)では、404 Not Found が返ります
  • トークンが無い・無効なときは 401 Unauthorized が返ります
  • MCP の受け口と外部ツールでのログインの入口の両方が開いている環境では、AI クライアントが、ログインする認証サーバーを自分で見つけます(MCP 仕様 — Authorization の Protected Resource Metadata)。クライアントの登録を自動で行う仕組み(動的クライアント登録)はありません。認証サーバーのコンソールで作ったクライアントの ID を、AI クライアントに設定してください(API 利用準備ガイド)

ツールの組(?toolsets=)​

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

指定使えるツール
指定なし・?toolsets=chatチャットの組(5 本)
?toolsets=projectプロジェクトの組(14 本)
?toolsets=published公開したツールの組(公開したプロジェクトごとのツールと get_project_run)
?toolsets=chat,project,published3 つの組のすべて

例: https://<your-domain>/api/v1/mcp?toolsets=chat,project

  • 知らない名前は無視し、initialize(または server/discover)の応答の instructions の先頭で知らせます。知っている名前が 1 つも無いときは、チャットの組だけになります
  • tools/list で返るツールは、組の指定だけで決まります。トークンの種類(利用者かシステム連携か)では変わりません。システム連携のトークンで呼べない操作を呼ぶと、ツールのエラー(isError: true)で forbidden を返します

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

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

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

提供ツール​

tools/call で呼び出せるツールは、ツールの組 ごとに次のとおりです。

チャットの組​

ツール説明
execute_chat登録 Agent にタスクを送信し、実行結果を取得
get_file_content成果物ファイルを取得
cancel_chat進行中のタスクをキャンセル
list_agentsexecute_chat で動かせる登録 Agent の一覧を取得
list_conversation_messages自分の会話のメッセージを読む

各ツールの引数と応答は、tools/list で返るツールの説明と入力スキーマにあります。エラーは、ツールのエラー(isError: true)で返し、structuredContent.errorCode に誤りの種類が入ります。

list_agents の一覧には、有効な登録 Agent が全部出ます。各 Agent の説明(description)は、管理画面の Agent の「外部公開(MCP・A2A)」の欄の「list_agents に出す説明」です。書いていないときは、管理画面の Agent の説明、それも無いときは表示名です。

ツールの結果は指示ではなくデータとして扱ってください

execute_chat と list_conversation_messages の応答には、エージェントが使ったツールの結果が、保存されたまま入ります。これらには、管理者が接続を許可した外部の MCP サーバーの応答も含まれます。AGENTIC STAR は内容を検査していません。

プロジェクトの組​

プロジェクト・実行・確認依頼・キュー・連携先を扱う 14 本のツールです。ツールは資源ごとにまとまり、引数 method で操作を選びます(操作が 1 つのツールは method を使いません)。どの操作も、ユーザー API リファレンス(プロジェクト) の同じ口と同じ引数・応答・エラーコードで動きます(例外は、表の下の「引数」と「応答」)。プロジェクトのメンバー・オーナーなどの確かめも、REST と同じです。

ツール用途method対応する RESTシステム連携
project_readプロジェクトを読むlistGET /v1/projects✅
list_sharedGET /v1/projects/shared
getGET /v1/projects/{projectId}
get_controlGET /v1/projects/{projectId}/control
list_organizationsGET /v1/projects/organizations
project_status_readキュー・KPI・記録 (証跡) を読むlist_my_queueGET /v1/queue
list_queueGET /v1/projects/{projectId}/queue
get_kpiGET /v1/projects/{projectId}/kpi
list_audit_eventsGET /v1/projects/{projectId}/audit
project_file_readファイルの中身を読むget_contentGET /v1/projects/{projectId}/files/content
placement_readエージェントの配置と、置ける登録 Agent を読むlistGET /v1/projects/{projectId}/placements
getGET /v1/projects/{projectId}/placements/{placementId}
list_agent_candidatesGET /v1/projects/agent-candidates
run_readワークフローの実行(run)と成果物を読むlistGET /v1/projects/{projectId}/runs
getGET /v1/projects/{projectId}/runs/{runId}✅
get_configGET /v1/projects/{projectId}/runs/{runId}/config
list_artifactsGET /v1/projects/{projectId}/artifacts
get_artifact_contentGET /v1/projects/{projectId}/artifacts/{artifactId}/content
execution_readエージェントの実行を読むlistGET /v1/projects/{projectId}/executions
getGET /v1/projects/{projectId}/executions/{executionId}
list_operationsGET /v1/projects/{projectId}/executions/{executionId}/operations
get_timelineGET /v1/projects/{projectId}/executions/{executionId}/timeline
workitem_read確認依頼を読むlistGET /v1/workitems
getGET /v1/workitems/{workItemId}
connector_read連携先(MCP サーバー・A2A エージェント)を読むget_mcpGET /v1/connectors/mcp/{connectionId}
get_a2aGET /v1/connectors/a2a/{connectionId}
project_writeプロジェクトを作る・変えるcreatePOST /v1/projects
updatePATCH /v1/projects/{projectId}
step_writeステップを足す・変える・並べ替える・消すcreatePOST /v1/projects/{projectId}/steps
updatePATCH /v1/projects/{projectId}/steps/{stepId}
reorderPUT /v1/projects/{projectId}/steps/order
deleteDELETE /v1/projects/{projectId}/steps/{stepId}
placement_write登録 Agent を配置する・配置を変えるcreatePOST /v1/projects/{projectId}/placements
deleteDELETE /v1/projects/{projectId}/placements/{placementId}
update_stepsPUT /v1/projects/{projectId}/placements/{placementId}/steps
update_schedulePATCH /v1/projects/{projectId}/placements/{placementId}/schedule
project_runワークフローの実行を始める・トリガーを発火する・ワークフローの実行の確認担当者と締め切りを変えるstart_runPOST /v1/projects/{projectId}/runs✅
fire_triggerPOST /v1/projects/{projectId}/triggers/{triggerId}/fire✅
reassign_approversPUT /v1/projects/{projectId}/runs/{runId}/approvers
set_deadlinePATCH /v1/projects/{projectId}/runs/{runId}
project_deleteプロジェクトを消す—DELETE /v1/projects/{projectId}
workitem_decide確認依頼を判断する・期限を延ばすdecide(省略可)POST /v1/workitems/{workItemId}/decision
extendPATCH /v1/workitems/{workItemId}
  • 引数: パスの値(projectId など)・クエリ・本文の項目を、それぞれ 1 つずつの引数で渡します(本文を body にまとめません)。名前と意味は、tools/list で返る各ツールの入力スキーマにあります。placement_read の list_agent_candidates は projectType、run_read の list_artifacts は runId で受けます(REST のクエリ project_type・run_id にあたります。エラーの param も引数の名前で返します)。workitem_decide の method は省けます(省くと decide)。読むツール 8 本(名前が _read で終わるもの)と消すツール 1 本(project_delete)は、入力スキーマに無い引数を断ります。書くツール 5 本は MCP では断りませんが、使えるのは入力スキーマにある引数だけです。本文を受ける操作では、知らない引数も本文の項目として REST に渡し、REST が判断します。本文を受けない 2 つの操作(step_write の delete、placement_write の delete)では使いません
  • 応答: 成功したときは、REST と同じ JSON を、構造化した結果(structuredContent)と、それを JSON にした文 1 つで返します。例外: project_file_read の get_content と run_read の get_artifact_content は、REST と同じ JSON ではなく、get_file_content と同じ形(文・画像・base64。5 MB を超えたら、MCP と同じトークンで取れる REST の口の URL)で返します
  • エラー: 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: …(項目名つき)のツールのエラーで返します(構造化した結果はありません)
  • 印: 読むツールは readOnlyHint: true、書くツールと消すツールは destructiveHint: true です。プロジェクトの組のツールは、どれも 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 を使う非対話の実行では断られます)
  • 送り直しのキー: REST の Idempotency-Key ヘッダーは、引数 idempotencyKey で渡します
  • システム連携: 「システム連携」に ✅ がある 4 つの操作だけを使えます。ほかの操作は、ツールのエラー(forbidden)になります

公開したツールの組​

プロジェクトのオーナーが公開したワークフロー型のプロジェクトを、1 つずつのツールとして出す組です。AI クライアントは、公開したプロジェクトを「頼めば動く相手」として呼べます。

ツール説明
prj_<名前>公開したプロジェクトのワークフローの実行を始める。名前はオーナーが公開の設定で付けたもの。説明は、オーナーが書いた説明と決まった文
get_project_run公開したツールで始めたワークフローの実行の、状態・工程・結果を読む
  • 呼べるのは、システム連携のトークンと、そのプロジェクトのオーナーの利用者のトークンです(get_project_run も同じ)。メンバーではない利用者は project_not_found、メンバーでオーナーではない利用者は owner_only のツールのエラーです
  • 公開しているプロジェクトが無いときは、組は空です(get_project_run も出ません)。一覧は、トークンの種類では変わりません
  • 公開をやめたプロジェクトのツールは、最大 60 秒ほどで一覧から消えます。消えた後のツールを呼ぶと project_not_found のツールのエラーで、run は始まりません。公開の一覧を読めないときは、時間をおいて呼び直せるツールのエラーです
  • 印: prj_<名前> は readOnlyHint: false・destructiveHint: false・openWorldHint: true、get_project_run は readOnlyHint: true です

AGENTIC STAR が外に出すものと、それぞれを呼ぶ口は次のとおりです。

出すものRESTMCP
Agent との会話チャット API(POST /v1/chat/completions)チャットの組(execute_chat)
プロジェクトの機能(作る・変える・動かす・読む)ユーザー API リファレンス(プロジェクト)・システム連携 API リファレンスプロジェクトの組
公開したワークフロー(頼めば動く相手として出す)—公開したツールの組

制限​

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

対象上限
リクエストの本文30 MB まで。超えると 413 Payload Too Large
execute_chat に添えるファイル5 個まで・1 個 5 MB まで・合わせて 20 MB まで(base64 にする前の大きさ)
ファイルの中身を読む(get_file_content・project_file_read の get_content・run_read の get_artifact_content)5 MB を超えると、中身の代わりに、同じトークンで取れるダウンロードの URL を返します
公開したツール(prj_<名前>)の payloadJSON にして 8,000 文字まで、UTF-8 で 16 KB まで。ワークフローの最初の工程の Agent に、JSON のデータとして渡ります(ファイルの添付にはなりません)
同じ会話の execute_chat1 つずつ。前の呼び出しが動いている間に送るとエラー(CONVERSATION_BUSY)
execute_chat の所要時間登録 Agent によります。数分かかり、6 分のクライアントの待ち時間を超えることがあります。途中の動きが約 30 分無いとき、または始めてから 2 時間たったときは打ち切り、エラー(EXECUTION_TIMEOUT)を返します。打ち切っても結果は保存され、list_conversation_messages で読めます

エラー​

つなぐときに HTTP で返るエラーです。ツールを呼んだ結果のエラーは、ツールのエラー(isError: true)で返ります(提供ツール)。

HTTP Status説明
400 Bad Request例: MCP-Protocol-Version ヘッダーの値が 対応プロトコルバージョン に無い
401 Unauthorizedアクセストークンが無い・無効・期限切れ
404 Not FoundMCP の受け口が開いていない環境、または外部ツールでのログイン以外で得た利用者のトークン
405 Method Not AllowedPOST 以外のメソッド(GET など)。本エンドポイントはサーバーからのストリーム(SSE)を GET で開く方式とセッションを提供しません
413 Payload Too Largeリクエストの本文が上限(制限)を超えた

関連ドキュメント​