---
title: MCPのトラブルシューティング
description: OpenTester MCPの接続、認証、権限、再試行の問題を解決します。
---

# MCPのトラブルシューティング {#mcp-troubleshooting}

**接続・起動 → API通信 → トークン権限 → ツール入力**の順で確認します。トークン原文をログやエージェントとの会話に貼り付けないでください。

## サーバーが起動しない {#server-does-not-start}

| 確認項目 | 対処 |
| --- | --- |
| 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の違いを確認します。

## ツールが表示されない {#tools-do-not-appear}

`codex mcp list`、`claude mcp list`、クライアントの`/mcp`で確認します。設定変更後は再接続します。

HTTPでは`https://mcp.opentester.app/mcp`と[接続ガイド](/ja/mcp/clients#remote-http)の2つの認証ヘッダーを使います。ローカルstdioではHTTP URLではなく実行ファイルを設定します。どちらもMCP OAuthログインは使いません。

パッケージ`0.1.0`はMCP SDK v2を使い、現行および2025形式の初期化クライアントに対応します。初期化方式が異なる場合はホストとサーバーのバージョンを確認します。

## ツールのエラーコード {#tool-error-codes}

API・通信失敗は`isError: true`を返します。`structuredContent`の例です。

```json
{
  "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接続前に入力検証で拒否される場合もあります。まず[入力仕様](/ja/mcp/tools)を確認します。

## 読み取りは成功するが作成できない {#reads-succeed-but-creation-fails}

`feedback:read`は報告取得だけです。作業取得は`work-items:read`、作成・PR関連付けは`work-items:write`が必要です。必要な権限で[トークンを再発行](/ja/api/tokens)し、環境変数またはHTTP認証情報を更新して再接続します。

## 作業作成後に応答がない {#no-response-after-creating-work}

作業は保存済みかもしれません。同じ`clientRequestId`と元の入力で再試行します。別IDは同じ内容でも別作業になります。このIDはエージェントの担当割り当てやロックではないため、開始前に既存作業を確認します。

## PR関連付け後も報告がopenのまま {#feedback-stays-open-after-linking-a-pr}

正常です。作業は`pr_linked`になりますが、報告は`fixed`になりません。GitHub状態同期やPlayデプロイも含まれません。テストとデプロイ後、コンソールで報告を管理します。

## リダイレクトとローカルネットワーク {#redirects-and-local-networks}

トークンを別アドレスに転送しないよう、MCPはAPIリダイレクトを拒否します。最終HTTPS URLを直接指定します。

平文HTTPはループバックのみです。`http://192.168.…`などのLANや公開ホストにはHTTPSが必要です。