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

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

Каждый запрос аутентифицируется вашим API-ключом, который отправляется в заголовке Authorization: Bearer или, если клиент не может его задать, в заголовке X-API-Key. Если вызовы инструментов отклоняются:

• Убедитесь, что ваш ключ начинается с префикса mgv_.
• Проверьте, что вы заменили заглушку mgv_xxxx из примеров конфигурации на свой реальный ключ из app.maguyva.ai.
• Если ваша конфигурация читает ключ из MAGUYVA_API_KEY, убедитесь, что переменная задана в той среде, из которой реально запускается ваш клиент. Экспорты в оболочке, добавленные в ~/.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="..."), чтобы проверить разрешение репозитория; не указывайте параметр репозитория только тогда, когда MCP-клиент задаёт значение по умолчанию для запроса или ключ имеет доступ ровно к одному репозиторию.

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

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