MCP API リファレンス
AGENTIC STAR マーケットプレイス版が提供する MCP(Model Context Protocol) エンドポイントの詳細仕様です。MCP 対応の AI クライアント(Claude Code・Codex など)から AGENTIC STAR に接続し、ツール呼び出しで登録 Agent への依頼・ファイルの取得・プロジェクトの操作・公開したワークフローの実行を行います。
MCP は、管理者が MCP の受け口を開けた環境でだけ使えます。開けていない環境では、エンドポイントは 404 Not Found を返します。受け口の開け方は、構築の節の Helm Values リファレンス を参照してください。
クライアントの設定とつなぎ方は AI クライアント接続ガイド(MCP)、接続方式の概要は 接続方式ガイド を参照してください。
ベース URL
すべてのリクエストは以下のベース URL に対して送信します。<your-domain> は導入した環境のドメインに読み替えてください。
https://<your-domain>エンドポイント
| メソッド | エンドポイント | 説明 |
|---|---|---|
POST | /api/v1/mcp | MCP 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,published | 3 つの組のすべて |
例: 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-25 | initialize でバージョンを決める形 |
2025-06-18 | initialize でバージョンを決める形 |
2025-03-26 | initialize でバージョンを決める形 |
2024-11-05 | initialize でバージョンを決める形 |
2024-10-07 | initialize でバージョンを決める形 |
提供ツール
tools/call で呼び出せるツールは、ツールの組 ごとに次のとおりです。
チャットの組
| ツール | 説明 |
|---|---|
execute_chat | 登録 Agent にタスクを送信し、実行結果を取得 |
get_file_content | 成果物ファイルを取得 |
cancel_chat | 進行中のタスクをキャンセル |
list_agents | execute_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 | プロジェクトを読む | list | GET /v1/projects | ✅ |
list_shared | GET /v1/projects/shared | |||
get | GET /v1/projects/{projectId} | |||
get_control | GET /v1/projects/{projectId}/control | |||
list_organizations | GET /v1/projects/organizations | |||
project_status_read | キュー・KPI・記録 (証跡) を読む | list_my_queue | GET /v1/queue | |
list_queue | GET /v1/projects/{projectId}/queue | |||
get_kpi | GET /v1/projects/{projectId}/kpi | |||
list_audit_events | GET /v1/projects/{projectId}/audit | |||
project_file_read | ファイルの中身を読む | get_content | GET /v1/projects/{projectId}/files/content | |
placement_read | エージェントの配置と、置ける登録 Agent を読む | list | GET /v1/projects/{projectId}/placements | |
get | GET /v1/projects/{projectId}/placements/{placementId} | |||
list_agent_candidates | GET /v1/projects/agent-candidates | |||
run_read | ワークフローの実行(run)と成果物を読む | list | GET /v1/projects/{projectId}/runs | |
get | GET /v1/projects/{projectId}/runs/{runId} | ✅ | ||
get_config | GET /v1/projects/{projectId}/runs/{runId}/config | |||
list_artifacts | GET /v1/projects/{projectId}/artifacts | |||
get_artifact_content | GET /v1/projects/{projectId}/artifacts/{artifactId}/content | |||
execution_read | エージェントの実行を読む | list | GET /v1/projects/{projectId}/executions | |
get | GET /v1/projects/{projectId}/executions/{executionId} | |||
list_operations | GET /v1/projects/{projectId}/executions/{executionId}/operations | |||
get_timeline | GET /v1/projects/{projectId}/executions/{executionId}/timeline | |||
workitem_read | 確認依頼を読む | list | GET /v1/workitems | |
get | GET /v1/workitems/{workItemId} | |||
connector_read | 連携先(MCP サーバー・A2A エージェント)を読む | get_mcp | GET /v1/connectors/mcp/{connectionId} | |
get_a2a | GET /v1/connectors/a2a/{connectionId} | |||
project_write | プロジェクトを作る・変える | create | POST /v1/projects | |
update | PATCH /v1/projects/{projectId} | |||
step_write | ステップを足す・変える・並べ替える・消す | create | POST /v1/projects/{projectId}/steps | |
update | PATCH /v1/projects/{projectId}/steps/{stepId} | |||
reorder | PUT /v1/projects/{projectId}/steps/order | |||
delete | DELETE /v1/projects/{projectId}/steps/{stepId} | |||
placement_write | 登録 Agent を配置する・配置を変える | create | POST /v1/projects/{projectId}/placements | |
delete | DELETE /v1/projects/{projectId}/placements/{placementId} | |||
update_steps | PUT /v1/projects/{projectId}/placements/{placementId}/steps | |||
update_schedule | PATCH /v1/projects/{projectId}/placements/{placementId}/schedule | |||
project_run | ワークフローの実行を始める・トリガーを発火する・ワークフローの実行の確認担当者と締め切りを変える | start_run | POST /v1/projects/{projectId}/runs | ✅ |
fire_trigger | POST /v1/projects/{projectId}/triggers/{triggerId}/fire | ✅ | ||
reassign_approvers | PUT /v1/projects/{projectId}/runs/{runId}/approvers | |||
set_deadline | PATCH /v1/projects/{projectId}/runs/{runId} | |||
project_delete | プロジェクトを消す | — | DELETE /v1/projects/{projectId} | |
workitem_decide | 確認依頼を判断する・期限を延ばす | decide(省略可) | POST /v1/workitems/{workItemId}/decision | |
extend | PATCH /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 が外に出すものと、それぞれを呼ぶ口は次のとおりです。
| 出すもの | REST | MCP |
|---|---|---|
| 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_<名前>)の payload | JSON にして 8,000 文字まで、UTF-8 で 16 KB まで。ワークフローの最初の工程の Agent に、JSON のデータとして渡ります(ファイルの添付にはなりません) |
同じ会話の execute_chat | 1 つずつ。前の呼び出しが動いている間に送るとエラー(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 Found | MCP の受け口が開いていない環境、または外部ツールでのログイン以外で得た利用者のトークン |
405 Method Not Allowed | POST 以外のメソッド(GET など)。本エンドポイントはサーバーからのストリーム(SSE)を GET で開く方式とセッションを提供しません |
413 Payload Too Large | リクエストの本文が上限(制限)を超えた |
関連ドキュメント
- AI クライアント接続ガイド(MCP) — クライアントの設定とつなぎ方
- 接続方式ガイド — 接続方式の概要
- 認証 API リファレンス — トークン取得
- ユーザー API リファレンス(会話・組織) — チャットの組の REST の口
- ユーザー API リファレンス(プロジェクト) — プロジェクトの組の REST の口
- Model Context Protocol 仕様 — プロトコルの詳細