MCPのトラブルシューティング
接続・起動 → API通信 → トークン権限 → ツール入力の順で確認します。トークン原文をログやエージェントとの会話に貼り付けないでください。
サーバーが起動しない
| 確認項目 | 対処 |
|---|---|
| Nodeが見つからない | Node.js 22以上を入れ、commandに実行ファイルの絶対パスを指定 |
dist/index.jsがない | MCPリポジトリでnpm ciとnpm run buildを実行し、argsを確認 |
OPENTESTER_API_URLが不正 | /api/v1で終わるHTTPS絶対URL。認証情報、query、fragmentを除去 |
OPENTESTER_APP_IDが不正 | 名前やパッケージ名ではなくコンソールのUUIDを指定 |
OPENTESTER_AGENT_TOKENが不正 | SDKトークンやCookieではなくアプリのエージェントトークンを使用 |
ローカルMCPは.envを自動で読みません。ホストから子プロセスに3つの変数を渡します。デスクトップだけ失敗する場合は、ターミナルとの環境変数やPATHの違いを確認します。
ツールが表示されない
codex mcp list、claude mcp list、クライアントの/mcpで確認します。設定変更後は再接続します。
HTTPではhttps://mcp.opentester.app/mcpと接続ガイドの2つの認証ヘッダーを使います。ローカルstdioではHTTP URLではなく実行ファイルを設定します。どちらもMCP OAuthログインは使いません。
パッケージ0.1.0はMCP SDK v2を使い、現行および2025形式の初期化クライアントに対応します。初期化方式が異なる場合はホストとサーバーのバージョンを確認します。
ツールのエラーコード
API・通信失敗はisError: trueを返します。structuredContentの例です。
{
"error": {
"code": "forbidden",
"message": "This token cannot perform this action for this app. Check its scopes and app ownership.",
"status": 403
}
}statusはHTTP応答を受けた場合だけ含まれます。APIの生のエラー本文ではなく、固定メッセージを返します。
| コード | 原因と対処 |
|---|---|
invalid_request | UUID、文字数、報告ID重複、許可フィールドを確認 |
unauthenticated | 不正・期限切れ・取り消し済みトークン。再発行して再接続 |
forbidden | アプリ範囲、権限、所有者、設定アプリIDを確認 |
not_found | 対象アプリの報告・作業IDを再確認 |
conflict | 同じIDで異なる内容、または別PRが関連付け済み。既存作業を確認 |
request_too_large | 説明を短くするか作業を分割 |
rate_limited | 待ってから再試行 |
api_unavailable | サービス状態を確認して再試行 |
timeout | APIが15秒超。書き込み済みの可能性があるため同じIDと入力で再試行 |
connection_failed | API URL、稼働状態、ネットワークを確認 |
redirect_refused | 最終API URLを直接指定 |
response_too_large | 応答が4 MiB超。一覧のlimitを縮小 |
invalid_response | 空またはオブジェクト以外のJSON。ログイン・プロキシ画面を確認 |
internal_error | 想定外の失敗。実行環境とサービス状態を確認 |
API接続前に入力検証で拒否される場合もあります。まず入力仕様を確認します。
読み取りは成功するが作成できない
feedback:readは報告取得だけです。作業取得はwork-items:read、作成・PR関連付けはwork-items:writeが必要です。必要な権限でトークンを再発行し、環境変数またはHTTP認証情報を更新して再接続します。
作業作成後に応答がない
作業は保存済みかもしれません。同じclientRequestIdと元の入力で再試行します。別IDは同じ内容でも別作業になります。このIDはエージェントの担当割り当てやロックではないため、開始前に既存作業を確認します。
PR関連付け後も報告がopenのまま
正常です。作業はpr_linkedになりますが、報告はfixedになりません。GitHub状態同期やPlayデプロイも含まれません。テストとデプロイ後、コンソールで報告を管理します。
リダイレクトとローカルネットワーク
トークンを別アドレスに転送しないよう、MCPはAPIリダイレクトを拒否します。最終HTTPS URLを直接指定します。
平文HTTPはループバックのみです。http://192.168.…などのLANや公開ホストにはHTTPSが必要です。