Σύνδεσμοι AI (MCP), σύντομα

Σημείο πρόσβασης#

Ο διακομιστής βρίσκεται στο https://api.console.citronos.com/mcp. Όπως και στο /graphql, η διαδρομή δεν έχει /v1. Χρησιμοποιεί την έκδοση πρωτοκόλλου 2025-11-25 μέσω streamable HTTP και δεν διατηρεί κατάσταση: κάθε POST λαμβάνει απάντηση JSON, δεν υπάρχουν συνεδρίες και τα GET και DELETE απαντούν 405.

Μετά την κυκλοφορία θα μπορούν να συνδεθούν το Claude (claude.ai, Claude Desktop και Claude Code), το ChatGPT, το Cursor, το VS Code και οποιοδήποτε άλλο πρόγραμμα-πελάτης MCP. Όσα υποστηρίζουν OAuth συνδέονται μόνα τους· τα υπόλοιπα χρησιμοποιούν ένα προσωπικό token.

Σύνδεση προγράμματος-πελάτη#

Claude Code#

Προσθέστε τον διακομιστή, έπειτα εκτελέστε /mcp στο Claude Code και επιλέξτε Authenticate. Ανοίγει ένα πρόγραμμα περιήγησης στην οθόνη συναίνεσης του Citron. Για να παρακάμψετε το OAuth, περάστε αντί γι’ αυτό ένα προσωπικό token ως κεφαλίδα.

claude mcp add --transport http citron https://api.console.citronos.com/mcp
# then, inside Claude Code: /mcp → citron → Authenticate

claude mcp add --transport http citron https://api.console.citronos.com/mcp \
  --header "Authorization: Bearer cmcp_pat_…"

Claude Desktop και claude.ai#

Ανοίξτε Settings → Connectors → Add custom connector, εισαγάγετε https://api.console.citronos.com/mcp ως URL και επιλέξτε Connect, έπειτα εγκρίνετε τη σύνδεση στο Citron. Για να το εκτελέσετε τοπικά με προσωπικό token, προσθέστε τα εξής στο claude_desktop_config.json:

{
  "mcpServers": {
    "citron": {
      "command": "citron-mcp",
      "args": ["--base-url", "https://api.console.citronos.com"],
      "env": { "CITRON_MCP_TOKEN": "cmcp_pat_…" }
    }
  }
}

Cursor#

Προσθέστε τον διακομιστή στο ~/.cursor/mcp.json. Παραλείψτε τα headers για να συνδεθείτε με OAuth αντί για token.

{
  "mcpServers": {
    "citron": {
      "url": "https://api.console.citronos.com/mcp",
      "headers": { "Authorization": "Bearer cmcp_pat_…" }
    }
  }
}

ChatGPT#

Ανοίξτε Settings → Apps & Connectors → Advanced settings, ενεργοποιήστε το Developer mode και έπειτα επιλέξτε Create connector. Εισαγάγετε https://api.console.citronos.com/mcp ως URL του διακομιστή MCP και επιλέξτε OAuth για τον έλεγχο ταυτότητας.

Προγράμματα-πελάτες που εκτελούν μόνο τοπικούς διακομιστές#

Ένας μικρός τοπικός διακομιστής stdio, ο citron-mcp, προωθεί κάθε κλήση στο απομακρυσμένο σημείο πρόσβασης. Δεν υπάρχει ακόμη στο npm, οπότε ζητήστε μας το αρχείο του πακέτου και μην εγκαθιστάτε ποτέ πακέτο με αυτό το όνομα από αλλού. Δέχεται προσωπικό token μέσω --token ή στο CITRON_MCP_TOKEN και το βασικό URL μέσω --base-url ή στο CITRON_BASE_URL. Απαιτεί Node 20 ή νεότερη έκδοση.

# Node 20+. Not on npm yet: install the package file we send you
npm install -g ./citron-mcp-0.1.0.tgz

citron-mcp --base-url https://api.console.citronos.com --token cmcp_pat_…

# or with environment variables
CITRON_BASE_URL=https://api.console.citronos.com CITRON_MCP_TOKEN=cmcp_pat_… citron-mcp

Έλεγχος ταυτότητας#

Υπάρχουν δύο είδη διαπιστευτηρίων. Το OAuth συνιστάται για τα προγράμματα-πελάτες που το υποστηρίζουν. Τα προσωπικά token λειτουργούν σε όλες τις άλλες περιπτώσεις.

OAuth 2.1#

Το πρόγραμμα-πελάτης ανακαλύπτει τα πάντα μόνο του. Μια αίτηση χωρίς token λαμβάνει 401 με κεφαλίδα WWW-Authenticate που παραπέμπει στα μεταδεδομένα του προστατευμένου πόρου.

POST /mcp HTTP/1.1
Host: api.console.citronos.com
Content-Type: application/json

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.console.citronos.com/.well-known/oauth-protected-resource/mcp"

• Κωδικός εξουσιοδότησης με PKCE. Γίνεται δεκτή μόνο η μέθοδος S256.
• Τα εγγεγραμμένα προγράμματα-πελάτες είναι δημόσια από προεπιλογή. Υποστηρίζονται επίσης τα client_secret_post και client_secret_basic.
• Ένα έγγραφο μεταδεδομένων προγράμματος-πελάτη (ένα https URL ως client_id) λειτουργεί αντί για την εγγραφή.
• Στείλτε τον δείκτη πόρου (RFC 8707) resource=https://api.console.citronos.com/mcp.
• Τα URI ανακατεύθυνσης πρέπει να είναι https. Το απλό http επιτρέπεται μόνο σε localhost, 127.0.0.1 ή [::1], σε οποιαδήποτε θύρα. Επιτρέπονται επίσης σχήματα εφαρμογών όπως το cursor://….
• Τα εύρη (scopes) είναι mcp:read και mcp:write. Το δικαίωμα εγγραφής περιλαμβάνει και την ανάγνωση.
• Τα token πρόσβασης (cmcp_oat_…) ισχύουν 1 ώρα. Τα token ανανέωσης (cmcp_ort_…) ισχύουν 30 ημέρες και αντικαθίστανται σε κάθε χρήση.
• Ένας κωδικός εξουσιοδότησης που χρησιμοποιείται δύο φορές ανακαλεί όλα όσα εξέδωσε.

Ο χρήστης εγκρίνει τη σύνδεση σε μια οθόνη συναίνεσης στην κονσόλα του Citron (/admin/connect/mcp), συνδεδεμένος με την κανονική του συνεδρία. Εκεί επιλέγει τον χώρο εργασίας και Read only ή Read & write.

Προσωπικά token#

1. Δημιουργήστε το tokenΣτην κονσόλα, ανοίξτε Settings → Developers → AI connectors και επιλέξτε New token.
2. Επιλέξτε όνομα, πρόσβαση και λήξηΗ πρόσβαση είναι Read only ή Read & write. Το token λήγει μετά από 7, 30 ή 90 ημέρες, μετά από 1 έτος ή ποτέ.
3. Αντιγράψτε το μία φοράΤο token (cmcp_pat_…) εμφανίζεται μόνο μία φορά. Το Citron αποθηκεύει μόνο το hash SHA-256 του. Στείλτε το ως Authorization: Bearer cmcp_pat_….

Η λίστα των token δείχνει πότε χρησιμοποιήθηκε τελευταία φορά το καθένα. Μπορείτε να ανακαλέσετε οποιοδήποτε από αυτά ανά πάσα στιγμή.

Εκ μέρους ποιου ενεργεί η σύνδεση#

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

Οι πολιτικές εγγραφών (κανόνες πεδίων και εγγραφών), οι περιορισμοί πρόσβασης σε συλλογές και οι ενεργοποιημένες μονάδες εφαρμόζονται ακριβώς όπως στην κονσόλα.

Εργαλεία#

Τα εργαλεία είναι ίδια με εκείνα του βοηθού AI της κονσόλας. Καλύπτουν τα εισερχόμενα και τα αιτήματα, τις φόρμες, τις κρατήσεις, τις συλλογές και τις εγγραφές περιεχομένου, τα πολυμέσα, το CRM, τους αυτοματισμούς, τους πίνακες ελέγχου και άλλα. Τι βλέπει ένα πρόγραμμα-πελάτης εξαρτάται από τα δικαιώματα του μέλους, τις μονάδες του χώρου εργασίας και την πρόσβαση του token.

• Τα εργαλεία ανάγνωσης (αναζήτηση, ανάγνωση, σύνοψη, εκτέλεση ερωτήματος πίνακα ελέγχου) λειτουργούν με οποιοδήποτε token.
• Τα εργαλεία εγγραφής εμφανίζονται και εκτελούνται μόνο με token Read & write. Μέσω MCP μια αλλαγή εφαρμόζεται αμέσως, χωρίς βήμα επιβεβαίωσης στην κονσόλα. Περνά από τις ίδιες μεθόδους υπηρεσιών με την κονσόλα, καταγράφεται στο αρχείο ελέγχου και επιστρέφει ένα actionId. Όταν η αλλαγή μπορεί να αναιρεθεί, το εργαλείο undo_change την αναιρεί.
• Τα καταστροφικά εργαλεία (διαγραφή, αρχειοθέτηση, ανάκληση) απαιτούν επιπλέον το όρισμα confirm: true. Χωρίς αυτό, η κλήση επιστρέφει CONFIRMATION_REQUIRED και δεν συμβαίνει τίποτα. Το AI πρέπει να το περνά μόνο αφού συμφωνήσει ο χρήστης.
• Οι αλλαγές ασφαλείας (ρόλοι, μέλη, κλειδιά API, SSO, τομείς) απαιτούν πρόσφατη σύνδεση, γι’ αυτό δεν είναι ποτέ διαθέσιμες μέσω MCP και επιστρέφουν UNAVAILABLE_OVER_MCP. Τα εργαλεία που απλώς πλοηγούν στην κονσόλα δεν εμφανίζονται.
• Τα αποτελέσματα των εργαλείων επισημαίνουν τα δεδομένα των εγγραφών ως μη αξιόπιστα. Ισχύουν οι κανόνες ελαχιστοποίησης δεδομένων του βοηθού: χωρίς διευθύνσεις e-mail ή αριθμούς τηλεφώνου, ενώ ονόματα και κείμενο μηνυμάτων μόνο όταν ο χώρος εργασίας επιτρέπει στο AI να διαβάζει το περιεχόμενο των εισερχομένων και του CRM (Settings → AI).
• Τα εργαλεία φέρουν τις επισημάνσεις readOnlyHint και destructiveHint.

Σφάλματα εργαλείων#

Ένα εργαλείο που αποτυγχάνει επιστρέφει αποτέλεσμα με isError: true. Το κείμενό του ξεκινά με έναν από αυτούς τους κωδικούς.

{
  "content": [{ "type": "text", "text": "CONFIRMATION_REQUIRED: …" }],
  "isError": true
}

Πόροι#

Προτροπές#

Σφάλματα HTTP και όρια αιτήσεων#

Τα σημεία πρόσβασης OAuth επιστρέφουν σφάλματα σε μορφή RFC, { "error", "error_description" }. Τα σφάλματα του δημόσιου API περιγράφονται στα σφάλματα και όρια αιτήσεων.

Καταγραφή ελέγχου και ανάκληση πρόσβασης#

Κάθε κλήση εργαλείου γράφει μία γραμμή mcp.tool.call στο αρχείο ελέγχου: το εργαλείο, αν πέτυχε ή τον κωδικό σφάλματος, το id του token, το πρόγραμμα-πελάτη OAuth, το επίπεδο πρόσβασης και τα ονόματα των ορισμάτων. Οι τιμές των ορισμάτων δεν καταγράφονται ποτέ.

Η δημιουργία και η ανάκληση token και οι εγκρίσεις OAuth καταγράφονται επίσης, ως mcp.token.create, mcp.token.revoke, mcp.oauth.approve, mcp.oauth.deny και mcp.oauth.grant.

Ανακαλέστε ένα token ή μια συνδεδεμένη εφαρμογή ανά πάσα στιγμή από Settings → Developers → AI connectors. Η ανάκληση μιας εφαρμογής OAuth τερματίζει και το token ανανέωσής της.