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 認可サーバーを有効にする

  1. ルートブログの「REST API設定」(開き方は MCP サーバーを有効にする(設定項目の一覧))で、「MCP サーバーを利用する」がオンであることを確かめます。OAuth で接続できるのは、有効になっている入口だけです。

  2. 「OAuth 認可サーバー」の「OAuth 認可サーバーを利用する」にチェックを入れて保存します。ほかの項目は、まずは既定値のままにします。接続できるアプリを claude.ai などに絞るときは「CIMD の許可ホスト」、アプリの自己登録を止めるときは「動的クライアント登録(DCR)」を変えます。

  3. 認可サーバーのメタデータが返るかを確かめます: curl https://example.com/.well-known/oauth-authorization-server(パスのあるブログは OAuth のメタデータの URL と .htaccess の URL)。JSON が返れば有効です。

「REST API設定」の「OAuth 認可サーバー」の節
「REST API設定」の「OAuth 認可サーバー」の節

項目(画面の名前)

設定キー

既定値

説明・入力例

OAuth 認可サーバー有効化(OAuth 認可サーバーを利用する)

oauth_enable

off

OAuth 認可サーバー(/oauth/)を有効にします。オフのあいだは、/oauth/ とメタデータが 404 になり、発行済みの OAuth のトークンも使えません(API トークンは使えます)。

CIMD の受け入れ(URL で示されたアプリの情報で自動登録する(CIMD))

oauth_cimd_enable

on

アプリの識別子(https の URL)に置かれた情報を取得して、アプリを自動で登録します。ルートブログの設定だけが使われます。

CIMD の許可ホスト

oauth_cimd_allowed_hosts

空

CIMD のアプリの識別子に使えるホスト名を、完全一致で制限します。例: claude.ai。空なら、公開のホストをすべて受け付けます。ルートブログの設定だけが使われます。

動的クライアント登録(DCR)(動的クライアント登録(DCR)を受け入れる)

oauth_dcr_enable

on

アプリが自分で登録できるようにします。登録だけでは権限を与えず、利用には利用者の許可が要ります。ルートブログの設定だけが使われます。

登録の回数制限

oauth_register_limit_per_hour

10

動的登録の、接続元 IP アドレスごとの 1 時間あたりの上限です。超えると 429 を返します。

トークン発行の失敗の上限

oauth_token_failure_limit_per_minute

20

トークンの発行・取り消しの失敗の、接続元 IP アドレスごとの 1 分あたりの上限です。達すると 10 分間 429 を返します。

アクセストークンの有効期間

oauth_access_token_ttl

3600

秒で指定します。300〜86400 の範囲に丸めます。

リフレッシュトークンの有効期間

oauth_refresh_token_ttl

2592000

秒で指定します。使うたびに新しくなります。86400〜7776000 の範囲に丸めます。

デフォルトのスコープ

oauth_default_scope

read write

クライアントがスコープを指定しないときの値で、確認の画面の初期値にもなります。スペース区切りで指定します。空のときは read write を使います。

専用スコープの付与(専用スコープの付与を許可する)

oauth_allow_dedicated_scopes

off

entries:publish・users:write など影響の大きい専用スコープを、OAuth で付与できるようにします。オフのときは、専用スコープを含む要求を拒否します。

  • 認可とトークンの発行は HTTPS で行います(localhost などのループバックの開発環境を除く)。

  • URL の区切り oauth は、config.server.php の OAUTH_SEGMENT で変えられます。

  • 既存のサイトでは、.htaccess の設定も確かめてください(OAuth のメタデータの URL と .htaccess)。

接続の流れ

  1. 利用者が、MCP クライアントに MCP サーバーの URL(https://example.com/mcp/)を登録します。client ID・secret は入力しません。

  2. クライアントがトークン無しで MCP サーバーへ接続すると、401 が返ります。WWW-Authenticate ヘッダーの resource_metadata に、保護リソースのメタデータの URL が入っています。

  3. クライアントは保護リソースのメタデータから認可サーバーを見つけ、認可サーバーのメタデータ(認可・トークン・登録の URL など)を読みます。

  4. クライアントが自分を登録します。アプリの識別子の URL を示す方式(CIMD)か、動的クライアント登録(DCR)です。管理者が事前に登録したクライアントは、登録を飛ばします。

  5. ブラウザで認可の URL(https://example.com/admin/oauth_authorize/。子ブログは、そのブログの URL の下の admin/oauth_authorize/)が開きます。ログインしていなければ、a-blog cms のログイン画面が表示されます。二要素認証を設定しているユーザーは、それも通ります。

  6. 「アプリの接続を確認」の画面が表示されます。利用者が内容を確かめ、「許可する範囲」を選んで「許可する」を押します。

  7. ブラウザがクライアントの戻り先(リダイレクト URI)へ戻り、クライアントが認可コードをトークンに交換します。

  8. クライアントがアクセストークンを付けて MCP サーバーに接続し、ツールを使えるようになります。

  9. 新しい接続ができたことを、本人にメールで知らせます(「メール設定」の「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 認可サーバーが無効か、メタデータが取得できません。curl -i https://example.com/.well-known/oauth-authorization-server が 200 の JSON を返すかを確かめます。301 や 403 なら .htaccess を確かめます(OAuth のメタデータの URL と .htaccess)。

ブラウザに「アプリと接続できません」と表示される

アプリの登録が見つからないか、戻り先(リダイレクト URI)が登録と一致しません。事前登録したクライアントなら、「OAuth クライアント」の「リダイレクト URI」とアプリの設定が完全に一致しているか(ループバックの http はポートだけ違ってよい)、クライアントが「無効」になっていないかを確かめます。

アプリに invalid_scope・invalid_target のエラーが返る

invalid_scope は、専用スコープなど付与できないスコープを求めています(「専用スコープの付与」)。invalid_target は、接続先(MCP サーバー・REST API)が無効か、別のブログの URL を求めています。

「このサイトは、現在アプリの接続を受け付けていません。」と表示される

OAuth 認可サーバーが無効です(ステータスは 404)。「OAuth 認可サーバーを利用する」をオンにします。

CIMD のアプリが登録できない

「CIMD の受け入れ」がオフか、「CIMD の許可ホスト」にアプリの識別子のホストが入っていません。アプリの識別子の URL が、サーバーから取得できる公開のホストかも確かめます(取得は 5 秒・5 KB まで。リダイレクトは追いません)。

動的登録が 429 になる

「登録の回数制限」に達しました。1 時間待つか、上限を上げます。

しばらく使うと接続が切れる

リフレッシュトークンの有効期間(既定 30 日)を過ぎたか、接続が失効されました。もう一度接続し直します。「接続済みアプリ」で接続が残っているかを確かめます。

OAuth を一時的にオフにしたら、すべてのアプリがつながらなくなった

オフのあいだは発行済みの OAuth のトークンも 401(invalid_token)になります。オンに戻すと、有効期間内のトークンは再び使えます。

ブラウザで認可の画面を開くと、ログイン画面ではなく 403 のページになる

ログインしていない状態で認可の画面を開くと、ログイン画面へ送り、ログインのあとに認可の画面へ戻します。この動きには、コンフィグの「ログイン設定」の「現在のURLでログイン」(login_auto_redirect。既定 on)がオンである必要があります。オフにしているサイトでは、先に同じブラウザで管理画面にログインしてから接続を始めます。

接続のたびに確認の画面が出る

仕様です。接続を始めるたびに許可を求めます。

通知のメールが届かない

「メール設定」の「API の接続の通知」の From が既定の info@example.com のままでないか、本人のメールアドレスが正しいかを確かめます。