MCP サーバーを有効にする(設定項目の一覧)


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

MCP サーバーは既定で無効です。このページの手順で有効にします。設定はブログごとで、ルートブログで設定すると子ブログにも効き、子ブログで上書きできます。

設定画面を開く

MCP サーバーの設定は、コンフィグの「REST API設定」の画面にあります。ブログの管理者のユーザーで操作します。

管理画面の「コンフィグ」で、ブログが使っているコンフィグセットの「REST API設定」を開きます(コンフィグセットを使っていない場合は「このブログのコンフィグ(レガシー設定)」の「REST API設定」)。

使っていないコンフィグを編集しないでください

コンフィグセットを設定しているブログでは、「このブログのコンフィグ(レガシー設定)」は使われません。そちらで「MCP サーバーを利用する」をオンにしても、MCP サーバーは有効になりません。画面の上部の「コンフィグセット」の表示で、編集しているコンフィグを確かめてください。

MCP サーバーを有効にする手順

  1. 「REST API設定」の「MCP サーバー」の「MCP サーバーを利用する」にチェックを入れます。

  2. 「MCP で許可する操作」を選びます。AI に読ませるだけなら「読み取りのみ(デフォルト)」、エントリーの作成・更新もさせるなら「作成・更新まで(削除はできない)」にします。

  3. 「ツールの出し方」を選びます。ふつうは「まとめて(compact。デフォルト)」のままにします。

  4. ブラウザ上のアプリから接続するときだけ「許可する Origin」を、接続元を絞るときは「接続元 IP アドレス」(CIDR 表記)を設定します。

  5. 「REST API」の「API・MCP を使える権限」に、AI が使うユーザーの権限種別が含まれているかを確かめます(既定は管理者・編集者・投稿者)。

  6. 保存します。

「REST API設定」の「MCP サーバー」の節
「REST API設定」の「MCP サーバー」の節

有効になったかは、トークンを付けずに MCP サーバーへ POST して確かめられます。有効なら 401、無効なら 404 が返ります。

curl -i -X POST https://example.com/mcp/ \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

有効なときの応答の例です(OAuth 認可サーバーが有効なときは、WWW-Authenticate に resource_metadata が付きます)。

HTTP/2 401
content-type: application/problem+json; charset=utf-8
cache-control: no-store
www-authenticate: Bearer realm="a-blog cms", scope="read write", resource_metadata="https://example.com/.well-known/oauth-protected-resource/mcp/"

{"type":"https://developer.a-blogcms.jp/rest-api/problems/missing-token","title":"認証情報がありません。","status":401,"instance":"/mcp/","code":"missing_token"}

この確認は監査ログに「MCP の認証に失敗しました」(レベル「注意」)として 1 件残ります。

設定項目(MCP サーバー)

「REST API設定」の画面の「MCP サーバー」の見出しにある項目です。設定キーは、コンフィグのエクスポートや private/config.system.yaml で使う名前です。

項目(画面の名前)

設定キー

既定値

説明・入力例

MCP サーバー有効化(MCP サーバーを利用する)

mcp_enable

off

on で MCP サーバー(/mcp/)を公開します。off のとき、MCP サーバーの URL は 404 になります。REST API の有効・無効とは独立しています。

MCP で許可する操作

mcp_access_level

read

MCP からできる操作の上限です。read(読み取りのみ)・write(作成・更新まで)・destructive(削除を含むすべて)。不正な値は read として扱います。下の「MCP で許可する操作」を参照。

ツールの出し方

mcp_tool_mode

compact

compact(まとめて)か full(1 機能 1 ツール)。接続時のヘッダー X-Acms-Mcp-Tools があれば、そちらを優先します(MCP のツールの使い方(compact と full))。

許可する Origin

mcp_allowed_origins

空

ブラウザ上のアプリから接続するときに許可する Origin です。例: https://app.example.com。スキーム・ホスト・ポートまで一致するものだけを受け付けます(大文字・小文字と末尾の / は区別しません)。空のときは、Origin ヘッダーの付いたリクエストをすべて 403 にします。Claude Code などブラウザ以外のクライアントは Origin を送らないため、空のままで使えます。

接続元 IP アドレス

mcp_restriction_address

空

MCP サーバーに接続できる IP アドレスを CIDR 表記で制限します。例: 192.168.99.10/32、192.168.100.0/24。空のときは、REST API の「接続元 IP アドレス」(rest_api_restriction_address)を使います。

MCP にも効くほかの設定

次の設定は REST API と MCP で共通です。「REST API設定」の画面の「REST API」の見出しにあります。

項目(画面の名前)

設定キー

既定値

MCP への効き方

REST API の外部からの利用(外部からの REST API の利用を許可する)

rest_api_enable

off

MCP サーバーには影響しません。オフのままでも MCP は使えます。

API・MCP を使える権限

rest_api_allowed_auth

管理者・編集者・投稿者

チェックの無い権限種別のユーザーのトークンは、MCP でも 403(api_access_not_allowed)になります。エンタープライズライセンスでロールを使っているユーザーには、ロールの「API・MCP の接続」が使われます。

接続元 IP アドレス

rest_api_restriction_address

空

MCP の「接続元 IP アドレス」が空のときだけ、MCP にも使います。

リクエスト上限

rest_api_rate_limit_per_minute

300

トークンごとの 1 分あたりの上限です。超えると 429(rate_limited)になります。

匿名のリクエスト上限

rest_api_anonymous_rate_limit_per_minute

60

トークンを使わないリクエストの上限です。MCP は常にトークンで認証するため、MCP のツールの呼び出しには関係しません。

管理画面からのリクエスト上限

rest_api_session_rate_limit_per_minute

300

ログイン中のブラウザからの呼び出しの上限です。MCP には関係しません。

認証失敗の上限

rest_api_auth_failure_limit_per_minute

10

接続元 IP アドレスごとの 1 分あたりの認証の失敗の上限です。達すると 10 分間 429 になります。トークンを貼り間違えたまま試し続けると、正しいトークンでも 10 分間つながりません。

削除などの操作の上限

rest_api_destructive_limit_per_hour

60

削除などの操作の、トークンごとの 1 時間あたりの上限です。0 は上限なしです。MCP の削除にも効きます。

(画面にはありません)

rest_api_max_body_size

2097152

MCP のリクエストの本文の上限(バイト)です。超えると 413(payload_too_large)になります。

画面に無い設定は private/config.system.yaml に書きます。

# private/config.system.yaml(画面に無い設定を変えるときだけ書く)
rest_api_max_body_size: 4194304

新しい接続(OAuth でアプリを接続した・API トークンを発行した)を本人へ知らせるメールは、コンフィグの「メール設定」の「API の接続の通知」で設定します。

項目(画面の名前)

設定キー

既定値

説明・入力例

通知(新しい接続をメールで知らせる)

rest_api_connection_notify

on

OAuth でアプリを接続したときと、API トークンを発行したときに、本人へメールで知らせます。

From

mail_rest_api_connection_from

info@example.com

差出人です。既定のままでは届かないことが多いため、サイトのアドレスに変えます。

To

rest_api_connection_notify_to

空

本人のほかにも知らせる宛先です。カンマ区切りで複数指定できます。例: security@example.com, admin@example.com

件名テンプレート

mail_rest_api_connection_tpl_subject

mail/rest-api-connection/subject.txt

メールの件名のテンプレートの場所です。

本文テンプレート(TEXT)

mail_rest_api_connection_tpl_body

mail/rest-api-connection/body.txt

テキストの本文のテンプレートの場所です。

本文テンプレート(HTML)

mail_rest_api_connection_tpl_body_html

mail/rest-api-connection/body.html

HTML の本文のテンプレートの場所です。

MCP で許可する操作

トークンのスコープや OAuth の同意とは別に、サイトの管理者が「MCP からできる操作の上限」をブログごとに決めます。プロンプトインジェクション・同意の誤り・トークンの漏えいがあっても、MCP からの被害をこの上限で抑えるためです。MCP サーバーは削除の前に人へ確認を求められないため、削除を許すかどうかはここで決めます。

画面の選択肢

値

MCP からできること

読み取りのみ(デフォルト)

read

読み取りだけ

作成・更新まで(削除はできない)

write

読み取り・作成・更新。削除と、削除に準じる影響の大きい変更はできません

削除を含むすべての操作

destructive

削除を含むすべての操作

  • 操作の種類は HTTP のメソッドで決まります。GET は読み取り、POST・PUT・PATCH は作成・更新、DELETE は削除です。ルートが「影響の大きい変更」と宣言したものは、POST などでも削除と同じ扱いです。

  • 上限を超える操作のツールは、ツールの一覧にも acms_search の結果にも出ません。名前を指定して呼んでも実行されず、次の 403(forbidden)の結果になります: 「この操作(write)は、サイトの設定「MCP で許可する操作」で止められています(今の上限: read)。必要なら、サイトの管理者に設定の変更を依頼してください。」

  • 「作成・更新まで」以下では、エントリーをゴミ箱へ移す更新(本文の status を trash にする更新)も、削除と同じく止まります。

  • トークンのスコープとこの上限は独立して判定し、両方を満たす操作だけを実行します。上限を広げても、トークンに無いスコープの操作はできません。

  • REST API(/rest-api/)には掛かりません。

  • 今の上限は、acms_site_overview の結果の mcp(access_level と、呼べる操作の種類の allowed_kinds)で確かめられます。

URL の区切り(mcp)を変える

mcp が既存のブログ・カテゴリー・エントリーのコードと重なる場合は、config.server.php で区切りを変えます。REST_API_SEGMENT・MCP_SEGMENT・OAUTH_SEGMENT は互いに同じ値にできません。書かなければ rest-api・mcp・oauth になります。

<?php
// config.server.php(例: mcp の区切りを ai-mcp に変える)
define('REST_API_SEGMENT', 'rest-api');
define('MCP_SEGMENT', 'ai-mcp');
define('OAUTH_SEGMENT', 'oauth');

Apache で同梱の .htaccess を使っている場合は、「最後にスラッシュをつける」規則の除外も同じ値に書き換えます。書き換えないと、末尾に / の無い URL への POST が 301 になり、本文が失われます。

# .htaccess の「最後にスラッシュをつける」規則(mcp を ai-mcp に書き換えた例)
RewriteCond %{ENV:has_encoded_query} !1
RewriteCond %{REQUEST_URI} !(^|/)(rest-api|ai-mcp|oauth)(/|$)
RewriteCond %{REQUEST_URI} !^/\.well-known/(oauth-authorization-server|openid-configuration|oauth-protected-resource)(/|$)
RewriteCond %{REQUEST_URI} !/$
RewriteCond %{REQUEST_URI} !\.[^/\.]+$
RewriteRule ^.+[^/]$ %{REQUEST_SCHEME}://%{HTTP_HOST}%{REQUEST_URI}/ [R=301,L]

.htaccess のほかの確認点は OAuth のメタデータの URL と .htaccess を参照してください。

よくある質問・つまずき

症状

原因と確かめ方

保存したのに MCP サーバーの URL が 404 のまま

使っていないコンフィグ(コンフィグセットを使うブログの「このブログのコンフィグ(レガシー設定)」など)を編集していないか、画面の上部の「コンフィグセット」の表示で確かめます。子ブログの URL で接続している場合は、子ブログの設定で無効になっていないかを確かめます。

書き込みのツールが出ない・forbidden の結果になる

「MCP で許可する操作」が「読み取りのみ」です。トークンのスコープだけでは書き込めません。acms_site_overview の mcp.access_level で今の値を確かめます。

設定を変えたのに AI のツールの一覧が変わらない

クライアントがツールの一覧を覚えています。Claude Code なら /mcp から再接続するか、Claude Code を起動し直します。プロトコルのバージョン 2026-07-28 で接続したクライアントには、ツールの一覧を 60 秒まで使い回してよいと伝えています。

403(api_access_not_allowed)

「API・MCP を使える権限」に、トークンのユーザーの権限種別が入っていません(ロールを使うユーザーは、ロールの「API・MCP の接続」)。

403(ip_restricted)

接続元 IP アドレスが「接続元 IP アドレス」の範囲の外です。MCP の欄が空なら、REST API の欄の値が使われていることに注意します。

403(forbidden)がすぐに返る(ツールを呼ぶ前)

リクエストに Origin ヘッダーがあり、「許可する Origin」に入っていません。監査ログに「MCP の要求を、許可していない Origin のため拒否しました」が残ります。

429(rate_limited)

リクエスト上限・認証失敗の上限・削除などの操作の上限のどれかに達しています。認証失敗の上限は 10 分間続きます。