MCPのトラブルシューティング

再試行の前に、ツールの検出、認証、組織へのアクセス、引数、結果が不明な処理について問題を切り分けます。

症状に応じて、次に確認する項目を選びます。ツールが見つからない場合は接続を、呼び出しが拒否された場合は引数や権限に関するエラーを確認してください。ツール名、機密情報を含まない入力、応答、関連するリソースやソースのリビジョンを保存しておきます。こうした記録があれば、結果が不明な書き込みを繰り返さずに、本来の作業を再開しやすくなります。

あるはずのツールが見つからない #

設定したエンドポイントと、クライアントが返すツール一覧を照合します。/mcpと/mainは、認証が必要な同じツール群を公開しています。/accountは、認証後に/mainへリダイレクトします。

members_listMembershipsとengines_listを探し、初回の読み取り例に沿って操作してください。正確な名前とスキーマは、最新のtools/listの応答で確認します。APIエンドポイントが存在していても、MCPで公開されているとは限りません。

一部のツールだけが表示されない場合は、クライアントの許可リストと承認設定を確認し、作業に必要なものだけを有効にしてください。本来あるはずのツールが見つからない場合は、報告に備えてサーバーとバージョンの情報、および機密情報を含まない検出結果を保存しておきます。

GETで405が返される #

/mcpでストリーマブルHTTPを使用するように設定します。認証後、/mcpまたは/mainへのGETは、Allow: POSTを伴う405を返します。クライアントはPOSTでMCPメッセージを送信します。トークンがない場合や無効な場合は、処理が振り分けられる前に401が返されます。一方、/accountへの認証済みリクエストでは、/mainへの308が返されます。これらのGETの応答では、有効なMCPのPOST接続が機能するかどうかは確認できません。正しいトランスポートを選択してから、クライアントの接続エラーを調べてください。

認証または組織が正しくない #

401では、接続時に意図したLingo.devユーザーとしてOAuth認証を完了しているか確認します。ホスト型サーバーには、有効なユーザーのベアラートークンが必要です。個人用またはサービス用のAPIキーは、x-api-keyでもベアラー値としても使用できません。クライアントに認可情報を更新させるか、クライアントのアカウント管理から再接続してください。診断情報にトークンを含めないでください。

members_listMembershipsを呼び出し、dataから目的の組織を選んで、そのIDを次のツールの組織フィールドに渡します。engines_listの場合、そのフィールドはorgIdです。同じ一覧から別の組織を選ぶだけなら、OAuth認可をやり直す必要はありません。ログイン中のユーザーが違う場合は再接続してください。再起動だけでは、保存済みのセッションが再利用されることがあります。

ssoRequiredにメンバーシップが表示される場合は、その組織の認証プロバイダーを通じてLingo.devにログインし、再接続してください。dataとssoRequiredが両方とも空の場合は、https://lingo.dev/orgs/startで組織のセットアップを完了してから、メンバーシップを再取得します。組織を利用できない理由としては、組織が存在しない、ユーザーが所属していない、SSOが必要といった可能性があります。このような応答をすべて認証情報の期限切れと判断しないでください。

ツールが権限や利用資格を理由に処理を拒否した場合は、認証を繰り返すのではなく、その操作の要件を確認してください。組織へのアクセスと、特定の書き込みを実行する権限は、別々に確認されます。無断で権限の広いロールや認証情報を選ばず、どの権限が不足しているかを説明してください。

組織のセットアップが未完了とツールに表示される #

最近作成された組織で、作成者がウェブアプリでのセットアップをまだ完了していない状態です。セットアップには、連携、チームメンバー、最初のエンジンの設定が含まれます。完了するまで、組織レベルのツールが利用できないことがあります。再試行や再認可を行っても、これらの手順は完了しません。members_listMembershipsは引き続き利用できます。組織の作成者としてメッセージ内のリンクhttps://lingo.dev/orgs/<orgId>を開き、記載された手順を完了してから、もう一度呼び出してください。新しい組織のセットアップを完了するを参照してください。

ツールに引数が拒否される #

入力を、接続先から返されたスキーマと正確に照合します。現在のツールの引数はフラットなフィールドで構成され、スキーマで指定された箇所にのみ入れ子の値を持ちます。独自にbody、params、queryのラッパーを追加しないでください。組織フィールドが必須の場合は、明示的に指定します。ベアラートークンから自動的に設定されることはありません。任意項目のintentにはタスクの内容を記述します。対応するアカウント操作については、機能を参照してください。

各IDが何を識別するものか確認してください。members_remove.idはmembers_listから取得したメンバーシップIDで、members_setRole.userIdはそのメンバーシップのユーザーを識別します。ローカライゼーションエンジンのIDを、リクエストログのIDの代わりに使うことはできません。内部構造を解釈できないカーソルや、精度を省略していないタイムスタンプとIDの組は、表示された日付から再構成せず、そのまま正確にコピーしてください。

スキーマで定義された、省略とヌル値、数値と文字列、配列と単一の値の違いを保ってください。引数エラーの回避策を適用する前に、接続先ツールのスキーマを確認します。

アカウントへの書き込みやジョブの結果が不明 #

再試行する前に、関連するリソースやジョブの状態を確認してください。キーの作成、招待、レビューの判断、提案、ジョブをサーバーが受け付けた後で、ネットワークエラーが発生することがあります。自動的に再送信せず、意図した変更が実際に反映されているかを確かめてください。

送信済みのプロビジョニングジョブについては、再試行するかどうかを決める前に、保存したジョブIDを使ってprovisioningJobs_getで状態を確認します。その他の操作では、保存したリソースと、接続先ツールが定める完了条件を確認してください。翻訳ワークフローについては、CLIまたはAPIのリファレンスを参照してください。

ドキュメントや根拠が見つからない #

localization_searchで検索し、検索結果のpathをdocs_fetchに渡してページ全体を読み取ります。そのパスで取得できない場合は、タスクについて再検索し、最新の結果を使用してください。ナレッジベースは、ファイルを基盤とするウェブサイトとは別の保存先を使用しています。そのため、ウェブサイトのページがナレッジベースのインデックスに存在しない場合や、内容が古い場合があります。機能を利用できないと結論付ける前に、ウェブサイトの最新のリファレンスを確認してください。

MCPで未解決の機能不足を報告する場合は、試みたタスク、正確なツール名、サーバーのバージョン、機密情報を含まない応答を記載してください。報告の受領通知は、修正時期を約束するものではありません。

品質に関する問い合わせでは、何が不足しているかを特定してください。ソースの根拠資料、完了済みの評価、適用できる基準、明確な回答のうち、どれが不足しているかによって、次に必要な対応は異なります。測定では、未回答のケースを合格扱いせずに、入手できた根拠を報告する方法を説明しています。