{"title":"MCP トラブルシューティング","slug":"troubleshooting","category":"mcp","summary":"よくある MCP 連携の問題を解決 — サーバーが起動しない、ツールが表示されない、認証エラー。","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":322,"read_minutes":2,"llm_context":"Common issues:\n1. Node.js < 18 → upgrade to 18+\n2. Mind Key invalid → check format (mk_...), get fresh via POST /minds\n3. npx not found → install Node.js\n4. Tools not appearing → restart client, check config JSON validity\n5. SYNAPSE_URL unreachable → curl /health to verify\n6. MCP server crashes → check logs, run npx manually to see error\nDebug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr\nLogs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/\n","lang":"ja","translated":true,"requested_lang":"ja","content_markdown":"\n# MCP トラブルシューティング\n\nSynapse MCP を LLM クライアントに連携する際のよくある問題と解決策。\n\n## クイック診断チェックリスト\n\n1. ✅ Node.js 18+ がインストール済み？（`node --version`）\n2. ✅ Mind Key が `mk_` で始まる？（JWT `eyJ...` ではない）\n3. ✅ Synapse API に到達可能？（`curl https://synapse.schaefer.zone/health`）\n4. ✅ Mind Key が動作する？（`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`）\n5. ✅ 設定ファイルが有効な JSON？（末尾のカンマなし、コメントなし）\n6. ✅ 設定変更後にクライアントを再起動した？\n7. ✅ MCP サーバーが手動で起動する？（`npx -y synapse-mcp-api@latest`）\n\n## 問題：クライアントにツールが表示されない\n\n### 症状\n\n- Claude Desktop / Cursor / Continue が 0 ツールを表示\n- MCP サーバーリストに 🔌 アイコンや「synapse」エントリがない\n\n### 解決策\n\n1. **クライアントを完全に再起動** — macOS では Cmd+Q（ウィンドウを閉じるだけではない）\n2. **設定ファイルの場所を確認**：\n - Claude Desktop macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`\n - Claude Desktop Windows：`%APPDATA%\\Claude\\claude_desktop_config.json`\n - Cursor：`~/.cursor/config.json`\n - Continue：`~/.continue/config.json`\n3. **JSON を検証** — 設定を に貼り付け\n4. **クライアントログを確認** して MCP エラーを探す：\n - Claude Desktop：`~/Library/Logs/Claude/mcp.log`（macOS）\n - Cursor：View → Output → MCP\n5. **MCP サーバーを手動で実行** して起動エラーを確認：\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## 問題：「Mind Key invalid」エラー\n\n### 症状\n\n- ツールは表示されるが呼び出しが「401 Unauthorized」で失敗\n- エラー：「Mind Key fehlt oder ungültig」\n\n### 解決策\n\n1. **Mind Key フォーマットを確認** — `mk_` で始まる、約 40 文字\n2. **直接テスト**：\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **環境変数が設定されているか確認** — stdio トランスポートの場合、環境変数はシェルではなく MCP サーバー設定にある必要がある\n4. **新しい Mind Key を取得**：\n ```bash\n # Login to get JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Create new mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## 問題：npx が見つからない\n\n### 症状\n\n- エラー：「npx: command not found」\n- MCP サーバーが起動に失敗\n\n### 解決策\n\n1. **Node.js 18+ をインストール**：\n - macOS：`brew install node` または からダウンロード\n - Linux：`curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows： からダウンロード\n2. インストール後に**ターミナルを再起動**\n3. **確認**：`node --version && npx --version`\n\n## 問題：SYNAPSE_URL に到達できない\n\n### 症状\n\n- MCP サーバーは起動するがツール呼び出しがタイムアウト\n- エラー：「fetch failed」または「ECONNREFUSED」\n\n### 解決策\n\n1. **接続をテスト**：\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **企業ファイアウォールを確認** — 送信 HTTPS をブロックしている可能性\n3. **代替 URL を試す**：\n - 本番：`https://synapse.schaefer.zone`\n - MCP サーバー：`https://synapse-mcp.schaefer.zone`\n4. **セルフホストの場合**：Synapse インスタンスが実行中でアクセス可能であることを確認\n\n## 問題：MCP サーバーがクラッシュする\n\n### 症状\n\n- MCP サーバーが起動直後に終了\n- クライアントログに「MCP server disconnected」と表示\n\n### 解決策\n\n1. **手動で実行してエラーを確認**：\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **ポート競合を確認** — MCP サーバーはデフォルトでポート 13100 を使用\n3. **npx キャッシュをクリア**：\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **最新に更新**：\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## 問題：ツール呼び出しが 429 を返す\n\n### 症状\n\n- エラー：「Rate limit exceeded」\n\n### 解決策\n\nMCP では発生しないはずです（ヘッダー認証を使用、レート制限なし）。発生した場合：\n\n1. **どこかで `?key=` を使用していないか確認** — ヘッダー認証に切り替え\n2. **`SYNAPSE_URL` を確認** — 正しいインスタンスを指していることを確認\n3. 問題が続く場合は**サポートに連絡**\n\n## 問題：ツールは表示されるが動作しない\n\n### 症状\n\n- クライアントにツールがリストされる\n- ツールを呼び出すとエラーまたは結果なし\n\n### 解決策\n\n1. **ツール名を確認** — 正確である必要（例：`memory.recall` ではなく `memory_recall`）\n2. **引数を確認** — ツールの入力スキーマを確認\n3. **直接 API でテスト**：\n ```bash\n curl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer mk_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\":\"fact\",\"key\":\"test\",\"content\":\"hello\"}'\n ```\n4. **Synapse のヘルスを確認**：\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## ヘルプを得る\n\n上記のいずれも問題を解決しない場合：\n\n1. **既存の Issue を確認**：\n2. 次を含めて**新しい Issue を開く**：\n - MCP サーバーのバージョン（`npx -y synapse-mcp-api@latest --version`）\n - クライアント名とバージョン\n - オペレーティングシステム\n - 関連ログの抜粋\n - 再現手順\n\n## 次のステップ\n\n- [Claude Desktop Setup](/docs/mcp/claude-desktop)\n- [Claude Code Setup](/docs/mcp/claude-code)\n- [API Errors](/docs/api/errors)\n","content_html":"

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

\n

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

\n

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

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

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

\n

症状

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

解決策

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

問題：「Mind Key invalid」エラー

\n

症状

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

解決策

\n
    \n
  1. Mind Key フォーマットを確認 — mk_ で始まる、約 40 文字
    2. \n
  2. 直接テスト：
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  3. 環境変数が設定されているか確認 — stdio トランスポートの場合、環境変数はシェルではなく MCP サーバー設定にある必要がある
    4. \n
  4. 新しい Mind Key を取得：
    # Login to get JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# Create new mind\ncurl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
    5. \n
\n

問題：npx が見つからない

\n

症状

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

解決策

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

問題：SYNAPSE_URL に到達できない

\n

症状

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

解決策

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

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

\n

症状

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

解決策

\n
    \n
  1. 手動で実行してエラーを確認：
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. ポート競合を確認 — MCP サーバーはデフォルトでポート 13100 を使用
    3. \n
  3. npx キャッシュをクリア：
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. 最新に更新：
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

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

\n

症状

\n
    \n
  • エラー：「Rate limit exceeded」
    • \n
\n

解決策

\n

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

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

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

\n

症状

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

解決策

\n
    \n
  1. ツール名を確認 — 正確である必要（例：memory.recall ではなく memory_recall）
    2. \n
  2. 引数を確認 — ツールの入力スキーマを確認
    3. \n
  3. 直接 API でテスト：
    curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer mk_..." \\\n  -H "Content-Type: application/json" \\\n  -d '{"category":"fact","key":"test","content":"hello"}'
    4. \n
  4. Synapse のヘルスを確認：
    curl https://synapse.schaefer.zone/health
    5. \n
\n

ヘルプを得る

\n

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

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

次のステップ

\n\n","urls":{"html":"/docs/mcp/troubleshooting","text":"/docs/mcp/troubleshooting?format=text","json":"/docs/mcp/troubleshooting?format=json","llm":"/docs/mcp/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}