# MCP समस्या निवारण

Synapse MCP को अपने LLM client के साथ एकीकृत करते समय सामान्य समस्याएँ और समाधान।

## त्वरित डायग्नोस्टिक चेकलिस्ट

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. ✅ कॉन्फ़िग परिवर्तन के बाद client पुनः आरंभ किया?
7. ✅ MCP server मैन्युअली शुरू होता है? (`npx -y synapse-mcp-api@latest`)

## समस्या: Client में कोई टूल दिखाई नहीं देता

### लक्षण

- Claude Desktop / Cursor / Continue 0 टूल दिखाता है
- MCP servers सूची में कोई 🔌 आइकन या "synapse" एंट्री नहीं

### समाधान

1. **Client पूरी तरह पुनः आरंभ करें** — 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 त्रुटियों के लिए client लॉग जाँचें**:
   - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)
   - Cursor: View → Output → MCP
5. **स्टार्टअप त्रुटियाँ देखने के लिए MCP server मैन्युअली चलाएँ**:
   ```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. **जाँचें कि env var सेट है** — stdio ट्रांसपोर्ट के लिए, env var आपके शेल में नहीं, MCP server कॉन्फ़िग में होना चाहिए
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 server शुरू होने में विफल

### समाधान

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 server शुरू होता है लेकिन टूल कॉल टाइमआउट हो जाते हैं
- त्रुटि: "fetch failed" या "ECONNREFUSED"

### समाधान

1. **कनेक्टिविटी टेस्ट करें**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```
2. **कॉर्पोरेट फ़ायरवॉल जाँचें** — आउटबाउंड HTTPS को ब्लॉक कर सकता है
3. **वैकल्पिक URL आज़माएँ**:
   - Production: `https://synapse.schaefer.zone`
   - MCP server: `https://synapse-mcp.schaefer.zone`
4. **सेल्फ-होस्टेड के लिए**: सुनिश्चित करें कि आपका Synapse इंस्टेंस चल रहा है और पहुँच योग्य है

## समस्या: MCP Server क्रैश

### लक्षण

- MCP server शुरू होने के तुरंत बाद बाहर निकलता है
- Client लॉग "MCP server disconnected" दिखाते हैं

### समाधान

1. **त्रुटि देखने के लिए मैन्युअली चलाएँ**:
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **पोर्ट संघर्ष की जाँच करें** — MCP server डिफ़ॉल्ट रूप से पोर्ट 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 के साथ नहीं होना चाहिए (हेडर auth का उपयोग करता है, कोई रेट लिमिट नहीं)। यदि होता है:

1. **जाँचें कि कहीं आप `?key=` का उपयोग तो नहीं कर रहे** — हेडर auth पर स्विच करें
2. **`SYNAPSE_URL` सत्यापित करें** — सुनिश्चित करें कि यह सही इंस्टेंस की ओर इशारा करता है
3. **सहायता से संपर्क करें** यदि समस्या बनी रहे

## समस्या: टूल दिखाई देते हैं लेकिन काम नहीं करते

### लक्षण

- Client में टूल सूचीबद्ध हैं
- टूल कॉल करने पर त्रुटि या कोई परिणाम नहीं

### समाधान

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. **मौजूदा issues जाँचें**: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. **नया issue खोलें** इनके साथ:
   - MCP server संस्करण (`npx -y synapse-mcp-api@latest --version`)
   - Client नाम और संस्करण
   - ऑपरेटिंग सिस्टम
   - संबंधित लॉग अंश
   - पुनः उत्पन्न करने के चरण

## अगले कदम

- [Claude Desktop Setup](/docs/mcp/claude-desktop)
- [Claude Code Setup](/docs/mcp/claude-code)
- [API Errors](/docs/api/errors)