# 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 サーバーを手動で実行** して起動エラーを確認：
   ```bash
   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. **直接テスト**：
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **環境変数が設定されているか確認** — stdio トランスポートの場合、環境変数はシェルではなく MCP サーバー設定にある必要がある
4. **新しい Mind Key を取得**：
   ```bash
   # 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. **接続をテスト**：
   ```bash
   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. **手動で実行してエラーを確認**：
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **ポート競合を確認** — MCP サーバーはデフォルトでポート 13100 を使用
3. **npx キャッシュをクリア**：
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **最新に更新**：
   ```bash
   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 でテスト**：
   ```bash
   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 のヘルスを確認**：
   ```bash
   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](/docs/mcp/claude-desktop)
- [Claude Code Setup](/docs/mcp/claude-code)
- [API Errors](/docs/api/errors)