認証

TAGRU の MCP サーバーには、OAuth と API キーの 2 通りの方法で接続できます。どちらの場合も、ツールを呼ぶときにプランやワークスペースの利用資格を確認します。

2 つの接続方法

OAuth

URL を登録するだけで、TAGRU にログインして接続します。Claude や ChatGPT のように、ヘッダーを設定できないクライアントはこちらを使います。

API キー

発行した API キーを Authorization ヘッダーで送ります。CLI や設定ファイルで接続するクライアントに向いています。

OAuth で接続する

MCP 仕様（2026-07-28 版）の認可の手順に沿っています。対応したクライアントでは、次の流れが自動で進みます。

  1. クライアントに URL（https://mcp.tag-ru.com/mcp）だけを登録します。
  2. 接続の最初のリクエスト（initialize）は認証なしでも応答します。その次のリクエスト（ツール一覧の取得など）で、MCP サーバーは 401 と一緒に、認可サーバーの場所（Protected Resource Metadata の URL）を WWW-Authenticate ヘッダーで返します。
  3. クライアントがブラウザで TAGRU のログイン画面を開きます。ログインして、接続するアプリとログイン情報の戻り先を確認し、許可します。
  4. クライアントがアクセストークンを受け取り、以降はそのトークンで MCP サーバーを呼び出します。

OAuth の仕様

自分で MCP クライアントを作る場合の参考情報です。

Protected Resource Metadata
https://mcp.tag-ru.com/.well-known/oauth-protected-resource/mcp
認可サーバー（issuer）
https://api.tag-ru.com
認可サーバーのメタデータ
https://api.tag-ru.com/.well-known/oauth-authorization-server
認可エンドポイント
https://api.tag-ru.com/api/v1/oauth/authorize
トークンエンドポイント
https://api.tag-ru.com/api/v1/oauth/token
  • PKCE は必須です（code_challenge_method は S256 のみ）。
  • resource パラメータ（RFC 8707）には https://mcp.tag-ru.com/mcp を指定します。これ以外を宛先にしたトークンは受け付けません。
  • クライアントの事前登録・動的登録はありません。client_id に Client ID Metadata Document の URL（https）を使うと、その文書に書かれた redirect_uri へ認可コードを返します。
  • それ以外の client_id では、許可済みの redirect_uri（Claude・ChatGPT・Cursor・VS Code の公式のコールバックと、localhost / 127.0.0.1 などのループバック）だけを受け付けます。
  • トークンエンドポイントのクライアント認証は none（公開クライアント）です。
  • アクセストークンの有効期限は 1 時間です。リフレッシュトークンで更新するたびに新しいリフレッシュトークンが発行され、古いものは使えなくなります。ただし、リフレッシュトークンの期限は更新しても延びず、最初に許可した時点から 30 日です。30 日を過ぎたら、もう一度ログインして許可し直す必要があります。
  • 認可の応答には iss パラメータ（RFC 9207）が付きます。

API キーで接続する

ログイン後の API キー管理 でキーを発行し、すべてのリクエストに次のヘッダーを付けます。

HTTP ヘッダー

Authorization: Bearer ak_XXXXX.YYYYY
  • 有効な API キーを送っていれば、そのまま接続できます。OAuth のログイン画面や許可の画面は表示されません。
  • API キーが無効だと 401 が返ります。OAuth に対応したクライアントでは、そのときにログイン画面が開くことがあります。その場合は API キーが正しいか確認してください。
  • API キーには、発行時に選んだスコープ（draft.read / draft.write）が付きます。

スコープ

  • mcp:use

    MCP サーバーへの接続。OAuth でスコープを指定しないときの既定値です。

  • draft.read

    下書きなどの読み取り。

  • draft.write

    下書きの作成とメディアのアップロード。書き込み系のツールに必要です。

書き込み系のツール（下書きの作成・メディアのアップロード）には draft.write が必要です。読み取り系のツールは、接続できていれば使えます。OAuth で付与されるスコープはクライアントが要求した範囲で、TAGRU の許可画面でスコープを個別に選ぶ欄はありません。API キーのスコープは、発行時に選びます。どのツールに何が必要かは ツール一覧 を参照してください。

エラーの返り方

  • 401 は「誰なのか確認できない」状態です。API キーまたはアクセストークンが無い・無効・期限切れのときに返ります。
  • 403 は「誰かは分かるが、その操作はできない」状態です。OAuth のトークンで draft.write が足りないツールを呼ぶと、ツールを実行する前に 403 insufficient_scope を返し、必要なスコープを WWW-Authenticate ヘッダーで伝えます。クライアントによっては、追加の許可を求める画面が開きます。
  • API キーのスコープ不足や、プラン・ワークスペースの利用資格が無い場合は、接続はできたうえで、ツールの実行結果がエラーになり、理由がエラー文で返ります。

具体的なエラーと対処は エラーと対処 にまとめています。