MCPセットアップで詰まる9つの問題と解決策｜Claude Desktop / Claude Code 共通トラブルシューティング

MCP (Model Context Protocol) 連携の設定で詰まるケースの大半は、決まった9つのパターンに該当します。本記事は Ganty を含む MCP 対応 SaaS で詰まったときのトラブルシューティングを、診断フロー付きで完全網羅した実務ガイドです。Claude Desktop と Claude Code 両方に対応しています。

診断の前に：まず確認すべき5ステップ

具体的なエラー別の対処に入る前に、上記の HowTo 5ステップを順に実行してください。原因の8割はこの5ステップ内のいずれかで判明します。それでも解決しない場合に、以下の9つの問題別対処法を参照してください。

問題1：Claude Desktop の MCP ツール一覧に Ganty が出ない

最頻出パターン。原因は次の3つのうちのいずれかです。

• 設定ファイルのパスが間違っている: macOS と Windows でパスが異なります。HowTo ステップ2で正しいパスを確認
• JSON書式エラー: カンマ忘れ・括弧の閉じ漏れ・全角文字混入。jq . config.json でバリデート
• 再起動が不完全: ウィンドウを閉じただけでは設定が再読込されません。Cmd+Q または タスクトレイの Quit で完全終了

問題2：401 Unauthorized が返る

認証エラーの典型パターン。チェックリスト：

• トークンが失効していないか (Ganty ダッシュボード → MCP連携 で確認)
• トークンのコピー時に余分な空白や改行が入っていないか
• Authorization: Bearer TOKEN の形式が正しいか (Bearer と トークンの間に半角スペース1つ)

解決の最短ルートは「現トークンを revoke → 新規発行 → 完全コピー → 設定ファイル更新 → クライアント再起動」です。

問題3：設定ファイルの JSON 書式エラー

典型的な間違い：

// ❌ 末尾カンマ
{
  "mcpServers": {
    "ganty": { "url": "...", },
  }
}

// ✅ 正しい形式
{
  "mcpServers": {
    "ganty": {
      "url": "https://ganty.app/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

VS Code や jq でフォーマット・バリデーションすれば一発で発見できます。

問題4：Claude Desktop を再起動しても反映されない

「ウィンドウを閉じる」と「アプリを完全終了する」は別物です。macOS は Cmd+Q で必ず完全終了。Windows はタスクトレイのアイコン右クリック→Quit でバックグラウンドプロセスごと終了します。タスクマネージャー / Activity Monitor で Claude プロセスが残っていないことを確認してから再起動してください。

問題5：ローカル MCP サーバーが起動しない

ローカル(stdio型)MCPサーバーの場合、コマンドのパスが間違っていることが多い原因です。設定ファイルで command を絶対パスで指定するか、npx -y @your-org/mcp-server のように -y オプション付きで指定して初回起動を確実にします。Ganty は HTTP 型(リモート)なのでこの問題は起きませんが、複数 MCP を併用する場合は他サーバー側の問題で連動して動かないように見えることがあります。

問題6：ポート競合 (ローカル MCP のみ)

同じポートを使うMCPサーバーが複数登録されていると衝突します。各サーバーの設定で env に PORT を明示するか、URL に異なるポートを指定して回避します。Ganty のリモート MCP では発生しません。

問題7：SSL/TLS 証明書エラー

企業ネットワーク・プロキシ環境で稀に発生します。証明書チェーンの問題か、HTTPS インスペクションを行うプロキシによる中間者復号が原因。NODE_EXTRA_CA_CERTS 環境変数で社内CA証明書を追加するか、ネットワーク管理者に ganty.app ドメインの除外を依頼してください。

問題8：レート制限 (429 Too Many Requests)

短時間に大量リクエストを送ると一時的にレート制限がかかります。Ganty の MCP API はIPあたり毎分60リクエストを上限としています。バッチ処理が必要なら指数バックオフでリトライ実装するか、間隔を空けて呼び出してください。

問題9：Claude / MCP クライアントのバージョン非互換

Claude Desktop が古いと最新の MCP 仕様(2025年以降の更新)に対応していないことがあります。アプリのバージョンを確認し、最新版にアップデート。Claude Code は claude --version で確認後、npm i -g @anthropic-ai/claude-code@latest で更新してください。

診断フローチャート

困ったら次の順番で切り分けてください。

1. curl で疎通確認: curl -i -H "Authorization: Bearer TOKEN" https://ganty.app/api/mcp
2. 200 が返る → クライアント側の問題 (設定ファイル or 再起動)
3. 401 → トークン or Authorization ヘッダ問題
4. 403 → トークンのスコープ不足
5. 500/timeout → サーバー側の一時障害 (status ページ確認)

次のステップ

本記事の手順で解決しない場合は support@ganty.app までエラー画面のスクリーンショットとトークンプレビュー(gnty_xxxx...xxxx)を添えて連絡してください。MCP連携の基本セットアップは MCP連携ガイド、活用パターンは MCP活用5実例 と Claude Code でプロジェクト管理する完全ガイド で解説しています。