Kuroco Admin MCP

Kuroco Admin MCP Skill

概要

Kuroco Admin MCP は、Kuroco 管理画面の操作（admin_api と同等の管理操作）を MCP (Model Context Protocol) サーバーとして公開する機能。JSON-RPC 2.0 ベースで、 Claude Code / Claude Desktop / ChatGPT などの MCP クライアントから接続できる。

AI エージェントから Kuroco の管理操作を行う際の推奨機能。 標準の MCP プロトコルと OAuth 2.0 に準拠しており、追加ツールのインストール不要で主要な MCP クライアントから そのまま利用できる。

最大の特徴: ツールは DB に登録するのではなく、管理画面のコントローラーと サービスモデルが実行時に動的に MCP ツール化される。管理画面でできる操作は 原則そのまま MCP ツールとして利用できる。

公式リファレンス: MCP クライアント設定リファレンス 仕様は活発に更新されているため、接続手順の最終確認は公式ドキュメントを参照すること。 同梱の kuroco-docs スキルからも参照できる: ../kuroco-docs/docs/reference-mcp-ai.md 内の mcp-server（MCP サーバ）/ mcp-client-configuration（クライアント設定）の各ページ

類似機能との区別（混同注意）:

エンドポイント

POST https://<site_key>.g.kuroco.app/direct/rcms_api/admin_mcp/x/<module>[,<module>][/readonly]

重要なルール:

• エンドポイントのドメインは API ドメイン（<site_key>.g.kuroco.app）。 管理ドメイン （.g.kuroco-mng.app）は管理画面・Issuer URL 用であり、MCP エンドポイントには使わない。 URL は手で組み立てず、Admin MCP 情報ページに 表示される値をそのまま使うこと。
• /x/<スコープ> は必須。 bare の /direct/rcms_api/admin_mcp/ は 400 を返す （旧仕様の「スコープ省略＝全ツール」は廃止済み。全ツールは必ず /x/all）。
• ベースパスは末尾スラッシュ必須。 ディスパッチャURL（デフォルト audience）は /direct/rcms_api/admin_mcp/（スラッシュ込み）で、/direct/rcms_api/admin_mcp （スラッシュなし）は解決されない。スコープ付き URL（/x/all 等）は例示どおり 末尾スラッシュなしで書く。 OAuth の audience はトークン発行時の URL 表記と 厳密一致するため、登録後に URL 表記を変えない。
• モジュール識別子は小文字英数字とアンダースコアのみ（^[a-z][a-z0-9_]*$）。 カンマ区切りの順序に機能上の意味はないが、URL 表記は audience として扱われるため 一度登録した表記を固定すること。
• topics まわりは3つの識別子を使い分ける:
  • topics_group_<N> — グループNにスコープしたコンテンツ（レコード）の実操作
  • topics_group — グループ定義（TopicsGroup）自体のCRUD（topics_group-create / -list / -update / -delete）
  • topics 単独指定 — discovery専用（グループ制約なしの同等表現）。ツールの呼び出しは拒否されるため、 実操作には使えない。レコード操作は topics_group_<N>、グループ定義の操作は topics_group を指定する

認証

3 方式ある。Bearer トークンが提示された場合はセッションにフォールバックしない （RFC 6750 準拠。無効トークンは 401）。

方式1: OAuth 2.0 認可コードフロー（推奨）

管理画面に Admin MCP 用の OAuth 認可サーバー（Authorization Server） が 自動作成される（初回に Admin MCP (default) がシードされる）。

• Issuer URL: https://<管理ドメイン>/direct/login/oauth_idp/<idp_id>
  • 管理画面 [Admin MCP 情報ページ] または OAuth Authorization Server 編集画面に表示される
• CIMD（クライアント ID メタデータドキュメント / URL クライアント ID） を有効化すると、 クライアント側での client_id / secret の手動設定が不要になる
• Dynamic Client Registration (RFC 7591) は非対応。 CIMD を使わない場合、 クライアントは管理画面で手動登録する
• Protected Resource Metadata (RFC 9728) は認証不要で公開: GET /.well-known/oauth-protected-resource/direct/rcms_api/admin_mcp/
• CI／無人エージェントは client_credentials グラントを使う。CIMD クライアントでは 利用できないため手動登録が必要（認可サーバー・クライアント双方の「対応するグラントタイプ」に client_credentials を含め、クライアントのトークンエンドポイント認証方式は client_secret_basic / client_secret_post）。トークン要求時は resource パラメータ （RFC 8707）にスコープ付き URL を指定する。リフレッシュトークンは発行されないため、 対話的クライアントの常用には向かない（対話利用は authorization_code を使う）

方式2: 特権静的トークン

OAuth 導入前からの管理ツール向け方式。Authorization: Bearer <特権静的トークン> で接続。 スコープ制限はなく全権限（mcp:admin 相当）になるため、取り扱いに注意。

方式3: 管理セッション

管理画面内の UI（AI エージェント支援、ツールチェッカー等）からの呼び出し専用。 外部クライアントからは使用しない。

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

Admin MCP エンドポイントは管理画面の IP アドレス制限の対象外（送信元 IP が一定しない クラウド型 MCP クライアントに対応するため）。接続元を限定する場合は、専用の許可 IP リストを **[環境設定]→[管理画面] の「Admin MCPのアクセス制限(IPアドレス)」**で有効化する。

• 判定は認証より前。許可外 IP からはトークンの正否にかかわらず 403 （Access from this IP address is not allowed.）が返る
• 対象: Admin MCP エンドポイント（?MODE=tools 含む）とファイルアップロード （/direct/rcms_api/mcp_upload/）。Bearer・管理セッションの両経路に適用され、 管理画面内の AI エージェント機能にも適用される
• 対象外: ?MODE=protected_resource_metadata（RFC 9728 メタデータ配信）
• client_credentials によるトークン取得と発行済みトークンでの呼び出しは 「管理画面のアクセス制限(IPアドレス)」の対象外（効くのは Admin MCP 専用リストのみ）

OAuth スコープ（権限レベル）

Admin MCP 用認可サーバーの権限は個別スコープ選択ではなく単一レベル選択（4段階）。 レベルはスコープ文字列で識別すること（管理画面の日本語ラベルは似た語が並び紛らわしいため）。 whoami の permissions.connection.scope が返すのもこのスコープ文字列:

• mcp:tools.write は単独では選べず、mcp:tools.read とセットで付与される（読み取りは全モジュールに効く）
• auth.scopes には上表以外の値も混じる。 ツール一覧の取得に使われる mcp:tools.list が併せて付与されるため、whoami は例えば ["mcp:admin", "mcp:tools.list"] を返す。これは権限レベルではない。実効的な権限レベルの判定には auth.scopes ではなく permissions.connection.scope を見る
• mcp:tools.all の例外 — グループ（権限）と汎用Smartyバッチの作成・変更・削除／メンバーへのスーパーユーザーグループ付与／特権付き静的トークンの発行はできない（遅延実行や特権付き静的トークンには上限を安全に引き継げないため）
• mcp:admin はスーパーユーザーしか承認できない。それ以外のメンバーには同意画面で承認可能な最大レベルが提示され、そのレベルで発行される。スコープとして直接要求した場合は「mcp:tools.all を要求せよ」というメッセージで拒否される

管理画面のラベルで確認できるのは mcp:tools.all = 「全操作（委譲先メンバーの権限の範囲）」。

スコープは「上限（ceiling）」であって権限の付与ではない。 実効権限は メンバー自身の権限 ∩ スコープの上限。上限に含まれないモジュールは全操作が拒否される。 逆に、上限が広くてもメンバーに権限がなければ何もできない。

構築作業に必要なスコープ

サイト構築で必要なスコープは、どのモジュールに書き込むかで決まる:

API エンドポイントを作る時点で mcp:tools.write では足りない（rcms_api が mcp:tools.write の上限に含まれないため、全操作が拒否される）。コンテンツ定義の作成までは mcp:tools.write で進めるので、エンドポイント作成の手前で初めて失敗する。着手前に確認すること。

一連の構築を通しで行うなら mcp:tools.all、上表の mcp:admin 行に該当する作業を 含めるなら mcp:admin が必要。

リソース単位のスコープも存在する:

• mcp:module.<mt> — 特定モジュール（例: mcp:module.member）、mcp:module.* で全モジュール
• mcp:topics_group.<N> — 特定コンテンツ定義、mcp:topics_group.* で全定義

enforce-if-present 方式: スコープは OAuth トークンにスコープが付与されている場合のみ 強制される。スコープなしのトークン（旧来の管理エージェントトークン・特権静的トークン）は 制限されない。「スコープを設定しない＝制限なし」である点をユーザーに必ず伝えること。

特権メタツール:

• kuroco_front-generate_deploy_token は mcp:admin スコープ必須
• rcms_api-generate_token は rcms_api/update 権限が必要（＝mcp:tools.all 以上）。 さらに token_type: "privileged_static" は厳密な mcp:admin が必須で、 mcp:tools.all でも発行できない（発行されるトークンが接続側の上限を持たない 常設の資格情報になるため）。token_type: "static" にはこの追加制約はない

設定箇所: 権限レベル・リソーススコープは OAuth Authorization Server 編集画面 （/management/external/memberregist_sso_oauth_idp_edit/）で設定する。設定値と Issuer URL は Admin MCP 情報ページでも確認できる。

クライアント接続

接続手順の正本は kuroco-docs

クライアント別の対応状況（CIMD / 手動クライアント登録 / ヘッダー認証）と設定手順は ../kuroco-docs/docs/reference-mcp-ai.md の mcp-client-configuration ページが正本。 Claude Code / Claude（Web・Desktop・Mobile）/ ChatGPT（Developer mode）/ Codex CLI / Cursor / Slackbot / GitHub Copilot / カスタム実装 の対応表と手順が揃っている。

このスキルは接続手順を複製しない。 docs は /sync-docs で公式サイトから再生成されるため、 複製すると再同期のたびに片方だけ更新されて乖離する。ここに置くのは、docs に無い 「Admin MCP 固有の URL の組み立て方」と「エージェントとしての振る舞い」だけ。

Admin MCP 固有: URL がスコープであり、リソース識別子

docs の手順の URL 部分を、Admin MCP のスコープ付き URL に置き換えて使う。

https://<site_key>.g.kuroco.app/direct/rcms_api/admin_mcp/x/all
https://<site_key>.g.kuroco.app/direct/rcms_api/admin_mcp/x/topics_group_5
https://<site_key>.g.kuroco.app/direct/rcms_api/admin_mcp/x/topics_group_1,member/readonly

共通の前提:

• OAuth 認可フローは Kuroco 管理画面のログイン・同意を経由するため、接続者には 対象サイトの管理メンバーアカウントが必要
• URL（スコープ）を変更した場合は再認可が必須（audience が URL 表記と厳密一致するため）。 クライアント UI で URL を編集できない場合は、コネクタを削除して新規追加する
• チーム利用や権限分離が必要な場合は、既定の Admin MCP (default) を変更せず 用途ごとに専用の認可サーバーを作成する運用を推奨

CLI での例（OAuth の登録方式そのものは docs に従う）:

# Claude Code
claude mcp add --transport http kuroco https://<site_key>.g.kuroco.app/direct/rcms_api/admin_mcp/x/all
claude mcp login kuroco

# Codex CLI
codex mcp add kuroco --url https://<site_key>.g.kuroco.app/direct/rcms_api/admin_mcp/x/all
codex mcp login kuroco

接続ごとに区別できるサーバー名を付ける（kuroco-blog など）。画面から設定するクライアント （Claude Web・Desktop・Mobile、ChatGPT）は、MCP URL の入力欄に上記の URL を入れる。

特権静的トークンを使う場合（OAuth を経由しない。全権限になるため取り扱い注意 → 方式2: 特権静的トークン）:

claude mcp add --transport http kuroco \
  https://<site_key>.g.kuroco.app/direct/rcms_api/admin_mcp/x/all \
  --header "Authorization: Bearer <特権静的トークン>"

Admin MCP のヘッダー認証は Authorization: Bearer。コンテンツ API MCP の X-RCMS-API-ACCESS-TOKEN とは別なので、docs のヘッダー認証手順をそのまま流用しない。

接続時の振る舞い

• 利用クライアントを識別してから手順を選ぶ。 全クライアントで使える自動判定があると 仮定しない。システムから示された情報かユーザーの説明で判断し、それが無く手順の選択に 影響する場合だけ一度確認する
• 異なるクライアントの手順を混在させない。 CLI 利用者に画面操作を求めたり、 デスクトップ利用者に理由なく CLI コマンドを求めたりしない
• 手動クライアント登録は管理画面の永続的な設定変更。 実行前にユーザーの承認を得る。 CIMD が使えるかどうかは docs の対応表で確認し、 「エラーが出た」以外の理由で手動登録へ倒さない
• Kuroco は RFC 7591 の DCR を実装していない。 DCR しか持たないクライアント （Cursor 等）は手動クライアント登録が唯一の経路
• サイト全体に影響する設定変更はエージェントが確定しない。 認可サーバーの設定変更や CIMD の有効化が必要な場合は、必要性を説明してユーザー自身に操作してもらう
• 接続後は新しいタスクを開始して whoami を実行し、接続先ホスト・実効スコープ・ 読み書き権限・サイト固有の上限を確認してから作業に入る（whoami による事前確認）
• 作業に必要な最小スコープの URL を選ぶ（構築作業に必要なスコープ）

  • 担当者の責務で決める:

    担当者の責務	スコープ
    構築担当	mcp:admin
    改修担当	必要に応じて mcp:admin も許可
    保守・運用担当	最小権限
    その他	最小権限

ツールの命名規則と使い方

tools/list が返すツール名は動的に生成される。コントローラー名の語尾と MODE が 動詞に畳み込まれた {resource}-{verb} 形式（1 コントローラーアクション = 1 ツール）:

ハイフンは resource と verb を区切る1つだけ。 {resource} はコントローラー名から _api と末尾1語（_list / _edit / _upload）を除いたもので、モジュールディレクトリ名ではない （topics_group_edit_api → topics_group）。リソース名に含まれるアンダースコアは ハイフンに置き換わらない。

正確なツール名と入力スキーマは必ず tools/list で確認する（名前を推測して呼ばない）。

• topics_group_<N> スコープで接続した場合も、ツール名は汎用の topics-{verb} のまま変わらない。 許可グループは各ツールの topics_group_id 引数の enum として制約され、許可外グループの指定は拒否される
• スコープ由来の拒否は実行時に判定される。topics_group_id の enum に載っていない ID を 指定して拒否された場合は、スコープ不足なのか ID が存在しないのかを読み取りツールで切り分ける

代表的な引数（正確な仕様は各ツールの inputSchema が正）:

• list 系（{mt}-list）: filter（Kuroco DSL）・order_query（ソート）・cnt / pageID（ページング）・ columns（カラム絞り込み）。topics はさらに topics_keyword / vector_query（検索）が使える。 単一レコードを ID で取るときは {mt}-get を優先する
• update / delete（単一レコード系）: ID（topics_id 等）が必須。topics 系ツールは動詞によらず topics_group_id を渡す

利用フロー:

0. whoami で実効権限を確認する（下記）。特に構築作業の着手前と、破壊的操作の前
1. tools/list で利用可能ツールを確認（または REST の ?MODE=tools でモジュール一覧）
2. 読み取りツールで現状確認（親子関係: Topics には topics_group_id、Member には group_id が必要。 親の ID は topics_group-list 等で先に解決する）
   • list 系ツールはデフォルトで全カラムを返す。columns 引数で必要なカラムだけに絞る
3. 書き込みツールの inputSchema を確認してから実行

   • topics の拡張項目（ext_col）は inputSchema に列挙されない。 topics-describe で 対象グループのフィールド定義を確認する:

     // tool: topics-describe（topics_group_id は必須）
     { "topics_group_id": 5 }
     

   • update 系ツールは部分更新: 送信しなかったフィールドは変更されず既存値が保持される。 一部のフィールドだけ変えたい場合は、ID と変更するフィールドのみを送る（既存値の再送は不要）。 大きなテキストカラムは行単位でも部分更新できる（下記「部分更新」）

4. INSERT / UPDATE / DELETE は実行前にユーザーに確認すること
5. 複数レコードの書き込みは並列せず 1 件ずつ実行する。 各書き込みはサーバー側で 検索インデックス再構築・キャッシュ削除・トリガー処理を伴い、並列書き込みは レート制限（HTTP 429）の対象になる。複数件は同じ update / delete ツールの ids / filter （＋set）で 1 回の呼び出しにまとめる（dry_run → expected_cnt の順で安全に）
6. 成功レスポンスにも errors 配列が含まれることがある。 常に確認する

lightweight_mode の注意: topics の create/update で lightweight_mode: true を渡すと 書き込みが大幅に軽くなるが、後追いバッチで反映されるのは検索インデックスと ベクトル埋め込みのみ。トリガー・外部通知（FCM/メール）・タグ集計はスキップされ 恒久的に実行されない。既定動作を変えるため、使用はユーザー確認のうえで。

ツールが見えない場合のチェックリスト:

• 対象テーブルが 0 件のモジュールは読み取りツールが除外される（空モジュールは INSERT のみ表示）
• URL スコープ（/x/<module>）にそのモジュールが含まれているか
• readonly 付き URL では書き込みツールが出ない
• OAuth スコープ（mcp:module.* / mcp:topics_group.*）で絞られていないか
• コンテンツ操作は topics ではなく topics_group_<N> を指定しているか

部分更新

Admin MCP の update 系ツールは 2 段階の部分更新に対応する。どちらも「変えない部分を 送らなくて済む」ための仕組みで、送受信量とコンテキスト消費を抑えられる。

フィールド単位（すべての update 系ツール）

送信しなかったフィールドは既存値が保持される。ID と変更するフィールドだけを送る。 既存値を読み直して再送する必要はない。

行単位（patch.<カラム>）

CSS・JS・Smarty テンプレートのように長くなるカラムは、行範囲を指定して一部だけを 書き換えられる。カラム全体を送る代わりに、同じ update ツールへ patch.<カラム名> を渡す。

patch. は部分更新の予約プレフィックス。対応カラムが増えても専用ツールは追加されず、 そのリソースの -update に引数が 1 つ増えるだけなので、ツール一覧は膨らまない。

対応カラム（tools/list の inputSchema が正本）:

手順:

1. 読み取りツール（custom_function-get / topics_group-get）で対象カラムの <カラム名>_hash を取得する（保存内容の SHA-256）
2. その値を base_hash に渡して update を呼ぶ

// tool: topics_group-update
{
  "topics_group_id": 5,
  "patch.custom_css": {
    "base_hash": "<topics_group-get が返した custom_css_hash>",
    "start_line": 2,           // 1始まり
    "delete_line_count": 1,    // 0 なら挿入（replacement は空にできない）
    "replacement": "/* 差し替え */"   // 空文字なら該当行を削除
  }
}

• base_hash は楽観ロック。読み取り後に他の誰かがそのカラムを変更していれば 「changed since it was read」で拒否される。取り直して再試行する
• 更新レスポンスにも保存後の <カラム名>_hash が入る。続けてパッチする場合は 読み直さずその値を使う
• カラム名そのものと patch.<カラム名> は併用不可（同時指定はエラー）。 カラム名を送れば従来どおり全文置換になる
• 改行コードは元の内容（内容に改行が無ければ replacement）に合わせて正規化される
• 1 回の呼び出しで複数カラムを同時にパッチできる（それぞれに base_hash が必要）

ハッシュは保存内容から算出される。 サーバー側で保存時に値を正規化するカラムがあり （例: search_template_* は空だと既定テンプレート全文に置換、custom_css / custom_js は エディタのプレースホルダと一致すると空で保存）、送った値と保存された値は一致しないことがある。 だから base_hash は必ず読み取りツールの <カラム名>_hash を使い、自分で ハッシュを計算しない。

whoami による事前確認

whoami はすべてのスコープ付きエンドポイントに常設されるメタツール（readonly バンドルにも出る）。 引数なしで呼べ、接続の実効コンテキストを返す。

実際に呼べるのは permissions.granted ∩ permissions.connection。 片方だけを見て判断しない。

拡張項目のキー命名（site.topics_ext_key_format）

topics の拡張項目のキー名はサイト設定によって2通りに分かれる。whoami はそのまま使える命名文字列を返す:

• キー名を推測しない。 命名はサイト単位で決まるので、topics の読み書きの前に whoami で確認する
• 返却値は定数名ではなく命名そのものなので、<n> / <nn> を項目番号に置き換えてそのまま使える
• グループ単位の正は topics-describe。 実際のフィールド定義（どの番号がどの項目か、ext_slug が設定されているか）はこちらで確認する。topics_ext_key_format はサイト全体の命名規則を先に知るためのもの
• ext_slug が設定されている項目は、フロントAPIではスラッグがキーになるためこの分岐の影響を受けない
• 古いサイトでは topics_ext_key_format が返らないことがある。 その場合は topics-describe の結果を正として扱う

コンテンツ構造の上限（site.limits）

site.limits は、コンテンツ構造に関わる4つの上限を {current, max} の形で返す。current はこのサイトの現在の設定値、max はシステム上引き上げられる上限。 どちらも推測しない——設計・作成の前に必ずここで確認する。

currentがmax未満なら、admin_setting-updateツールで引き上げられる（tools/listに存在するか確認してから使う。まだ見えない場合は未対応のサーバーなので、管理画面での引き上げ手順を案内する）。「拡張項目が99個までしか作れない」といった相談を受けたら、まずこのlimitsを見て、レガシー形式（max=99）なのかJSONB形式（max=999）なのか、現在値が上限に達しているだけなのかを切り分ける。

呼ぶべきタイミング:

1. セッション開始時 — 接続先サイトが意図したものか、どのメンバーとして操作するかを確認
2. 構築作業の着手前 — connection.scope が mcp:tools.all または mcp:admin かを確認する。 「読み書き」で始めるとコンテンツ定義までは成功し、エンドポイント作成で初めて失敗するため、 途中まで作られた状態が残る。不足していれば available_scopes を提示して再認可を依頼する
3. コンテンツ構造の設計前 — site.limits（上記）で拡張項目・フィールドグループ・カテゴリ・会員拡張項目の上限を確認する。/kuroco-content-structure はこの値をもとに分割・圧縮を判断する
4. 破壊的操作の前 — 対象サイトと権限を再確認

スコープが不足している場合、推測でツールを呼んで失敗を確かめない。 available_scopes を添えて、必要なレベルでの再認可をユーザーに依頼する。

ファイルアップロード

バイナリを直接 MCP に送らず、ステージング → 参照渡しの 2 段階方式:

1. files-create_temp_upload_url ツールを呼ぶと、file_id と S3 プリサインド PUT の presigned_url（および presigned_short_url）が発行される。file_size（バイト数）と ext（拡張子）の宣言が必須:

   // tool: files-create_temp_upload_url
   { "file_size": 1048576, "ext": "pdf" }
   

2. 発行された URL にファイル本体（生バイト）を PUT する（presigned_short_url が 307 を返す場合は GET で Location を解決してから、その URL に PUT する）

3. topics-create / topics-update のファイル/画像型フィールドの値として file_id を渡して消費する。 値の形は文字列 "files/temp/..."、またはキャプション付きの {"file_id": "files/temp/...", "desc": "キャプション"}

ファイルマネージャーへのアップロード（file_manager-upload）

topics の項目ではなくファイルマネージャーのツリー（files/user/・files/ltd/・クラウドストレージ）に置く場合は file_manager-upload を使う。

// 16MB まで: data URI をそのまま渡す
{ "storage": "kurocofiles_public", "directory": "docs/2026", "file": "data:application/pdf;base64,...", "file_name": "report.pdf" }

// それ以上: files-create_temp_upload_url で PUT した file_id を渡す
{ "storage": "cloud_public", "directory": "videos", "file": "files/temp/kuroco/<site>/<uuid>.mp4", "file_name": "intro.mp4" }

• file_name が保存名と拡張子を決める。拡張子はサイトのアップロード許可リストにあるもの（php 等の実行系は不可）で、内容と一致していること（HTML/SVG/JS の中身を画像拡張子で置くなど、偽装は拒否される）。フォルダごとの拡張子制限も適用される
• directory は file_manager-list が返す path と同じ相対パスで、途中のフォルダは自動作成される（フォルダ作成ツールは無い）
• 同名ファイルは上書き（ツールは destructive 扱い）。allow_overwrite: false で拒否させられる
• クラウドストレージ（cloud_public / cloud_private）宛ての file_id はストレージ側でコピーされ、Kuroco のサーバーを経由しない。files-create_temp_upload_url に storage: "S3" を付けて発行した file_id ならサイズ上限なし
• ローカルストレージ（kurocofiles_*）宛ての file_id は 80MB まで。超える場合はクラウドストレージに置く
• 応答の path は file_manager-list / file_manager-delete に渡す値、content_field_value は「ファイル（ファイルマネージャーから）」型の項目に書き込む値

承認ゲートとの順序: 書き込み前のユーザー承認を得てから URL を発行し、 「発行 → PUT → 消費」を一続きで行うこと（承認待ちの間に発行すると期限切れのリスク）。

制約:

• プリサインド URL の有効期限は 10 分。「発行 → アップロード → 消費」を 10 分以内に完了させる
• サイズ上限は file_size の宣言値で検査され、消費時にも再検査される（既定 100MB）
• storage: "S3" を付けるとサイトの S3 バケットの files/temp/ に直接置かれる（GCS サイトでは不可）
• 小さいファイル（16MB まで）はインライン data URI でも受理される

管理画面: Admin MCP 情報ページ

/management/rcms_api/admin_mcp_info/ に Admin MCP の設定情報が集約されている:

• エンドポイント URL 一覧（x/all、x/all/readonly、モジュール指定の例）
• OAuth 認可サーバー一覧と Issuer URL
• 接続クライアント一覧（client_id のみ表示。secret は表示されない）
• Admin MCP を利用する AI エージェント一覧（公開モジュール / 読み取り専用設定）
• ツールチェッカー（利用可能ツールの確認 UI）

ユーザーに Issuer URL やエンドポイントを案内するときは、まずこのページを参照させる。

トラブルシューティング

権限エラーの切り分け

上表の症状マッチだけで原因を確定しない。 「書き込みが権限エラーになった」という報告は、 スコープ不足以外の原因でも同じように見える。ユーザーが「スコープ不足だと思う」と 自己診断していても、まず事実を確認する。

1. HTTPステータスを確認する。 401 は認証（トークン無効・失効）、403 は認可 （スコープ・権限・IP制限）。ここを取り違えると以降の切り分けが全部ずれる
2. whoami を呼ぶ（推測でツールを呼んで失敗を再現しない）
3. 返ってきた事実で分岐する:

whoami が十分な権限を示したのに「再認可してください」と案内してはいけない。 確認した事実と矛盾する対処を提示すると、ユーザーは解決しない作業に時間を使う。

セキュリティ注意事項

• 公開エンドポイント（セキュリティ=なし）での運用は非推奨。 特に書き込みを 認証なしで公開しない
• 特権静的トークンはスコープ制限が効かない（全権限）。可能な限り OAuth ＋ 適切な権限レベルを使う
• 読み取り用途には x/all/readonly や「読み取り専用」権限レベルで最小権限にする
• client_secret・トークン値をログや会話に出力しない
• Admin MCP のリクエストは管理ログに記録され、Admin API 同様リクエスト単位で課金対象

他スキルとの連携

使い分けの目安: AI エージェントからの管理操作は Admin MCP（本スキル）が推奨。 Claude Desktop / claude.ai / ChatGPT / Claude Code いずれからも標準の MCP 接続で利用できる。