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

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

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

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

• Перевірте, що ваш ключ починається з префікса mgv_.
• Перевірте, що ви замінили плейсхолдер mgv_xxxx з прикладів конфігурації на свій реальний ключ із app.maguyva.ai.
• Якщо ваша конфігурація зчитує ключ зі змінної MAGUYVA_API_KEY, переконайтеся, що вона встановлена в тому середовищі, з якого фактично запускається ваш клієнт. Shell-експорти, додані до ~/.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-конектори Claude Desktop.

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

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

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

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

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

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