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

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 ヘッダーにトークンを設定します。ヘッダー認証に対応したクライアントが必要です。
動的アクセストークン / CookieOAuth 認証で接続します（OAuth Authorization Server、用途 = API）。Claude.ai のコネクタ機能などが対応しています。

動的アクセストークン / Cookie の場合、このMCPサーバのリソース識別子（RFC 8707 の resource）は MCP サーバの URL です。アクセストークンはこの識別子に拘束されます。

{API ドメイン}/rcms-api/{id}/mcp

401 レスポンスには RFC 6750 準拠の WWW-Authenticate チャレンジが含まれ、resource_metadata で次のメタデータ文書（RFC 9728 Protected Resource Metadata）を案内します。MCP サーバの URL からメタデータ文書の URL を導出するクライアントも、同じ URL に到達します。

{API ドメイン}/.well-known/oauth-protected-resource/rcms-api/{id}/mcp

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

注記

同じ API の REST エンドポイント（/rcms-api/{id}）は別の OAuth リソースです。MCP サーバ用に取得したトークンで REST を呼び出すことはできません（逆も同様です）。

注意

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

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

Admin MCP サーバ​

Admin API と同等の管理操作を、JSON-RPC 2.0 ベースの MCP サーバ として /direct/rcms_api/admin_mcp/ から提供しています。MCP 対応クライアントは、後述するモジュールスコープ付き URL（例: /direct/rcms_api/admin_mcp/x/all）を登録するだけで利用でき、CLI のビルドは不要です。

認証​

認証方式は、リクエストに含まれる資格情報によって切り替わります。

資格情報方式補足
Bearer トークン（Authorization ヘッダ）OAuth アクセストークンOAuth Authorization Server（用途 = AdminMCP）が発行するアクセストークンのみを受け付けます。トークンは RFC 8707 準拠で、アクセス先のスコープ付き URL（/x/...）に audience 拘束されます。OAuth の認可フローを対話的に実行できない CI や無人エージェントには client_credentials グラントを利用します。
Bearer トークンなし（管理画面ドメインからのアクセス）管理セッション Cookie管理画面と同じログインセッションを利用します。

401 レスポンスには RFC 6750 準拠の WWW-Authenticate チャレンジが含まれ、resource_metadata でアクセスしたスコープ付き URL に対応するメタデータ文書（RFC 9728 Protected Resource Metadata）を案内します。

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

メタデータ文書はスコープ付き URL ごとに配信されます（上記は /x/all の例）。認証不要の公開エンドポイントで、MCP クライアントは事前認証なしで Authorization Server を発見できます。?MODE=protected_resource_metadata 経由でも到達可能です。

OAuth スコープ​

アクセストークンには、実行できる操作の種別を表すスコープを付与します。「どのモジュールを操作できるか」はスコープではなく、トークンの audience（/x/... のバンドル URL）で決まります。

スコープ実行できる操作
mcp:tools.read参照系ツールの実行と tools/list
mcp:tools.write更新系ツールの実行と tools/list（参照系も実行できます）
mcp:adminすべてのツールの実行。トークンを発行するツールはこのスコープでのみ利用できます。
mcp:tools.listtools/list のみ（ツールは実行できません）
  • 401 の WWW-Authenticate チャレンジには、アクセス先のバンドルに必要なスコープが含まれます。/readonly のバンドルでは更新系のスコープを要求しません。
  • スコープが不足している場合は 403、WWW-Authenticate の error="insufficient_scope"、および JSON-RPC のエラーを返します。
  • mcp:admin を持たないトークンは、上記のいずれかのスコープが少なくとも 1 つ必要です。openid のみのトークンはどのツールにも到達しません。
  • 管理セッション Cookie での接続は、スコープによる制限を受けません（管理者の権限に従います）。

IP アドレスによるアクセス制限​

Admin MCP エンドポイントは、管理画面や KurocoFiles の IP アドレス制限の対象外です（送信元 IP アドレスが一定しないクラウド型の MCP クライアントに対応するため）。ネットワークで接続元を限定する場合は、Admin MCP 専用の許可 IP リストを有効にします。

設定箇所は [環境設定] -> [管理画面] の「Admin MCPのアクセス制限(IPアドレス)」です。[有効にする]にチェックを入れ、許可する IP アドレスを 1 行に 1 つ入力します。CIDR 表記、#コメント、[[IPSETS_*]] 定数を利用できます。設定手順は 管理画面 を参照してください。

適用範囲と挙動は次のとおりです。

項目内容
対象Admin MCP エンドポイント（/direct/rcms_api/admin_mcp/、モジュールスコープ付き URL と ?MODE=tools を含む）、およびファイルアップロード用エンドポイント（/direct/rcms_api/mcp_upload/）。
対象の認証経路Bearer トークン（OAuth アクセストークン）と管理セッション Cookie の両方。
対象外?MODE=protected_resource_metadata（RFC 9728 のメタデータ配信）。認証不要の公開エンドポイントのまま維持されます。
判定タイミング認証よりも前に判定されます。許可されない IP アドレスからのリクエストは、トークンの正否にかかわらず 403 を返します。
拒否時のレスポンス403 と JSON-RPC のエラーボディ（Access from this IP address is not allowed.）。
無効時の挙動[有効にする]が OFF の場合、またはリストが空（コメント行のみの場合を含む）の場合は制限しません。既定では制限なしです。
定数の展開結果が空の場合許可 IP が 1 件も得られないため、すべてのリクエストを拒否します（未定義の [[IPSETS_*]] を指定した場合など）。
管理画面の IP アドレス制限との関係

「管理画面のアクセス制限(IPアドレス)」は Admin MCP エンドポイントには適用されません。ただし、OAuth の認可コードフロー（authorization_code）と管理セッション Cookie の利用では、途中で管理画面のログイン・同意画面を経由するため、その画面が「管理画面のアクセス制限(IPアドレス)」の対象になります。
client_credentials によるトークン取得、リフレッシュトークンによる更新、および発行済みトークンでの Admin MCP 呼び出しは、「管理画面のアクセス制限(IPアドレス)」の対象外です。これらも含めて接続元を限定する場合に「Admin MCPのアクセス制限(IPアドレス)」を利用します。

注意

この制限は、管理画面内の AI エージェント機能（AIエージェントアシスト など）による Admin MCP へのアクセスにも適用されます。リストに含まれていない IP アドレスから管理画面を利用している管理者は、自分の IP アドレスを追加するまで、これらの機能を利用できません。
[環境設定] -> [管理画面] の画面自体はこの制限の対象外のため、設定の変更・解除は引き続き可能です。

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

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

POST /direct/rcms_api/admin_mcp/x/all                                # 全ツール
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
注意

スコープ指定（/x/...）は必須です。ベース URL（/direct/rcms_api/admin_mcp/）への直接のリクエストは 400 で拒否されます。全ツールを利用する場合も /x/all を明示してください。

認識される CSV エントリ（AI エージェント設定の「公開モジュール」と同じ識別子）:

エントリ意味
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 など）。
サブモジュール1 つのモジュールの一部のコントローラだけを公開する識別子（site_management_plugin）。アクセス範囲だけが変わり、ツール名は <mt> 指定時と同じです。

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

  • 更新系の操作は、操作ごとに個別のツールになります（追加 / 更新 / 削除など）
  • レコードが 1 件も無いモジュールでは、参照系のツールが表示されません（追加のツールのみが表示されます）

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

モジュール一覧（REST）​

スコープ指定（/x/...）なしのベース URL で利用できます（認証は必要です）。

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

レスポンス:

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

type は topics（topics レコード操作）、topics_group_admin（グループ定義管理）、controller（一般の管理モジュール）、service（サービスモデル）のいずれかです。各エントリにはモジュールの表示名（label）と説明（description）が含まれ、topics のエントリには選択可能なグループの一覧（groups）も含まれます。

MCP プロトコル​

HTTP POST + JSON-RPC 2.0。initialize で交渉するプロトコルバージョンは 2025-11-25 / 2025-06-18 / 2025-03-26 に対応しています。

サポートメソッド:

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

ツール名は {resource}-{verb} の形式です。リソースは操作対象のレコード種別を表し、モジュール名とは一致しないことがあります（例: site モジュールには kuroco_front、usage、const などのリソースが含まれます）。ハイフンはリソースと動詞の区切りとして 1 つだけ使われ、リソース名の中の区切りはアンダースコアのままです（topics_group-create）。

動詞操作例
-list一覧・検索topics-list
-getID 指定で 1 件取得topics-get
-create追加topics-create
-update更新（1 件、または ids / filter で複数件）topics-update
-delete削除（同上）topics-delete
-validate保存せず入力チェックのみ実行topics-validate
-importCSV や行データの取り込みtopics-import
-exportダウンロードtopics-export
その他の管理操作管理操作の名称がそのまま動詞になりますtopics-accept
サービスメソッド{Service}-{method}Email-send

固定名のツールが 2 つあります。topics-describe（コンテンツ定義の構造を返します）と files-create-upload（ファイルのアップロードを参照）です。

対象件数（1 件 / 複数）や実行方法（同期 / ジョブ）はツール名ではなく引数で指定します。このため一括処理は専用のツール名（bulk_delete など）を持ちません。{resource}-delete / {resource}-update では引数で対象（ids または filter）を選択し、ガードとして dry_run / expected_cnt を指定できます。ジョブ実行に対応するツールでは async 引数で同期実行とジョブ実行を切り替えます（{resource}-import など）。

実際のツール一覧はモジュールが公開するコントローラに依存します。スコープ 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}

ファイルのアップロード​

コンテンツの画像・ファイル項目に大きなファイルを設定する場合は、files-create-upload ツールでアップロード先を発行し、本文とは別にアップロードします。小さなファイルは data: URI としてそのまま値に渡すこともできます。

  1. files-create-upload を呼び出すと、不透明な参照（file_ref、kuroco-file: で始まる文字列）とアップロード先（upload.method = PUT、upload.url）が返ります。
  2. upload.url にファイルのバイト列を PUT します。upload.url が 307 を返す場合は、GET でリダイレクト先（Location）を解決してから、その URL に PUT してください。リダイレクトする URL 自体への PUT はエッジで 405 になります。
  3. topics-create / topics-update の画像・ファイル項目の値に file_ref を渡します（{"file_id": "kuroco-file:...", "desc": "キャプション"} の形式も利用できます）。

アップロード先は環境によって異なります。S3 の一時バケットが構成されている場合は S3 の presigned URL（短縮 URL の場合は上記の 307 解決が必要）、構成されていない場合は Kuroco の以下のエンドポイントです。参照はアカウントに紐づき、有効期限があります。

PUT /direct/rcms_api/mcp_upload/<token>
注記

files-create-upload は、コンテンツのレコード操作ツールを含むバンドルにのみ表示されます。/readonly のバンドルでは表示されません。

制限事項​

MCP クライアントは 1 つの指示を複数のツール呼び出しに展開し、それらを並列で送信することがあります。管理操作 1 件はレコード保存に加えて検索インデックス更新・キャッシュパージ・トリガー処理を伴うため、並列送信をそのまま受け付けると同一インスタンスで配信している公開サイトまで遅くなります。これを防ぐために、以下の上限が設けられています。

いずれの上限も認証方式（OAuth アクセストークン／管理画面のセッションクッキー）にかかわらず適用されるため、AIエージェントアシスト など管理画面内から Admin MCP を利用する機能も対象です。

書き込みリクエストのレート制限​

項目内容
上限2 秒あたり 8 リクエスト（サイト単位）
対象書き込み系ツールの tools/call。Admin API（/direct/rcms_api/admin_api/）の書き込みリクエストと共通の枠で数えます。
対象外読み取り系ツールの tools/call、および initialize / tools/list / ping などのメソッド。接続直後のツール一覧取得や参照系の呼び出しは、この書き込みレート制限では数えません（Kuroco 全体の同時接続数の制限は別途適用されます）。
超過時の応答HTTP 429 と Retry-After ヘッダ、および JSON-RPC エラー。エラーメッセージにも再試行可能になるまでの秒数が含まれます。
対処書き込みを並列化せず 1 件ずつ送信します。同種の更新をまとめる場合は、{mt}-delete / {mt}-update に ids または filter を指定して 1 回の呼び出しで処理します。
注意

判定は「その 2 秒間に受け付けた書き込みリクエスト数」で行われます。数件の書き込みを並列で送る程度であれば通りますが、9 件目以降は 429 になります（平均すると 1 秒あたり 4 リクエストが上限です）。429 を受け取ったクライアントは Retry-After に従って再試行してください（待ち時間は最大 2 秒です）。

一括操作の 1 リクエスト上限​

項目内容
同期実行1 回の呼び出しで 200 件まで
非同期実行（async=true でジョブとして登録）1 ジョブで 100,000 件まで
超過時エラーを返します。同期実行で 200 件を超える場合は async=true の指定、または呼び出しの分割が必要です。

CSV ファイルの取り込みも同じ件数で判定され、上限を超えるファイルは 1 行も取り込まずにエラーになります。

処理時間の通知​

1 回のツール呼び出しに 1,000ms を超える時間がかかった場合、ツール実行結果に処理時間と対処の指針が追記されます。エラーではありませんが、書き込みの並列送信を控える、取得する項目や件数を絞るなどの対処を検討してください。

ログ参照ツールの上限​

項目内容
参照可能な期間直近 12 時間（timestamp_start は必須で、12 時間より前を指定するとエラー）
呼び出し間隔管理ユーザー単位で 5 秒に 1 回

Admin CLI と Admin MCP の使い分け​

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

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

どちらの経路も課金対象

Admin API（/direct/rcms_api/admin_api/）と Admin MCP（/direct/rcms_api/admin_mcp/）へのリクエストは、通常の API リクエストと同様にリクエストごとの課金対象です。意図しない書き込みトラフィックを抑えるには、モジュールスコープ付き URL と /readonly の活用を推奨します。

Client CLI

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

MCP 動作改善フィードバック​

クライアント API MCP サーバと Admin MCP サーバの initialize レスポンス（instructions）には、AI クライアントが MCP ツール自体の不具合・改善要望を Kuroco 開発チームへ報告するための送信手順が含まれます。ツールの説明が分かりにくい、入力スキーマが実際の挙動と一致しない、想定外のエラーが発生した、といった問題を AI クライアントが作業中に検知した場合、Kuroco が用意した専用のフィードバック API へ報告します。報告は Kuroco 開発チームに届き、MCP の改善に利用されます。

報告に含まれる項目は次のとおりです。

項目内容
件名（必須）問題・要望の要約
詳細（必須）現在の挙動、期待する挙動、再現手順
対象 MCP ツール名例: topics-list
利用クライアント例: Claude Code
利用モデル例: claude-fable-5
メールアドレス返信を希望する場合のみ

instructions には、AI クライアントに対する次の制約が明記されています。

  • 報告を送信する前に、必ず報告内容をユーザーに提示して承認を得ること。サイレントに送信してはならない
  • メールアドレスは、ユーザーが返信を希望して共有に同意した場合のみ送信すること
  • それ以外のユーザーのデータや秘密情報を報告に含めないこと

有効/無効の切り替え​

デフォルトは有効です。次のいずれかの画面で切り替えられます。

  • [環境設定] -> [サイト管理]（/management/site/site_edit/）の「MCP動作改善フィードバック」チェックボックス
  • Admin MCP 設定画面（/management/rcms_api/admin_mcp_info/）の「MCP動作改善フィードバック」カードの切り替えボタン

無効にすると、両 MCP サーバの instructions からフィードバック送信手順が除外されます。

関連ドキュメント​

サポート

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

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