OAuth で MCP サーバーに接続する
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
a-blog cms は OAuth 2.1 の認可サーバーを本体に内蔵しています。別の認証サーバーは要りません。OAuth を有効にしても、API トークン(アプリパスワード)による認証はそのまま使えます。
OAuth を使う場面
API トークン | OAuth | |
|---|---|---|
トークンの用意 | ユーザーが管理画面で発行し、クライアントに貼る | クライアントが接続のときに、ブラウザでユーザーの許可を得て自動で受け取る |
有効期間 | 発行のときに選ぶ(30 日・90 日・1 年など) | アクセストークンは既定 1 時間。リフレッシュトークンで自動で更新(既定 30 日) |
使える先 | MCP サーバーと REST API の両方 | 許可したときの接続先(MCP サーバーか REST API)とブログだけ |
失効 | 「API トークン」の画面 | 「接続済みアプリ」・「OAuth の接続」の画面 |
向いているクライアント | Claude Code・Cursor など、ヘッダーを設定できるもの | claude.ai・Claude Desktop のコネクタ、Claude Code(ドメインの直下のブログ)など |
OAuth 認可サーバーを有効にする
ルートブログの「REST API設定」(開き方は MCP サーバーを有効にする(設定項目の一覧))で、「MCP サーバーを利用する」がオンであることを確かめます。OAuth で接続できるのは、有効になっている入口だけです。
「OAuth 認可サーバー」の「OAuth 認可サーバーを利用する」にチェックを入れて保存します。ほかの項目は、まずは既定値のままにします。接続できるアプリを claude.ai などに絞るときは「CIMD の許可ホスト」、アプリの自己登録を止めるときは「動的クライアント登録(DCR)」を変えます。
認可サーバーのメタデータが返るかを確かめます:
curl https://example.com/.well-known/oauth-authorization-server(パスのあるブログは OAuth のメタデータの URL と .htaccess の URL)。JSON が返れば有効です。
項目(画面の名前) | 設定キー | 既定値 | 説明・入力例 |
|---|---|---|---|
OAuth 認可サーバー有効化(OAuth 認可サーバーを利用する) |
|
| OAuth 認可サーバー( |
CIMD の受け入れ(URL で示されたアプリの情報で自動登録する(CIMD)) |
|
| アプリの識別子(https の URL)に置かれた情報を取得して、アプリを自動で登録します。ルートブログの設定だけが使われます。 |
CIMD の許可ホスト |
| 空 | CIMD のアプリの識別子に使えるホスト名を、完全一致で制限します。例: |
動的クライアント登録(DCR)(動的クライアント登録(DCR)を受け入れる) |
|
| アプリが自分で登録できるようにします。登録だけでは権限を与えず、利用には利用者の許可が要ります。ルートブログの設定だけが使われます。 |
登録の回数制限 |
|
| 動的登録の、接続元 IP アドレスごとの 1 時間あたりの上限です。超えると 429 を返します。 |
トークン発行の失敗の上限 |
|
| トークンの発行・取り消しの失敗の、接続元 IP アドレスごとの 1 分あたりの上限です。達すると 10 分間 429 を返します。 |
アクセストークンの有効期間 |
|
| 秒で指定します。300〜86400 の範囲に丸めます。 |
リフレッシュトークンの有効期間 |
|
| 秒で指定します。使うたびに新しくなります。86400〜7776000 の範囲に丸めます。 |
デフォルトのスコープ |
|
| クライアントがスコープを指定しないときの値で、確認の画面の初期値にもなります。スペース区切りで指定します。空のときは |
専用スコープの付与(専用スコープの付与を許可する) |
|
|
|
認可とトークンの発行は HTTPS で行います(
localhostなどのループバックの開発環境を除く)。URL の区切り
oauthは、config.server.phpのOAUTH_SEGMENTで変えられます。既存のサイトでは、
.htaccessの設定も確かめてください(OAuth のメタデータの URL と .htaccess)。
接続の流れ
利用者が、MCP クライアントに MCP サーバーの URL(
https://example.com/mcp/)を登録します。client ID・secret は入力しません。クライアントがトークン無しで MCP サーバーへ接続すると、401 が返ります。
WWW-Authenticateヘッダーのresource_metadataに、保護リソースのメタデータの URL が入っています。クライアントは保護リソースのメタデータから認可サーバーを見つけ、認可サーバーのメタデータ(認可・トークン・登録の URL など)を読みます。
クライアントが自分を登録します。アプリの識別子の URL を示す方式(CIMD)か、動的クライアント登録(DCR)です。管理者が事前に登録したクライアントは、登録を飛ばします。
ブラウザで認可の URL(
https://example.com/admin/oauth_authorize/。子ブログは、そのブログの URL の下のadmin/oauth_authorize/)が開きます。ログインしていなければ、a-blog cms のログイン画面が表示されます。二要素認証を設定しているユーザーは、それも通ります。「アプリの接続を確認」の画面が表示されます。利用者が内容を確かめ、「許可する範囲」を選んで「許可する」を押します。
ブラウザがクライアントの戻り先(リダイレクト URI)へ戻り、クライアントが認可コードをトークンに交換します。
クライアントがアクセストークンを付けて MCP サーバーに接続し、ツールを使えるようになります。
新しい接続ができたことを、本人にメールで知らせます(「メール設定」の「API の接続の通知」がオンのとき)。
2 の応答の例です。
HTTP/2 401
content-type: application/problem+json; charset=utf-8
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 サーバーか REST API とその URL)、許可するユーザー、アプリの種別(事前登録以外の CIMD・DCR は「未確認のアプリ」)、接続後の戻り先のホスト、アプリの識別子(client ID)、許可するスコープが表示されます。心当たりのある接続かを確かめ、AI に任せないスコープは外して許可します。
戻り先がお使いの端末の中(
localhost・127.0.0.1・[::1])のときは、「接続後の戻り先が、お使いの端末の中(ローカル)です。接続を始めたアプリか確認してください。」という注意が表示されます。Claude Code など、手元で動くアプリでは正常です。「拒否する」を押すと、接続は作られずにアプリへ戻ります。
許可しても、許可したユーザーの権限を超える操作はできません。スコープは権限を絞るだけです。
画面の下に「許可したあとも、プロフィールの「接続済みアプリ」からいつでも接続を失効できます。」と表示されます(OAuth の接続とクライアントを管理する)。
アプリの登録が見つからない・戻り先(リダイレクト URI)が登録と違うなど、アプリへ戻せない誤りのときは、「アプリと接続できません」の画面になります。付与できないスコープ・無効な接続先などを求めたときは、確認の画面を出さずに、エラー(
invalid_scope・invalid_targetなど)を付けてアプリへ戻します。
トークンとスコープ
アクセストークンは、許可したときの接続先(MCP サーバーか REST API)とブログに結び付きます。MCP 宛てのトークンで REST API を直接呼ぶことはできず、別のブログでも使えません。API トークンは接続先を持たず、MCP でも REST API でも使えます。
スコープは、確認の画面で選んだものだけです。クライアントがスコープを指定しないときは「デフォルトのスコープ」(既定
read write)が初期値になります。専用スコープ(
entries:publish・users:read・users:write・configs:write・field-definitions:write・forms:readなど、read/writeに含まれない強い権限)は、「専用スコープの付与」がオンのときだけ付与できます。オフのときに専用スコープを求めると、確認の画面を出さずに、エラー(invalid_scope)を付けてアプリへ戻します。リフレッシュトークンは使うたびに新しくなります。使用済みのリフレッシュトークンや認可コードが再び使われると、漏えいとみなして、その接続を丸ごと失効します。
OAuth のトークンでは、API トークンの発行・OAuth の接続の許可・クライアントの管理はできません。
MCP でツールを呼んだときにスコープが足りず、そのスコープが OAuth で付与できるものなら、MCP サーバーは HTTP の 403 を返し、クライアントに足りないスコープでの再度の許可を求めさせます。
HTTP/2 403
content-type: application/problem+json; charset=utf-8
www-authenticate: Bearer realm="a-blog cms", error="insufficient_scope", scope="media:write", resource_metadata="https://example.com/.well-known/oauth-protected-resource/mcp/"付与できないスコープ(「専用スコープの付与」がオフのときの entries:publish など)が足りないときは、403 ではなく isError: true の結果(insufficient_scope)になり、AI が人に任せるよう案内されます。スコープの一覧は REST API の認証と API トークン を参照してください。
よくある質問・つまずき
症状 | 原因と確かめ方 |
|---|---|
クライアントが「認可サーバーが見つからない」と表示する | OAuth 認可サーバーが無効か、メタデータが取得できません。 |
ブラウザに「アプリと接続できません」と表示される | アプリの登録が見つからないか、戻り先(リダイレクト URI)が登録と一致しません。事前登録したクライアントなら、「OAuth クライアント」の「リダイレクト URI」とアプリの設定が完全に一致しているか(ループバックの http はポートだけ違ってよい)、クライアントが「無効」になっていないかを確かめます。 |
アプリに |
|
「このサイトは、現在アプリの接続を受け付けていません。」と表示される | OAuth 認可サーバーが無効です(ステータスは 404)。「OAuth 認可サーバーを利用する」をオンにします。 |
CIMD のアプリが登録できない | 「CIMD の受け入れ」がオフか、「CIMD の許可ホスト」にアプリの識別子のホストが入っていません。アプリの識別子の URL が、サーバーから取得できる公開のホストかも確かめます(取得は 5 秒・5 KB まで。リダイレクトは追いません)。 |
動的登録が 429 になる | 「登録の回数制限」に達しました。1 時間待つか、上限を上げます。 |
しばらく使うと接続が切れる | リフレッシュトークンの有効期間(既定 30 日)を過ぎたか、接続が失効されました。もう一度接続し直します。「接続済みアプリ」で接続が残っているかを確かめます。 |
OAuth を一時的にオフにしたら、すべてのアプリがつながらなくなった | オフのあいだは発行済みの OAuth のトークンも 401( |
ブラウザで認可の画面を開くと、ログイン画面ではなく 403 のページになる | ログインしていない状態で認可の画面を開くと、ログイン画面へ送り、ログインのあとに認可の画面へ戻します。この動きには、コンフィグの「ログイン設定」の「現在のURLでログイン」( |
接続のたびに確認の画面が出る | 仕様です。接続を始めるたびに許可を求めます。 |
通知のメールが届かない | 「メール設定」の「API の接続の通知」の From が既定の |
