Усунення несправностей

Більшість збоїв налаштування потрапляють в одну з чотирьох категорій: API-ключ не доходить до сервера, міст @maguyva/mcp не запускається, репозиторій не вдається визначити, або клієнт узагалі не може підключитися. Перейдіть до розділу, що відповідає вашому симптому.

Кожен запит автентифікується вашим API-ключем, який надсилається як заголовок Authorization: Bearer або, якщо клієнт не може його встановити, як заголовок X-API-Key. Якщо виклики інструментів відхиляються:

• Перевірте, що ваш ключ починається з префікса mgv_.
• Перевірте, що ви замінили заглушку mgv_xxxx з прикладів конфігурації на свій реальний ключ із app.maguyva.ai.
• Якщо ваша конфігурація зчитує ключ зі змінної MAGUYVA_API_KEY, переконайтеся, що вона встановлена в тому середовищі, з якого фактично запускається ваш клієнт. Shell-експорти, додані до ~/.zshrc або ~/.bashrc, застосовуються лише після перезавантаження оболонки — а GUI-застосунки можуть їх взагалі не успадковувати. Якщо сумніваєтеся, впишіть ключ безпосередньо в конфігурацію: у заголовок Authorization нативної віддаленої конфігурації (Bearer, а за ним ваш ключ) або в блок env конфігурації з мостом @maguyva/mcp.
• Переконайтеся, що термін дії ключа не сплив і що його не відкликано.

Якщо клієнт використовує міст @maguyva/mcp, він запускає локальний процес, який підключається до віддаленого сервера Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Якщо сервер узагалі не з'являється у вашому клієнті або з'являється й одразу відключається:

• Перевірте, що npx доступний у вашому PATH — мосту потрібна робоча інсталяція Node.js. Виконайте npx -y @maguyva/mcp --help у терміналі, щоб переконатися, що він запускається.
• Перевірте синтаксис конфігурації MCP вашого клієнта — некоректно сформований JSON-файл у деяких клієнтах не викликає явної помилки.
• Багатьом клієнтам міст узагалі не потрібен. Claude Code використовує плагін Maguyva (/plugin install maguyva@maguyva), а Cursor, VS Code, Devin Desktop і Zed підключаються до віддаленого сервера нативно з заголовком Bearer (Zed — через context_servers). Міст потрібен клієнтам, які не можуть надіслати цей заголовок зі своєї конфігурації, як-от Claude Desktop: його claude_desktop_config.json запускає лише локальні сервери. Користувацькі конектори Claude Desktop можуть надсилати заголовок запиту authorization, але заголовки запитів доступні в бета-версії лише обмеженій кількості організацій.

• Переконайтеся, що репозиторій підключено та проіндексовано в app.maguyva.ai.
• Перевірте формат: "owner/repo" націлюється на гілку за замовчуванням, "owner/repo:branch" — на конкретну гілку (наприклад, "owner/repository:develop").
• Переконайтеся, що ваш обліковий запис має доступ до репозиторію.
• Використайте repository_context(action="info", repository="..."), щоб перевірити визначення репозиторію; пропускайте параметр repository лише коли ваш клієнт MCP надає значення за замовчуванням у межах запиту або ключ має доступ лише до одного репозиторію.

• Перевірте з'єднання з https://maguyva.tools/mcp зі своєї машини — зазвичай винні корпоративні проксі та фаєрволи.
• Перевірте, що ваш API-токен дійсний і не прострочений.
• Перевірте конфігурацію свого клієнта за інструкціями з розділу «Гайд зі встановлення» — розташування та формат файлу конфігурації відрізняються залежно від клієнта.

Після будь-якої зміни запитайте у свого агента "Які репозиторії в мене підключено?" — це перевіряє з'єднання наскрізно. Потім поставте справжнє запитання про свій репозиторій; ви маєте побачити відповіді зі шляхами до файлів і номерами рядків із вашого підключеного репозиторію.