Μετάβαση στο περιεχόμενο
Επαληθεύτηκε

MCP

Το ίδιο κλειδί API, εκτεθειμένο σε έναν πράκτορα AI ως ένα εργαλείο με τύπους ανά επιτρεπόμενη μέθοδο.

Το Xuda τρέχει έναν διακομιστή Model Context Protocol στο /mcp, δίπλα στο /cpi. Συνδέστε σε αυτόν έναν πράκτορα που υποστηρίζει MCP, με σύνδεση ή με κλειδί API, και κάθε μέθοδος που επιτρέπεται να καλέσει το κλειδί εμφανίζεται ως εργαλείο με τύπους, χωρίς ξεχωριστή ενσωμάτωση για πράκτορες AI.

Σύνδεση

Υπάρχουν δύο τρόποι εισόδου, και οι δύο καταλήγουν στο ίδιο σημείο: στα δικαιώματα ενός κλειδιού API.

Σύνδεση (συνδέσεις Claude και άλλοι πελάτες OAuth)

Προσθέστε το https://xuda.ai/mcp ως προσαρμοσμένη σύνδεση στο Claude (Settings, Connectors, Add custom connector), αφήστε κενά το αναγνωριστικό πελάτη και το μυστικό OAuth, και πατήστε Connect. Το Claude ανοίγει το Xuda: συνδεθείτε αν δεν είστε ήδη συνδεδεμένοι, και ένα παράθυρο στον πίνακα ελέγχου ρωτά ποιο από τα κλειδιά API σας θα χρησιμοποιεί η σύνδεση για να ενεργεί: επιλέξτε ένα και πατήστε Σύνδεση. Το Claude στον ιστό, στην εφαρμογή Desktop, στο κινητό και στο Cowork μοιράζονται αυτή τη σύνδεση, και κάθε άλλος λογαριασμός Claude την προσθέτει με τον ίδιο τρόπο. Η καρτέλα Προγραμματιστές, MCP του πίνακα ελέγχου δείχνει τη διεύθυνση προς επικόλληση, αυτά τα βήματα και όλα όσα ακολουθούν.

Το Claude Code συνδέεται με τον ίδιο τρόπο όταν προσθέτετε τον διακομιστή χωρίς κεφαλίδα, και μετά εκτελείτε /mcp και επιλέγετε Authenticate:

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp

Η σύνδεση δεν έχει ποτέ δικά της δικαιώματα. Κάθε κλήση εργαλείου εκτελείται ως το κλειδί που επιλέξατε, οπότε η λειτουργία πρόσβασης του κλειδιού, η λίστα επιτρεπόμενων και η ανάκλησή του ισχύουν και για τη σύνδεση: ανακαλέστε το κλειδί στους Προγραμματιστές, Κλειδιά API και η σύνδεση σταματά, και η επόμενη σύνδεση ζητά άλλο κλειδί. Η σελίδα απαριθμεί μόνο τα δικά σας ενεργά κλειδιά: αν δεν έχετε κανένα, δημιουργήστε πρώτα ένα.

Για προγραμματιστές client, ο διακομιστής ακολουθεί την προδιαγραφή εξουσιοδότησης MCP:

Μια κλήση στο /mcp χωρίς χρησιμοποιήσιμο token απαντά με 401 και WWW-Authenticate: Bearer resource_metadata="...", και έτσι ένας πελάτης βρίσκει τα υπόλοιπα. Τα access tokens διαρκούν μία ώρα. Τα refresh tokens διαρκούν 90 ημέρες και αντικαθίστανται σε κάθε χρήση. Ένα URI ανακατεύθυνσης loopback (http://localhost ή http://127.0.0.1) ταιριάζει σε οποιαδήποτε θύρα.

Κλειδί API σε κεφαλίδα

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Το κλειδί μπαίνει σε κεφαλίδα Authorization: Bearer, το ίδιο κλειδί που θα χρησιμοποιούσατε ως api_key στο /cpi. Δεν υπάρχει ξεχωριστό διαπιστευτήριο MCP. Ένα αίτημα χωρίς κεφαλίδα Authorization, ή ένα κλειδί που δεν αντιστοιχεί σε ενεργό έγγραφο xuda_api_keys, απορρίπτεται με 401 πριν καταχωριστεί οποιοδήποτε εργαλείο.

Συνεδρίες

Η μεταφορά είναι streamable HTTP: το πρώτο αίτημα είναι μια κλήση MCP initialize, που ανοίγει μια συνεδρία και επιστρέφει μια κεφαλίδα mcp-session-id. Κάθε επόμενο αίτημα σε αυτή τη σύνδεση φέρει την ίδια κεφαλίδα και το ίδιο διαπιστευτήριο. Μια συνεδρία κλείνει μετά από 10 λεπτά χωρίς αίτημα. Ένα αίτημα σε συνεδρία που έχει κλείσει απαντά με 404, και ένας πελάτης MCP ξεκινά τότε νέα συνεδρία μόνος του.

Τι γίνεται εργαλείο

Τα εργαλεία καταχωρίζονται στην αρχή της συνεδρίας από την ίδια λειτουργία πρόσβασης που έχει ήδη το κλειδί:

  • Πλήρης πρόσβαση: κάθε μέθοδος του καταλόγου που δεν είναι private καταχωρίζεται ως εργαλείο, επιλύεται τη στιγμή της σύνδεσης, οπότε μια μέθοδος που προστέθηκε μετά τη δημιουργία του κλειδιού είναι διαθέσιμη χωρίς καμία αλλαγή στο ίδιο το κλειδί.
  • Προσαρμοσμένη πρόσβαση: καταχωρίζονται μόνο οι μέθοδοι της λίστας επιτρεπόμενων του κλειδιού.

Μια συνεδρία που τρέχει ακολουθεί το κλειδί της: ελέγχει το κλειδί κάθε λεπτό, και τις ενότητες και τα plugins πίσω από αυτό κάθε πέντε, και όταν το σύνολο των εργαλείων έχει αλλάξει στέλνει notifications/tools/list_changed. Ένας πελάτης που ακούει (το Claude ακούει) διαβάζει τη νέα λίστα χωρίς επανασύνδεση, οπότε μια μέθοδος που επιτρέπετε στο κλειδί φτάνει σε έναν πράκτορα που είναι ήδη συνδεδεμένος.

Κάθε εργαλείο κρατά τη δική μορφή της μεθόδου: το όνομα του εργαλείου είναι το όνομα της μεθόδου (get_account_projects, dbs_read, ...), ο τίτλος του είναι το όνομα της μεθόδου σε Title Case, η περιγραφή του είναι η δική description της μεθόδου, και το σχήμα εισόδου του χτίζεται πεδίο προς πεδίο από τα fields της μεθόδου, τα υποχρεωτικά πεδία παραμένουν υποχρεωτικά, όλα τα άλλα είναι προαιρετικά. Ένα πεδίο χωρίς αναγνωρισμένο τύπο γίνεται παρ' όλα αυτά ένα ανεκτικό όρισμα εργαλείου αντί να χαλάσει ολόκληρη τη συνεδρία, ώστε μια περίεργα καθορισμένη μέθοδος να μην παρασύρει ποτέ τον υπόλοιπο κατάλογο.

Τα κλειδιά Full Stack VPS φέρουν επιπλέον εργαλεία

Ένα κλειδί με εύρος ένα Full Stack VPS εκθέτει επίσης τα εγκατεστημένα εργαλεία plugin εκείνου του μηχανήματος δίπλα στις μεθόδους του οικοσυστήματος παραπάνω, ώστε ένας πράκτορας να φτάνει και στην πλατφόρμα και σε ό,τι έχει χτίσει ο προγραμματιστής στο μηχάνημα σε μία συνεδρία. Δείτε το Full Stack VPS.

Κλήση ενός εργαλείου

Ένας πράκτορας καλεί ένα εργαλείο με τα ίδια ορίσματα που περιγράφουν τα πεδία της μεθόδου. Το Xuda απαντά καλώντας εσωτερικά τη μέθοδο, με τον ίδιο τρόπο που θα το έκανε το /cpi/<method>, και επιστρέφει στο εργαλείο τον φάκελο {code, data} της μεθόδου ως κείμενο. Μια αποτυχημένη κλήση εξακολουθεί να επιστρέφει κανονικά στο επίπεδο MCP, ο κωδικός -1 και κάτω εμφανίζεται στο αποτέλεσμα του εργαλείου ακριβώς όπως θα εμφανιζόταν από μια απλή κλήση REST, ώστε ένας πράκτορας να το διαβάζει με τον ίδιο τρόπο που θα το διάβαζε ο δικός σας χειρισμός σφαλμάτων. Δείτε τα Σφάλματα.

Ένα αίτημα που αποτυγχάνει πριν εκτελεστεί οποιοδήποτε εργαλείο, ένα διαπιστευτήριο που λείπει ή απορρίφθηκε (401), μια συνεδρία που έχει κλείσει (404, κωδικός -32001), ένα κακοσχηματισμένο μήνυμα MCP, επιστρέφει ως σφάλμα JSON-RPC αντί για αποτέλεσμα εργαλείου:

json
{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Bad Request: Invalid Api key" }, "id": null }

Επόμενα