トラブルシューティング
MCPサーバーへの接続や使用中に問題が発生した場合は、以下の項目を確認してください。
"WHATAP_API_TOKEN environment variable is required"
APIトークンが設定されていないか、MCPサーバーに渡されていません。
各クライアントの設定ファイルで以下の項目を確認してください。
- Claude Desktop:
"env"ブロックに"WHATAP_API_TOKEN"キーがあるか確認（"WHATAP_TOKEN"ではありません） - Codex CLI: TOMLファイルに
[mcp_servers.whatap.env]セクションがあるか確認 - Gemini CLI: settings.jsonに
"env"ブロックがあるか確認 - Claude Code:
claude mcp addコマンドに-envフラグが含 まれているか確認
"No API token found for project XXXXX"
アカウントトークンは有効ですが、該当プロジェクトコードが存在しないかアクセス権限がありません。
AIアシスタントに「プロジェクト一覧を見せて」と入力し、正確なプロジェクトコードを確認します。
"npx: command not found"
Node.jsがインストールされていないか、PATHに登録されていません。
Node.js 18以上をインストールしてください。
node --version # v18以上を確認
npx --version # バージョンが表示されるか確認
"spawn git ENOENT"または"An unknown git error occurred"
Gitがインストールされていないか、実行パスがPATHに登録されていません。
WhaTap MCPサーバーはGitHubリポジトリを直接参照するため、Gitが必要です。主にWindows環境で発生します。
winget install --id Git.Git -e --source winget
インストール後は新しいターミナルを開き、以下のコマンドを実行してください。
git --version # バージョンが表示されるか確認
詳細ははじめに > Gitのインストールドキュメントを参照してください。
MCPサーバーが起動しないか、タイムアウトが発生する
MCPサーバーが起動しないか、タイムアウトが発生します。
サーバーを直接実行してエラーメッセージを確認してください。
WHATAP_API_TOKEN=ここにトークンを入力 npx -y github:whatap/whatap-open-mcp
サーバーが正常に起動すると入力待ち状態になります。Ctrl+Cで終了してください。エラーメッセージが表示された場合は、トークンの値またはNode.jsのバージョンを確認してください。
Claude Desktopでツールが表示されない
Claude DesktopでMCPツールが表示されません。
以下の項目を順番に確認してください。
-
JSONファイルが有効か確認します（カンマの欠落、括弧の不一致など）。
-
Claude Desktopを完全に終了してから再起動します（ウィンドウを閉じるのではなく、アプリを終了）。
-
ログを確認します:
~/Library/Logs/Claude/mcp*.log（macOS）
Codex CLIでツールが表示されない
Codex CLIでMCPツールが表示されません。
以下の項目を順番に確認してください。
-
codex mcp listで登録状況を確認します。 -
~/.codex/config.tomlが正しいTOML形式であるか確認します（JSON文法は使用不可）。 -
削除後に再登録します:
codex mcp add whatap ...
Gemini CLIでツールが表示されない
Gemini CLIでMCPツールが表示されません。
以下の項目を順番に確認してください。
-
gemini mcp listで登録状況を確認します。 -
~/.gemini/settings.jsonが正しいJSON形式であるか確認します。 -
適用範囲を確認します:
-scope user（全体）または-scope project（プロジェクト）
"WhaTap API error (401)" または "(403)"
APIトークンが無効か期限切れです。
WhaTap Consoleでアカウント管理 > APIトークンに移動し、新しいトークンを発行します。
レスポンスが遅い
レスポンスが遅いです。
照会時間の範囲を短くしてください。"5m"（5分）なら数秒、"1d"（1日）なら数十秒かかる場合があります。
連続リクエスト時にWhaTap APIのレート制限に引っかかる場合があります。しばらく待ってから再試行してください。
データが照会されない
データが照会されません。
以下の原因と確認方法を参照してください。
| 原因 | 確認方法 |
|---|---|
| プロジェクトタイプの不一致（例：ServerプロジェクトでAPMクエリを実行） | whatap_data_availability(projectCode)でアクティブカテゴリを確認 → 「このプロジェクトで照会できるデータを見せて」 |
| エージェント未インストールまたは非アクティブ | whatap_list_agents(projectCode)でエージェントの状態を確認 → 「エージェント一覧 を見せて」 |
| 時間範囲が狭すぎる | timeRange="1h"などで範囲を広げて再試行 |