MCP トラブルシューティング

Synapse MCP を LLM クライアントに連携する際のよくある問題と解決策。

クイック診断チェックリスト

1. ✅ Node.js 18+ がインストール済み？（node --version）
2. ✅ Mind Key が mk_ で始まる？（JWT eyJ... ではない）
3. ✅ Synapse API に到達可能？（curl https://synapse.schaefer.zone/health）
4. ✅ Mind Key が動作する？（curl -H "Authorization: Bearer mk_..." .../memory/recall）
5. ✅ 設定ファイルが有効な JSON？（末尾のカンマなし、コメントなし）
6. ✅ 設定変更後にクライアントを再起動した？
7. ✅ MCP サーバーが手動で起動する？（npx -y synapse-mcp-api@latest）

問題：クライアントにツールが表示されない

症状

• Claude Desktop / Cursor / Continue が 0 ツールを表示
• MCP サーバーリストに 🔌 アイコンや「synapse」エントリがない

解決策

1. クライアントを完全に再起動 — macOS では Cmd+Q（ウィンドウを閉じるだけではない）
2. 設定ファイルの場所を確認：
   • Claude Desktop macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Cursor：~/.cursor/config.json
   • Continue：~/.continue/config.json
3. JSON を検証 — 設定を https://jsonlint.com に貼り付け
4. クライアントログを確認 して MCP エラーを探す：
   • Claude Desktop：~/Library/Logs/Claude/mcp.log（macOS）
   • Cursor：View → Output → MCP
5. MCP サーバーを手動で実行 して起動エラーを確認：

   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

問題：「Mind Key invalid」エラー

症状

• ツールは表示されるが呼び出しが「401 Unauthorized」で失敗
• エラー：「Mind Key fehlt oder ungültig」

解決策

1. Mind Key フォーマットを確認 — mk_ で始まる、約 40 文字
2. 直接テスト：

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

3. 環境変数が設定されているか確認 — stdio トランスポートの場合、環境変数はシェルではなく MCP サーバー設定にある必要がある
4. 新しい Mind Key を取得：

   # Login to get JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Create new mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

問題：npx が見つからない

症状

• エラー：「npx: command not found」
• MCP サーバーが起動に失敗

解決策

1. Node.js 18+ をインストール：
   • macOS：brew install node または https://nodejs.org からダウンロード
   • Linux：curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows：https://nodejs.org からダウンロード
2. インストール後にターミナルを再起動
3. 確認：node --version && npx --version

問題：SYNAPSE_URL に到達できない

症状

• MCP サーバーは起動するがツール呼び出しがタイムアウト
• エラー：「fetch failed」または「ECONNREFUSED」

解決策

1. 接続をテスト：

   curl https://synapse.schaefer.zone/health

2. 企業ファイアウォールを確認 — 送信 HTTPS をブロックしている可能性
3. 代替 URL を試す：
   • 本番：https://synapse.schaefer.zone
   • MCP サーバー：https://synapse-mcp.schaefer.zone
4. セルフホストの場合：Synapse インスタンスが実行中でアクセス可能であることを確認

問題：MCP サーバーがクラッシュする

症状

• MCP サーバーが起動直後に終了
• クライアントログに「MCP server disconnected」と表示

解決策

1. 手動で実行してエラーを確認：

   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest

2. ポート競合を確認 — MCP サーバーはデフォルトでポート 13100 を使用
3. npx キャッシュをクリア：

   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx

4. 最新に更新：

   npx -y synapse-mcp-api@latest --version

問題：ツール呼び出しが 429 を返す

症状

• エラー：「Rate limit exceeded」

解決策

MCP では発生しないはずです（ヘッダー認証を使用、レート制限なし）。発生した場合：

1. どこかで ?key= を使用していないか確認 — ヘッダー認証に切り替え
2. SYNAPSE_URL を確認 — 正しいインスタンスを指していることを確認
3. 問題が続く場合はサポートに連絡

問題：ツールは表示されるが動作しない

症状

• クライアントにツールがリストされる
• ツールを呼び出すとエラーまたは結果なし

解決策

1. ツール名を確認 — 正確である必要（例：memory.recall ではなく memory_recall）
2. 引数を確認 — ツールの入力スキーマを確認
3. 直接 API でテスト：

   curl -X POST https://synapse.schaefer.zone/memory \
     -H "Authorization: Bearer mk_..." \
     -H "Content-Type: application/json" \
     -d '{"category":"fact","key":"test","content":"hello"}'

4. Synapse のヘルスを確認：

   curl https://synapse.schaefer.zone/health

ヘルプを得る

上記のいずれも問題を解決しない場合：

1. 既存の Issue を確認：https://gitlab.com/schaefer-services/synapse-mcp/-/issues
2. 次を含めて新しい Issue を開く：
   • MCP サーバーのバージョン（npx -y synapse-mcp-api@latest --version）
   • クライアント名とバージョン
   • オペレーティングシステム
   • 関連ログの抜粋
   • 再現手順

次のステップ

• Claude Desktop Setup
• Claude Code Setup
• API Errors