MCP API リファレンス（SaaS）

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

SaaS 版専用

本リファレンスのエンドポイントは SaaS 版でのみ提供 されます。Marketplace 版では MCP はビルド時に無効化されており、エンドポイントは存在しません。

接続方式の概要（接続設定例を含む）は 接続方式ガイド を参照してください。

エンドポイント

SaaS

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

ベース URL: https://api.fd.agenticstar.tm.softbank.jp

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

モード: Stateless（リクエストごとにサーバーインスタンスを生成・破棄）

認証

すべてのリクエストには Authorization: Bearer <access_token> ヘッダーが必須です。トークンには次のスコープが必要です。

スコープ	用途
mcp:exec	MCP 全体の利用（必須）
mcp:file	execute_chat でファイルを添付する場合に追加で必要

トークン取得方法は 認証 API リファレンス（SaaS） を参照してください。

リクエストヘッダー

ヘッダー	必須	説明
Authorization	✅	Bearer <access_token>
Content-Type	✅	application/json
MCP-Protocol-Version	—	クライアントがサポートする MCP プロトコルバージョン（推奨）

JSON-RPC メソッド

MCP は標準的な JSON-RPC 2.0 で通信します。本エンドポイントは以下の標準メソッドに対応しています。

メソッド	説明
initialize	クライアント / サーバー間の機能ネゴシエーション
tools/list	利用可能なツール一覧の取得
tools/call	ツールの実行
resources/list	利用可能なリソース一覧の取得
resources/read	リソースの読み取り

詳細は Model Context Protocol 仕様 を参照してください。

提供ツール

tools/call で呼び出せるツールは以下のとおりです。

execute_chat

エージェントにタスクを送信し、実行結果（応答テキスト・成果物ファイル・実行トレース）を取得します。

項目	内容
必要スコープ	mcp:exec（ファイル添付時は mcp:file も）
主な入力	prompt（必須）、conversationId（任意、会話継続）、files（任意、base64 エンコード）
主な出力	response、conversationId、deliverables[]（成果物のメタデータ）、executionSteps[]

deliverables[].size が fileSizeLimitMB（環境依存、デフォルト 20MB）を超える場合、get_file_content はインラインコンテンツの代わりにダウンロードリンクを返します。

get_file_content

execute_chat の deliverables[] または executionSteps[].files[] に含まれるファイルを取得します。

項目	内容
必要スコープ	mcp:exec
主な入力	filepath（必須）
主な出力	ファイルメタデータ + コンテンツ（小さいファイルはインライン、大きいファイルはダウンロードリンク）

cancel_chat

進行中のタスクをキャンセルします。

項目	内容
必要スコープ	mcp:exec
主な入力	conversationId（必須）
主な出力	キャンセル結果

list_personas

適用可能なペルソナ（応答人格）の一覧を取得します。

項目	内容
必要スコープ	mcp:exec
主な入力	なし
主な出力	ペルソナ一覧（key, name, description）

リクエスト例

initialize

curl

curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2024-11-05" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    }
  }'

tools/call（execute_chat）

curl

curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "execute_chat",
      "arguments": {
        "prompt": "売上データを分析してください"
      }
    }
  }'

エラーコード

JSON-RPC 2.0 標準のエラーコードを使用します。

code	説明
-32700	Parse Error（リクエストのパース失敗）
-32600	Invalid Request（JSON-RPC リクエストとして不正）
-32601	Method Not Found（未対応メソッド）
-32602	Invalid Params（パラメータ不正）
-32603	Internal Error（サーバー内部エラー）

HTTP 層のエラー:

HTTP Status	説明
401 Unauthorized	アクセストークンが無効・期限切れ
403 Forbidden	必要なスコープが不足（mcp:exec / mcp:file）
413 Payload Too Large	リクエストサイズが上限超過

関連ドキュメント

• 接続方式ガイド - MCP — 接続設定例とユースケース
• 認証 API リファレンス（SaaS） — トークン取得
• ユーザー API リファレンス — REST 経由の同等機能