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

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

Проблемы с API-ключом#

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

• Убедитесь, что ваш ключ начинается с префикса mgv_.
• Проверьте, что вы заменили плейсхолдер mgv_xxxx из примеров конфигурации на свой реальный ключ из app.maguyva.ai.
• Если ваша конфигурация читает ключ из MAGUYVA_API_KEY, убедитесь, что переменная задана в той среде, из которой реально запускается ваш клиент. Экспорты в оболочке, добавленные в ~/.zshrc или ~/.bashrc, применяются только после перезагрузки оболочки — а GUI-приложения могут вообще их не наследовать. Если сомневаетесь, поместите ключ в блок env конфигурации.
• Убедитесь, что срок действия ключа не истёк и он не был отозван.

Проблемы с мостом mcp-remote#

Большинство документированных конфигураций клиентов запускают локальный процесс-мост, который перенаправляет stdio MCP-трафик на удалённый сервер:

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

Если сервер вообще не появляется в вашем клиенте или появляется и сразу отключается:

• Убедитесь, что npx доступен в вашем PATH — мосту нужна рабочая установка Node.js. Выполните npx -y mcp-remote --help в терминале, чтобы проверить, что он запускается.
• Проверьте синтаксис MCP-конфигурации вашего клиента — в некоторых клиентах некорректный JSON-файл приводит к молчаливому сбою.
• Многим клиентам мост вообще не нужен. Claude Code использует плагин Maguyva (/plugin install maguyva@maguyva), а Cursor, VS Code, Windsurf и Zed подключаются к удалённому серверу нативно с заголовком Bearer (Zed — через context_servers). Мост нужен только клиентам без нативной поддержки удалённого заголовка, таким как OAuth-only коннекторы Claude Desktop.

Репозиторий не найден#

• Убедитесь, что репозиторий подключён и проиндексирован в app.maguyva.ai.
• Проверьте формат: "owner/repo" указывает на ветку по умолчанию, "owner/repo:branch" указывает на конкретную ветку (например, "owner/repository:develop").
• Убедитесь, что у вашего аккаунта есть доступ к репозиторию.
• Используйте repository_context(action="info", repository="..."), чтобы проверить разрешение репозитория; не указывайте параметр репозитория только тогда, когда MCP-клиент задаёт значение по умолчанию для запроса или ключ имеет доступ ровно к одному репозиторию.

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

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

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

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