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

MCP サーバ リファレンス

Kuroco は Model Context Protocol (MCP) のサーバを 2 系統提供しています。このページでは、それぞれのエンドポイントと認証方式、ツールの構成をまとめます。

サーバエンドポイント用途
クライアント API MCP サーバ/rcms-api/{id}/mcpClient API のエンドポイントを MCP ツールとして公開します。
Admin MCP サーバ/direct/rcms_api/admin_mcp/Admin API と同等の管理操作を MCP ツールとして公開します。

MCP クライアント側（Claude Code、Claude Desktop、Cursor など）の設定方法は MCP クライアント設定リファレンス を参照してください。

クライアント API MCP サーバ​

API 単位で提供される MCP サーバです（例: https://{your-site}.g.kuroco.app/rcms-api/{id}/mcp）。エンドポイントごとに MCP 設定（ツール名 / 入力データ定義 / ステータス）を有効化すると、そのエンドポイントが MCP ツールとして公開されます。

設定手順の詳細は Model Context Protocol (MCP) と Kuroco の連携 を参照してください。

認証​

接続方法は API のセキュリティ設定に従います。

API のセキュリティ接続方法
NoneMCP サーバの URL のみで接続できます（認証なし）。
静的トークン / 特権付き静的トークンX-RCMS-API-ACCESS-TOKEN ヘッダーにトークンを設定します。ヘッダー認証に対応したクライアントが必要です。
OAuth（OAuth Authorization Server、用途 = API）OAuth 認証で接続します。Claude.ai のコネクタ機能などが対応しています。
注意

認証なしの公開エンドポイントは本番運用では推奨されません。詳細は MCP クライアント設定リファレンス を参照してください。

OAuth 認証を利用した Claude.ai コネクタの登録手順は Claude.ai での MCP コネクタの登録方法 を参照してください。

Admin MCP サーバ​

Admin API と同等の管理操作を、JSON-RPC 2.0 ベースの MCP サーバ として /direct/rcms_api/admin_mcp/ から提供しています。MCP 対応クライアントはこのエンドポイントを直接登録するだけで利用でき、CLI のビルドは不要です。

認証​

認証方式はリクエストのホストによって自動的に切り替わります。

ホスト方式補足
ROOT_MNG_URL管理セッション Cookie管理画面と同じログインフロー。direct.php 標準フローで自動復元されます。
ROOT_API_URLBearer トークン（Authorization ヘッダ）OAuth Authorization Server アクセストークン（target_domain=AdminMCP、RFC 8707 準拠で audience 拘束）または、OAuth ハンドシェイクを張れないツール向けに AdminMCPServer::generateToken() で発行する特権 static トークン（api_id=-1）を受け付けます。

401 レスポンスには RFC 6750 準拠の WWW-Authenticate チャレンジが含まれ、resource_metadata で次のメタデータ文書を案内します。

/.well-known/oauth-protected-resource/direct/rcms_api/admin_mcp/

このエンドポイントは認証不要の公開エンドポイントで、MCP クライアントは事前認証なしで Authorization Server を発見できます。?MODE=protected_resource_metadata 経由でも到達可能です。

モジュールスコープ付き MCP サーバ​

/admin_mcp/ 以降のパスセグメントで、1 つの MCP サーバ（=1 認証情報）に複数の管理モジュールをバンドルできます。GitHub MCP の /x/<csv>/readonly パターンに準拠しています。

POST /direct/rcms_api/admin_mcp/                                     # 全ツール（管理／discovery のみ）
POST /direct/rcms_api/admin_mcp/x/topics_group_1,topics_group_5,member,services
POST /direct/rcms_api/admin_mcp/x/topics_group_1,topics_group_5/readonly
POST /direct/rcms_api/admin_mcp/x/topics_group                       # グループ定義 CRUD

認識される CSV エントリ（t_ai_agent.admin_mcp_modules の格納値と同じ識別子）:

エントリ意味
topics_group_<N>topics_group_id = N にスコープした topics レコード操作。各ツールの topics_group_id 引数は enum として制約され、許可外グループへの呼び出しは拒否されます。
topicsグループ制約なしの同等表現。discovery 専用で、ツール呼び出しは拒否されます。
topics_groupグループ定義の管理（t_topics_group の CRUD）。
servicesサービスモデル（Email、Slack など）。
<mt>その他任意の管理モジュール（member、ec、batch など）。

モジュール指定時の挙動:

  • 書き込み系コントローラは MODE 単位（INSERT / UPDATE / DELETE）にツール分割
  • レコード数がゼロのモジュールは読み取り系ツールが除外される
  • 空モジュールでは INSERT のみが表示される

パスに /readonly を付与すると、書き込み系ツールはリストから除外されます。

モジュール一覧（REST）​

GET /direct/rcms_api/admin_mcp/?MODE=tools

レスポンス:

{
  "modules": [
    {"module": "topics",   "type": "controller", "tool_count": 8},
    {"module": "member",   "type": "controller", "tool_count": 5},
    {"module": "services", "type": "service",    "tool_count": 4}
  ]
}

MCP プロトコル​

HTTP POST + JSON-RPC 2.0。サポートメソッド:

メソッド説明
initializeハンドシェイク・プロトコルバージョン交渉
notifications/initializedクライアント準備完了通知
ping接続確認
tools/list利用可能な管理ツール一覧（モジュールスコープ反映）
tools/call名前指定で管理ツールを実行

ツール名は {mt}-{verb} の畳まれた形式で生成されます。コントローラ名の語尾と MODE が動詞にマッピングされます（例: INSERT → create、_list_api → list）。

種別パターン例
List コントローラ（{mt}_list_api、MODE なし）{mt}-listtopics-list
List コントローラ + MODE{mt}-{mode}topics-accept
List コントローラの一括処理 MODE（DELETE 等）{mt}-bulk_{mode}topics-bulk_delete
用途特化型の list（{mt}_{spec}_list_api）{mt}-{spec}_listtopics-waiting_for_approval_list
Edit コントローラ INSERT{mt}-createtopics-create
Edit コントローラ UPDATE{mt}-updatetopics-update
Edit コントローラ DELETE{mt}-deletetopics-delete
Edit コントローラ VALIDATE{mt}-validatetopics-validate
サブエンティティのコントローラ（topics_group_edit_api など）{mt}-{sub}-{verb}topics-group-create
Fetch ヘルパー{mt}-fetchtopics-fetch
topics 専用の describe ツール（ハードコード）—topics-describe
サービスメソッド{mt}-{method}Email-send

実際のツール一覧はモジュールが公開するコントローラに依存します。スコープ URL に対して JSON-RPC の tools/list を発行して列挙してください。

呼び出し例:

POST /direct/rcms_api/admin_mcp/x/topics_group_1
Authorization: Bearer <token>
Content-Type: application/json

{"jsonrpc":"2.0","method":"tools/call",
 "params":{"name":"topics-create",
           "arguments":{"subject":"Hello","topics_group_id":1}},
 "id":3}

Admin CLI と Admin MCP の使い分け​

用途推奨
管理ログインを使ったローカル対話開発Admin CLI（kuroco-admin）
MCP ネイティブ対応クライアント（Claude Code / Claude Desktop など）Admin MCP サーバ
トークンローテーションを伴う CI／無人エージェントAdmin MCP サーバ（特権 static トークン）
エンドユーザー認可フロー（委任アクセス）Admin MCP サーバ（OAuth Authorization Server target_domain=AdminMCP）
シェルスクリプトや CLI パイプとの混在Admin CLI（kuroco-admin）

Admin CLI（kuroco-admin）の詳細は Kuroco Skills リファレンス を参照してください。

どちらの経路も課金対象

/direct/rcms_api/admin_api/ と /direct/rcms_api/admin_mcp/ はともに /direct/ 配下のため、Kuroco の課金対象です。意図しない書き込みトラフィックを抑えるには、モジュールスコープ付き URL と /readonly の活用を推奨します。

Client CLI

Client API に CLI ベースでアクセスする場合は、別途 Client CLI（kuroco-client）も利用可能です。 詳細は Kuroco AI アーキテクチャ を参照してください。

関連ドキュメント​

サポート

お探しのページは見つかりましたか？解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。

フォームから問い合わせをする
Slackコミュニティに参加する