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

Canonical source: https://maguyva.ai/uk/docs/troubleshooting

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Виправте типові помилки налаштування Maguyva: проблеми з API-ключем, проблеми моста @maguyva/mcp, пошук репозиторію та помилки з'єднання.

### Проблеми з API-ключем

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

### Проблеми моста @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 надає значення за замовчуванням у межах запиту або ключ має доступ лише до одного репозиторію.

### Проблеми з'єднання MCP

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

### Перевірте виправлення

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