エラーと対処
接続やツールの呼び出しでよく出るエラーと、その対処です。エラー文は英語で返るため、見出しに実際の文言を載せています。接続できないときは 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 / settings.write(403 insufficient_scope)
ツールに必要なスコープがありません。下書き作成やメディア操作などには draft.write、対応する設定更新ツールには settings.write が必要です。OAuth では HTTP 403 insufficient_scope、API キーではツールのエラーとして必要なスコープが返ります。
対処
- API キーの場合は、エラーに示されたスコープにチェックを入れた新しいキーを発行し、接続先で差し替えてください。既存キーの編集やシークレット再発行ではスコープは増えません。
- OAuth の場合は、クライアントの追加許可(step-up)へ進んでください。開かない場合は、必要なスコープを要求する設定で接続し直してください。TAGRU の許可画面でスコープを個別に選ぶ欄はなく、更新トークンの再発行だけでは権限は増えません。
- API キーやアクセストークンの値をチャット・スクリーンショット・ログへ貼り付けないでください。
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 にした文字列を渡してください。
asset_limit_reached / asset_invalid_format / asset_file_too_large / asset_forbidden / asset_classification_failed など
素材のツールは、断った理由を structuredContent の error.code で返します。asset_limit_reached は 20 件の上限、asset_invalid_format は対応していない形式(拡張子と中身の不一致を含む)、asset_file_too_large は 10MB 超え、asset_forbidden は権限不足(プランの対象外・参加していないワークスペース)、asset_invalid_input は名称・説明・content・workspace_id の入力の誤りや、ツールの定義に無い引数(個人用ツールへの workspace_id など)、asset_not_found はその領域に無い素材です。分類し直しでは、asset_already_classified は分類済みの素材(AI は使いません)、asset_classification_failed は AI の分類の失敗(素材は未分類のまま)、asset_reclassify_cooldown は同じ素材を前回の試行から 5 分以内に試したとき(AI は使いません)です。
対処
- 上限に達したときは、TAGRU の「素材」画面で不要な素材を削除してください(MCP からは削除できません)。
- 形式は JPEG / PNG / WebP / PDF、1 ファイル 10MB までです。filename の拡張子を中身に合わせてください。
- AI クライアントから大きいファイルを送れないときは、TAGRU の「素材」画面から登録してください。
- ワークスペースに登録するときは workspaces_asset_create に workspace_id を渡してください。workspaces_me で参加しているワークスペースを確認できます。
- asset_classification_failed のときは、時間をおいてから呼び直すかを利用者に確かめてください。何度も失敗する場合は、TAGRU の「素材」画面で削除してから登録し直してください。
image_limit_exceeded / image_plan_not_allowed / image_invalid_input / image_not_found など
画像の作成・編集のツールは、断った理由を structuredContent の error.code で返します。image_limit_exceeded は今月の画像生成の上限(画面の画像作成・画像編集・投稿案の画像と共通)、image_plan_not_allowed は画像生成を使えないプラン、image_invalid_input は mode と引数の組み合わせの誤り(create で prompt が無い、edit で main_image_path が無いなど)や対応していない形式、image_not_found は指定した画像が無い、image_forbidden は別の領域(個人 / ワークスペース)の画像やワークスペースの権限不足、image_generation_busy は同じ領域で同時に多くの生成が行われて混み合っている(何も作成しておらず上限は使っていない)、image_generation_failed は生成の失敗です。
対処
- 上限は翌月 1 日(UTC)に戻ります。残りの回数は TAGRU の「画像作成」画面で確認できます。
- 元の画像は、同じ領域(個人なら media_upload、ワークスペースなら workspaces_media_upload)で返された path を渡してください。形式は PNG / JPEG / WebP です。
- image_generation_busy のときは、同時に呼ぶ数を減らし、少し待ってからもう一度お試しください。
- image_generation_failed のときは、時間をおいてもう一度お試しください。
Unknown tool: video_generate / video_not_enabled / video_estimate_exceeds_max / video_insufficient_deposit / video_request_id_conflict など
動画の生成が有効でないアカウントでは、動画のツールは一覧に出ず、名前を指定して呼ぶと Unknown tool になります。ほかの理由は structuredContent の error.code で返します。video_not_enabled は指定したワークスペースで動画の生成が有効でない、video_estimate_exceeds_max は上限見積が max_jpy を超えた、video_insufficient_deposit はデポジットの残高不足、video_invalid_input は引数の誤り(モデルが受け付けない resolution・aspect_ratio、尺など)、video_forbidden は権限不足、video_job_not_found はその領域に無いジョブ、video_request_id_conflict は同じ request_id で別の内容の開始が既にある(そのジョブは開始・課金済みで、error.job_id に入る)、video_start_incomplete はジョブはあるが開始の処理が終わったことを確かめられない、video_request_id_ended はその request_id のジョブが開始の前に失敗(課金なし)・取り消しで終わった、video_start_failed は開始の失敗です。video_start_failed・video_request_id_conflict・video_start_incomplete・video_request_id_ended 以外は、開始されず料金も発生していません(video_request_id_ended は job_status が error のときだけ料金が発生していません)。
対処
- 動画の生成を使うには、TAGRU のお問い合わせ(https://tag-ru.com/contact)から申請してください。有効になった後は、AI クライアントから TAGRU MCP に接続し直すとツールが表示されます。
- video_estimate_exceeds_max のときは、尺・モデル・解像度か金額を利用者と確かめ直してください。
- video_insufficient_deposit のときは、TAGRU のプランページからデポジットをチャージしてください。
- video_start_failed や時間切れのときは、request_id を付けていれば同じ request_id・同じ引数で呼び直してください(開始済みならそのジョブが返ります)。付けていなければ、すぐにやり直さず、video_job_list(ワークスペースは workspaces_video_job_list)で開始済みのジョブが無いか確かめてください。
- video_request_id_conflict のときは、その request_id のジョブ(error.job_id)が開始済みです。同じ動画のつもりなら新しく開始せず、video_job_get で確かめてください。別の動画のときだけ新しい request_id で呼んでください。
- video_start_incomplete のときは新しく開始せず、数分おいて video_job_get で確かめてください。開始の処理が途中で止まっていた場合は、しばらくすると TAGRU が自動で取り消し(status が cancelled になり、理由は error_message に入ります)、デポジットから引かれていた分は確かめたうえで返金します。作り直すときは新しい request_id で開始してください。
- video_request_id_ended のときは、job_status が error なら課金されていません。cancelled なら取り消されたジョブです。作り直すときは新しい request_id で開始してください。
解決しない場合は、 お問い合わせ から、使っているクライアント名とエラー文を添えてご連絡ください。