# MCP トラブルシューティング
SUMMARY: よくある MCP 連携の問題を解決 — サーバーが起動しない、ツールが表示されない、認証エラー。

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

MCP トラブルシューティング
Synapse MCP を LLM クライアントに連携する際のよくある問題と解決策。
クイック診断チェックリスト
1. ✅ Node.js 18+ がインストール済み？（）
2. ✅ Mind Key が  で始まる？（JWT  ではない）
3. ✅ Synapse API に到達可能？（）
4. ✅ Mind Key が動作する？（）
5. ✅ 設定ファイルが有効な JSON？（末尾のカンマなし、コメントなし）
6. ✅ 設定変更後にクライアントを再起動した？
7. ✅ MCP サーバーが手動で起動する？（）
問題：クライアントにツールが表示されない
症状
- Claude Desktop / Cursor / Continue が 0 ツールを表示
- MCP サーバーリストに 🔌 アイコンや「synapse」エントリがない
解決策
1. クライアントを完全に再起動 — macOS では Cmd+Q（ウィンドウを閉じるだけではない）
2. 設定ファイルの場所を確認：
   - Claude Desktop macOS：
   - Claude Desktop Windows：
   - Cursor：
   - Continue：
3. JSON を検証 — 設定を <https://jsonlint.com> に貼り付け
4. クライアントログを確認 して MCP エラーを探す：
   - Claude Desktop：（macOS）
   - Cursor：View → Output → MCP
5. MCP サーバーを手動で実行 して起動エラーを確認：
   [CODE BLOCK]
問題：「Mind Key invalid」エラー
症状
- ツールは表示されるが呼び出しが「401 Unauthorized」で失敗
- エラー：「Mind Key fehlt oder ungültig」
解決策
1. Mind Key フォーマットを確認 —  で始まる、約 40 文字
2. 直接テスト：
   [CODE BLOCK]
3. 環境変数が設定されているか確認 — stdio トランスポートの場合、環境変数はシェルではなく MCP サーバー設定にある必要がある
4. 新しい Mind Key を取得：
   [CODE BLOCK]
問題：npx が見つからない
症状
- エラー：「npx: command not found」
- MCP サーバーが起動に失敗
解決策
1. Node.js 18+ をインストール：
   - macOS： または <https://nodejs.org> からダウンロード
   - Linux：
   - Windows：<https://nodejs.org> からダウンロード
2. インストール後にターミナルを再起動
3. 確認：
問題：SYNAPSEURL に到達できない
症状
- MCP サーバーは起動するがツール呼び出しがタイムアウト
- エラー：「fetch failed」または「ECONNREFUSED」
解決策
1. 接続をテスト：
   [CODE BLOCK]
2. 企業ファイアウォールを確認 — 送信 HTTPS をブロックしている可能性
3. 代替 URL を試す：
   - 本番：
   - MCP サーバー：
4. セルフホストの場合：Synapse インスタンスが実行中でアクセス可能であることを確認
問題：MCP サーバーがクラッシュする
症状
- MCP サーバーが起動直後に終了
- クライアントログに「MCP server disconnected」と表示
解決策
1. 手動で実行してエラーを確認：
   [CODE BLOCK]
2. ポート競合を確認 — MCP サーバーはデフォルトでポート 13100 を使用
3. npx キャッシュをクリア：
   [CODE BLOCK]
4. 最新に更新：
   [CODE BLOCK]
問題：ツール呼び出しが 429 を返す
症状
- エラー：「Rate limit exceeded」
解決策
MCP では発生しないはずです（ヘッダー認証を使用、レート制限なし）。発生した場合：
1. どこかで  を使用していないか確認 — ヘッダー認証に切り替え
2.  を確認 — 正しいインスタンスを指していることを確認
3. 問題が続く場合はサポートに連絡
問題：ツールは表示されるが動作しない
症状
- クライアントにツールがリストされる
- ツールを呼び出すとエラーまたは結果なし
解決策
1. ツール名を確認 — 正確である必要（例： ではなく ）
2. 引数を確認 — ツールの入力スキーマを確認
3. 直接 API でテスト：
   [CODE BLOCK]
4. Synapse のヘルスを確認：
   [CODE BLOCK]
ヘルプを得る
上記のいずれも問題を解決しない場合：
1. 既存の Issue を確認：<https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. 次を含めて新しい Issue を開く：
   - MCP サーバーのバージョン（）
   - クライアント名とバージョン
   - オペレーティングシステム
   - 関連ログの抜粋
   - 再現手順
次のステップ
- Claude Desktop Setup
- Claude Code Setup
- API Errors