Vianmääritys

Useimmat asennusvirheet jakautuvat neljään ryhmään: API-avain ei saavuta palvelinta, mcp-remote-silta ei käynnisty, repositoriota ei voida ratkaista, tai asiakasohjelma ei saa yhteyttä lainkaan. Käy läpi osio, joka vastaa oiretta.

API-avainongelmat#

Jokainen pyyntö todentaa API-avaimellasi, joka lähetetään Authorization: Bearer-otsikkona. Jos työkalukutsut hylätään:

• Varmista, että avaimesi alkaa mgv_-etuliitteellä.
• Tarkista, että korvasit konfiguraatioesimerkkien mgv_xxxx-paikkamerkin oikealla avaimellasi osoitteesta app.maguyva.ai.
• Jos konfiguraatiosi lukee avaimen muuttujasta MAGUYVA_API_KEY, varmista, että muuttuja on asetettu ympäristössä, josta asiakasohjelmasi oikeasti käynnistyy. Tiedostoihin ~/.zshrc tai ~/.bashrc lisätyt shell-exportit tulevat voimaan vasta shellin uudelleenlatauksen jälkeen — eivätkä GUI-sovellukset välttämättä peri niitä lainkaan. Jos olet epävarma, laita avain konfiguraation env-lohkoon.
• Varmista, ettei avain ole vanhentunut tai peruutettu.

mcp-remote-sillan ongelmat#

Useimmat dokumentoidut asiakasohjelmakonfiguraatiot käynnistävät paikallisen siltaprosessin, joka välittää stdio MCP -liikenteen etäpalvelimelle:

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

Jos palvelin ei koskaan näy asiakasohjelmassasi, tai näkyy ja katkeaa heti:

• Varmista, että npx on saatavilla PATH-muuttujassasi — silta tarvitsee toimivan Node.js-asennuksen. Aja npx -y mcp-remote --help terminaalissa varmistaaksesi, että se voi käynnistyä.
• Tarkista asiakasohjelmasi MCP-konfiguraation syntaksi — virheellinen JSON-tiedosto epäonnistuu hiljaisesti joissakin asiakasohjelmissa.
• Monet asiakasohjelmat eivät tarvitse siltaa lainkaan. Claude Code käyttää Maguyva-liitännäistä (/plugin install maguyva@maguyva), ja Cursor, VS Code, Windsurf ja Zed yhdistävät etäpalvelimeen natiivisti Bearer-otsikolla (Zed context_servers:n kautta). Silta on tarkoitettu vain asiakasohjelmille, joilla ei ole natiivia etäotsikkotukea, kuten Claude Desktop -sovelluksen pelkästään OAuth:iin perustuville liittimille.

Repositoriota ei löydy#

• Varmista, että repository on yhdistetty ja indeksoitu palvelussa app.maguyva.ai.
• Tarkista muoto: "owner/repo" kohdistuu oletushaaraan, "owner/repo:branch" tiettyyn haaraan (esim. "owner/repository:develop").
• Varmista, että tililläsi on pääsy repositoryyn.
• Tarkista komennolla repository_context(action="info", repository="..."), miten repository ratkaistaan; jätä repository-parametri pois vain, kun MCP-asiakas antaa pyyntökohtaisen oletuksen tai kun avaimella on pääsy täsmälleen yhteen repositoryyn.

MCP-yhteysongelmat#

• Testaa yhteyttä osoitteeseen https://maguyva.tools/mcp koneeltasi — yritysproxyt ja palomuurit ovat tavallisimmat syylliset.
• Tarkista, että API-tokenisi on voimassa eikä vanhentunut.
• Tarkista asiakasohjelmasi konfiguraatio uudelleen Asennusopas-oppaasta — konfiguraatiotiedoston sijainti ja muoto vaihtelevat asiakasohjelmittain.

Varmista korjaus#

Minkä tahansa muutoksen jälkeen kysy agentiltasi "Mitkä repositoriot minulla on yhdistettynä?" — se varmistaa yhteyden päästä päähän. Kysy sitten oikea kysymys repostasi; sinun pitäisi nähdä vastauksia tiedostopolkuineen ja rivinumeroineen yhdistetystä repositoriostasi.