# Устранение неполадок

Canonical source: https://maguyva.ai/ru/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, убедитесь, что переменная задана в той среде, из которой реально запускается ваш клиент. Экспорты в оболочке, добавленные в ~/.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="..."), чтобы проверить разрешение репозитория; не указывайте параметр репозитория только тогда, когда MCP-клиент задаёт значение по умолчанию для запроса или ключ имеет доступ ровно к одному репозиторию.

### Проблемы подключения MCP

- Проверьте соединение с https://maguyva.tools/mcp со своей машины — обычно виноваты корпоративные прокси и файрволы.
- Проверьте, что ваш API-токен действителен и не истёк.
- Перепроверьте конфигурацию клиента по руководству по установке для вашего клиента — расположение и формат конфигурационного файла отличаются у разных клиентов.

### Проверка исправления

После любого изменения спросите у своего агента «Какие репозитории у меня подключены?» — это проверит соединение целиком. Затем задайте реальный вопрос о своём репозитории; вы должны увидеть ответы с путями к файлам и номерами строк из вашего подключённого репозитория.