エラーと対処

接続やツールの呼び出しでよく出るエラーと、その対処です。エラー文は英語で返るため、見出しに実際の文言を載せています。接続できないときは HTTP のエラー（401 / 403）、接続後にツールが失敗したときはツールの実行結果のエラー文として返ります。

まず確認すること

auth_whoami を呼ぶと、認証中のユーザー ID と付与されているスコープが返ります。このツールはプランの確認を行わないため、

  • auth_whoami も失敗する → 認証（トークン・API キー）の問題
  • auth_whoami は成功し、ほかのツールが失敗する → スコープ・プラン・ワークスペースの問題

と切り分けられます。

401 invalid_token（Authentication required）

トークンが送られていない、または API キー・アクセストークンが無効です。API キーの削除・無効化や、アクセストークンの期限切れ（1 時間）や、リフレッシュトークンの期限切れ（最初に許可してから 30 日）でも起こります。

対処

  • Authorization ヘッダーが「Bearer 」に続けて API キーを送っているか確認してください。
  • API キーが API キー管理で有効になっているか確認し、分からなければ API キーを発行し直してください。
  • API キーが無効だと、OAuth に対応したクライアントでは TAGRU のログイン画面が開くことがあります。API キーで接続したい場合は、ログインせずに API キーを確認してください。
  • OAuth で接続している場合は、クライアントから接続し直し、もう一度ログインして許可してください。

Required scope: draft.write（403 insufficient_scope）

書き込み系のツール（下書きの作成・メディアのアップロード）を、draft.write を持たない API キーやアクセストークンで呼んでいます。OAuth のトークンでは HTTP 403 insufficient_scope が、API キーではツールのエラーとしてこの文言が返ります。

対処

  • API キーの場合は、draft.write にチェックを入れたキーを発行して差し替えてください。
  • OAuth の場合は、クライアントから接続し直してください。付与される権限はクライアントが要求した範囲で、TAGRU の許可画面でスコープを個別に選ぶ欄はありません。

MCP access is available only to pro, premium, or business users ...

ご自身のプランが pro / premium / business ではなく、対象のワークスペースにも参加していません。

対処

  • プランを確認してください。
  • ワークスペース経由で使う場合は、ワークスペースのオーナーが対象プランであることと、招待を承認済みであることを確認してください。

This API key can only access workspace-scoped MCP tools ...

ワークスペースの参加者として利用資格がある状態で、個人用ツール（workspaces_ で始まらないツール）を呼んでいます。

対処

  • workspaces_me でワークスペース ID を確認し、workspaces_ で始まるツールを使ってください。

Not a member of workspace / Admin role required など

指定したワークスペースに参加していない、招待が未承認、または管理者向けのツールを一般メンバーで呼んでいます。

対処

  • workspaces_me の結果に、そのワークスペースが含まれているか確認してください。
  • 下書きの作成・一覧とメディアのアップロードは、ワークスペースのオーナーまたは管理者のみ使えます。

メディアのアップロードに失敗する

ファイル名に拡張子が無い、対応していない形式、100MB を超えている、または content が Base64 になっていません。

対処

  • filename は image.jpg のように拡張子を付けてください。
  • 画像は png / jpg / jpeg、動画は mp4 / mov に対応しています。
  • content にはファイルを Base64 にした文字列を渡してください。

解決しない場合は、 お問い合わせ から、使っているクライアント名とエラー文を添えてご連絡ください。