Αντιμετώπιση προβλημάτων

Οι περισσότερες αποτυχίες ρύθμισης εμπίπτουν σε τέσσερις κατηγορίες: το κλειδί 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 του Claude Desktop.

Το αποθετήριο δεν βρέθηκε#

• Βεβαιωθείτε ότι το αποθετήριο είναι συνδεδεμένο και ευρετηριασμένο στο app.maguyva.ai.
• Ελέγξτε τη μορφή: Το "owner/repo" στοχεύει τον προεπιλεγμένο κλάδο, το "owner/repo:branch" στοχεύει έναν συγκεκριμένο κλάδο (π.χ. "owner/repository:develop").
• Βεβαιωθείτε ότι ο λογαριασμός σας έχει πρόσβαση στο αποθετήριο.
• Χρησιμοποιήστε το repository_context(action="info", repository="...") για να ελέγξετε πώς επιλύεται το αποθετήριο· παραλείψτε την παράμετρο repository μόνο όταν ο MCP client παρέχει προεπιλογή για το συγκεκριμένο αίτημα ή όταν το κλειδί έχει πρόσβαση σε ακριβώς ένα αποθετήριο.

Προβλήματα σύνδεσης MCP#

• Δοκίμασε τη συνδεσιμότητα με το https://maguyva.tools/mcp από το μηχάνημά σου — οι εταιρικοί διαμεσολαβητές και τα τείχη προστασίας είναι συνήθως οι ένοχοι.
• Έλεγξε ότι το διακριτικό API σου είναι έγκυρο και δεν έχει λήξει.
• Επανέλεγξε τη ρύθμιση του πελάτη σε σχέση με το Οδηγός Εγκατάστασης για τον πελάτη σου — η θέση και η μορφή του αρχείου ρύθμισης διαφέρουν ανά πελάτη.

Επιβεβαίωσε τη διόρθωση#

Μετά από οποιαδήποτε αλλαγή, ρώτησε τον πράκτορά σου "Ποια αποθετήρια έχω συνδεδεμένα;" — αυτό επιβεβαιώνει τη σύνδεση από άκρη σε άκρη. Στη συνέχεια κάνε μια πραγματική ερώτηση για το αποθετήριό σου· θα πρέπει να δεις απαντήσεις με διαδρομές αρχείων και αριθμούς γραμμών από το συνδεδεμένο αποθετήριό σου.