Τεκμηρίωση / MCP

Ο διακομιστής MCP

Το HyperCRM εκθέτει το API του μέσω του Model Context Protocol ως ένα endpoint JSON-RPC, ώστε ένας MCP client να δουλεύει με ασθενείς, ραντεβού, χρεώσεις, φόρμες, αρχεία και αναφορές — με την ίδια εμβέλεια ιατρείου και τους ίδιους ρόλους που ισχύουν στο REST API.

Ποιο πακέτο χρειάζεται

Το REST API και ο MCP server περιλαμβάνονται στο πακέτο Complete και δεν διατίθενται στο Essential — οι ενσωματώσεις είναι ανάγκη μεγαλύτερων ιατρείων και πραγματικό φορτίο υποστήριξης, οπότε βρίσκονται στο πακέτο που τις πληρώνει. Η σελίδα τιμών έχει κάθε κλιμάκιο. Οι OAuth clients δημιουργούνται από τις ρυθμίσεις του ιατρείου μόλις βρεθείτε στο Complete.

Τι περιλαμβάνει

60 εργαλεία — 38 αναγνώσεις, 22 εγγραφές, για ασθενείς, ραντεβού, χρεώσεις, αποδείξεις και τιμολόγια, φόρμες, αρχεία, καταλόγους (έδρες, υπηρεσίες, ετικέτες), ιατρείο και προσωπικό, αναφορές και αναζήτηση, ειδοποιήσεις, και τον κατασκευαστή ιστοσελίδας. Καθένα στηρίζεται στις ίδιες υπηρεσίες, επικυρώσεις και άδειες με το REST API, οπότε ένας agent δεν φτάνει πουθενά όπου δεν θα έφτανε ένα συνδεδεμένο μέλος του ιατρείου.

Δεν εκτίθενται resources ούτε prompts — τα resources/list και prompts/list επιστρέφουν κενά. Τα εργαλεία είναι όλη η επιφάνεια.

Σύνδεση

Ένα endpoint, POST /api/v1/mcp, με JSON-RPC 2.0 πάνω από streamable HTTP:

{
  "mcpServers": {
    "hypercrm": {
      "type": "http",
      "url": "https://your-hypercrm-origin/api/v1/mcp"
    }
  }
}

Το OPTIONS /api/v1/mcp απαντά στο preflight CORS. Το endpoint δεν στέλνει κεφαλίδα Access-Control-Allow-Credentials, και αυτό είναι ασφαλές ακριβώς επειδή κάθε κλήση απαιτεί ρητό bearer token και όχι cookie — μια σελίδα άλλης προέλευσης δεν μπορεί να εκμεταλλευτεί τη συνεδρία ενός συνδεδεμένου χρήστη.

Εξουσιοδότηση

Κάθε κλήση εργαλείου απαιτεί Authorization: Bearer <token>. Ο διακομιστής υλοποιεί την προδιαγραφή εξουσιοδότησης MCP: OAuth 2.1 με υποχρεωτικό PKCE (S256), έγγραφα μεταδεδομένων για τον προστατευόμενο πόρο και τον διακομιστή εξουσιοδότησης, και δυναμική καταχώριση client. Γίνεται επίσης δεκτό ένα Firebase ID token, που είναι ο απλούστερος δρόμος αν έχετε ήδη ένα.

Τα access token διαρκούν περίπου μία ώρα και τα refresh token 30 ημέρες· το refresh token εναλλάσσεται σε κάθε χρήση, οπότε ένα διαρρεύσαν token δουλεύει μόνο μία φορά. Τα token είναι αδιαφανείς τυχαίες συμβολοσειρές, ποτέ JWT, και αποθηκεύεται μόνο το hash τους.

Εμβέλεια ιατρείου

Το practiceId προέρχεται πάντα από το token και ποτέ από παράμετρο εργαλείου. Κανένα σχήμα εισόδου δεν το δηλώνει, και οι διαδρομές εγγραφής αφαιρούν οποιοδήποτε practiceId στείλει ο client πριν φτάσει σε υπηρεσία. Αυτό επιβάλλεται από τεστ σε όλα τα 60 εργαλεία και δεν αφήνεται στην προσοχή του αναθεωρητή: ένα μόνο εργαλείο που δεχόταν practice id θα μετέτρεπε τον διακομιστή σε ανάγνωση άλλων ιατρείων.

Ρόλοι

Το MCP επιβάλλει τους ίδιους περιορισμούς ιδιοκτήτη με το REST API. Οι αναφορές, το ιστορικό ελέγχου, όλα τα εργαλεία φορμών (και οι αναγνώσεις), οι ρυθμίσεις ιατρείου, οι προσκλήσεις, οι αλλαγές προσωπικού και κάθε εγγραφή στην ιστοσελίδα απαιτούν ρόλο ιδιοκτήτη· οι ασθενείς, τα ραντεβού, τα αρχεία, οι ειδοποιήσεις και οι αναγνώσεις καταλόγων είναι ανοιχτά σε κάθε μέλος. Ο κατάλογος εργαλείων το σημειώνει ανά εργαλείο.

Σφάλματα

Ένα εργαλείο που αποτυγχάνει επιστρέφει και πάλι HTTP 200 με έγκυρο φάκελο JSON-RPC. Η αποτυχία αναφέρεται μέσα στο αποτέλεσμα:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "status": 400,
      "ok": false,
      "error": {
        "code": "validation_failed",
        "message": "Request validation failed.",
        "details": [{ "path": ["firstName"], "message": "firstName is required" }]
      }
    }
  }
}

Είναι το ίδιο σχήμα σφάλματος που επιστρέφει το REST API, οπότε ένας χειριστής σφαλμάτων καλύπτει και τις δύο επιφάνειες. Τα προβλήματα σε επίπεδο μεταφοράς — κακοσχηματισμένο JSON, άγνωστη μέθοδος, λανθασμένες παράμετροι — επιστρέφουν HTTP 400 με αντικείμενο σφάλματος JSON-RPC (-32700, -32600, -32601, -32602, -32603).

Η μόνη εξαίρεση είναι ένα διαπιστευτήριο που λείπει, είναι άκυρο ή έχει λήξει: σύμφωνα με την προδιαγραφή λαμβάνει HTTP 401 με κεφαλίδα WWW-Authenticate που δείχνει στο έγγραφο μεταδεδομένων, και αυτό επιτρέπει στον client να ξεκινήσει μόνος του τη ροή OAuth.

Τι δεν εκτίθεται σκόπιμα