認証

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)から有効な Bearer トークンが必要です。トークンがない場合、MCP サーバーは HTTP 401 と一緒に、認可サーバーを発見するための Protected Resource Metadata の URL を WWW-Authenticate ヘッダーで返します。
  3. クライアントがブラウザで TAGRU のログイン画面を開きます。ログインして、接続するアプリとログイン情報の戻り先を確認し、許可します。
  4. クライアントがアクセストークンを受け取り、Authorization: Bearer ヘッダーを付けて initialize を再試行します。以降も各 HTTP リクエストにトークンを付けます。

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(公開クライアント)です。ただし、ログイン後の API キー管理の「OAuth クライアント」で作成したクライアント ID(tagru_mcp_ で始まるもの)は、client_secret_post または client_secret_basic でクライアントシークレットを送る必要があります。このクライアント ID は作成したアカウントのログインにだけ使えます。
  • アクセストークンの有効期限は 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 / settings.write)が付きます。settings.write は既定では選択されません。

スコープ

  • mcp:use

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

  • draft.read

    下書きなどの読み取り。

  • draft.write

    下書きの作成・メディアのアップロード・素材の登録・画像の作成と編集・動画の生成の開始。設定更新の権限は含みません。

  • settings.write

    対応する設定更新ツール専用の権限です。既存キーや OAuth の許可へ自動追加されません。この権限だけで生成・投稿・予約投稿はできません。

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

settings.write は既存キーや OAuth の許可へ自動追加されません。OAuth の不足権限は クライアントの追加許可(step-up)で取得します。追加許可が開かない場合は、必要なスコープを要求する設定で接続し直してください。 更新トークンだけでは権限は増えません。API キーは必要なスコープを選んで新規発行し、接続先で差し替えてください。 既存キーの編集やシークレット再発行ではスコープは変わりません。キーやトークンの値をチャット・画像・ログへ貼り付けないでください。

エラーの返り方

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

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

接続仕様の変更予定(リリースノート)

接続開始時の認証を必須にする変更です。サーバーへの反映後は、従来の匿名 initialize は成功せず HTTP 401 を返します。単なる後方互換の修正ではありません。

SSE クライアントは GET /sse だけでなく、POST /messages/ の initialize・通知・ツール呼び出しにも Authorization: Bearer ヘッダーを付けてください。Streamable HTTP の /mcp も、すべての HTTP リクエストに同じ認証が必要です。公開メタデータの取得には認証は不要です。

既存の OAuth トークンと API キーは、有効期限と付与済み権限の範囲で引き続き利用できます。 接続先 URL やリフレッシュトークンの更新手順は変わりません。再接続時も各リクエストへの Bearer 付与を確認してください。