Σύνδεση βοηθού AI (MCP)

Σύνδεση

Μπορείτε να συνδεθείτε με δύο τρόπους. Οι περισσότεροι χρήστες επιλέγουν τη σύνδεση με λογαριασμό (OAuth). Δεν χρειάζεται κλειδί. Η διεύθυνση του διακομιστή είναι η ίδια για κάθε βοηθό και κάθε τρόπο:

https://filodos.gr/api/mcp

Σύνδεση με τον λογαριασμό Filodos (OAuth)

Χρησιμοποιήστε αυτόν τον τρόπο όταν ο βοηθός σάς επιτρέπει να προσθέσετε σύνδεση μόνο με μια διεύθυνση URL. Ο βοηθός ανοίγει στον περιηγητή μια σελίδα σύνδεσης του Filodos. Δεν αντιγράφετε και δεν αποθηκεύετε κλειδί.

1. Ανοίξτε τις ρυθμίσεις συνδέσεων του βοηθού σας. Προσθέστε νέο διακομιστή MCP ή νέα σύνδεση με τη διεύθυνση παραπάνω.
2. Επιλέξτε OAuth αν ο βοηθός ρωτά για τον τύπο ταυτοποίησης. Αφήστε κενά τα πεδία κλειδιού και header.
3. Ο βοηθός ανοίγει τη σελίδα σύνδεσης του Filodos. Εισαγάγετε τον οργανισμό, το email και τον κωδικό σας. Έπειτα επιλέξτε Allow.
4. Η σελίδα εξηγεί την πρόσβαση με απλά λόγια. Η πρόσβαση είναι μόνο για ανάγνωση. Ένας λογαριασμός οδηγού δεν μπορεί να συνδεθεί.
5. Επιστρέψτε στον βοηθό και ρωτήστε: «πού βρίσκεται ο στόλος μου τώρα;». Αν εμφανίσει ζωντανές θέσεις, η σύνδεση λειτουργεί.

Αυτά είναι τα βήματα για κάθε βοηθό:

• ChatGPT: Ρυθμίσεις → Connectors (Apps) → δημιουργία σύνδεσης. Επικολλήστε τη διεύθυνση και επιλέξτε OAuth.
• Claude (claude.ai και Claude Desktop): Ρυθμίσεις → Connectors → Add custom connector. Γράψτε το όνομα Filodos και τη διεύθυνση. Επιλέξτε Connect.
• Claude Code: εκτελέστε μία φορά αυτή την εντολή σε τερματικό:

  claude mcp add --transport http --scope user filodos https://filodos.gr/api/mcp

  Έπειτα εκτελέστε /mcp, επιλέξτε filodos και επιλέξτε Authenticate. Ο περιηγητής ανοίγει τη σελίδα σύνδεσης.
• Cursor, VS Code και άλλα εργαλεία με υποστήριξη MCP OAuth: προσθέστε τον διακομιστή μόνο με το πεδίο url. Μην προσθέσετε τμήμα headers. Το εργαλείο ξεκινά τη σύνδεση όταν συνδεθεί.

Ο βοηθός παίρνει ένα διακριτικό πρόσβασης που ισχύει 1 ώρα. Το ανανεώνει χωρίς νέα σύνδεση για 30 ημέρες. Μετά από 30 ημέρες χωρίς ανανέωση, συνδεθείτε ξανά. Για να τερματίσετε την πρόσβαση νωρίτερα, επικοινωνήστε με το support@filodos.gr.

Σύνδεση με κλειδί API

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

1. Δημιουργήστε κλειδί στη σελίδα Organization → Βοηθοί AI του πίνακα ελέγχου. Η σελίδα δημιουργεί το κλειδί με τα σωστά δικαιώματα και σας δίνει έτοιμα τα αποσπάσματα με το κλειδί συμπληρωμένο.
2. Στείλτε το κλειδί στο header Authorization: Bearer YOUR_KEY σε κάθε αίτημα. Τα αποσπάσματα παρακάτω το κάνουν για κάθε βοηθό.
3. Claude Code: εκτελέστε μία φορά αυτή την εντολή σε τερματικό. Αντικαταστήστε το YOUR_KEY με το κλειδί σας:

   claude mcp add --transport http --scope user filodos https://filodos.gr/api/mcp --header "Authorization: Bearer YOUR_KEY"

   Έπειτα εκτελέστε /mcp στο Claude Code. Ο διακομιστής filodos εμφανίζεται ως συνδεδεμένος. Η επιλογή --scope user κάνει τον διακομιστή διαθέσιμο σε κάθε έργο.
4. Claude Desktop: Ρυθμίσεις → Επεκτάσεις → Sύνθετες ρυθμίσεις (Advanced settings). Ενσωματώστε αυτό το τμήμα στο αρχείο claude_desktop_config.json και αποθηκεύστε το:

   {
     "mcpServers": {
       "filodos": {
         "command": "npx",
         "args": [
           "-y", "mcp-remote",
           "https://filodos.gr/api/mcp",
           "--header",
           "Authorization: Bearer YOUR_KEY"
         ]
       }
     }
   }

   Απαιτείται Node.js (nodejs.org). Επανεκκινήστε το Claude Desktop μετά την αποθήκευση.
5. Cursor: επεξεργαστείτε το αρχείο ~/.cursor/mcp.json (δημιουργήστε το αν δεν υπάρχει):

   {
     "mcpServers": {
       "filodos": {
         "url": "https://filodos.gr/api/mcp",
         "headers": { "Authorization": "Bearer YOUR_KEY" }
       }
     }
   }

   Επανεκκινήστε το Cursor.
6. GitHub Copilot (VS Code): απαιτεί VS Code 1.99+ και την επέκταση GitHub Copilot. Ανοίξτε την παλέτα εντολών και εκτελέστε MCP: Add Server, ή δημιουργήστε το .vscode/mcp.json:

   {
     "inputs": [],
     "servers": {
       "filodos": {
         "url": "https://filodos.gr/api/mcp",
         "headers": { "Authorization": "Bearer YOUR_KEY" }
       }
     }
   }

   Επανεκκινήστε το VS Code.
7. Windsurf: επεξεργαστείτε το ~/.codeium/windsurf/mcp_config.json (δημιουργήστε το αν δεν υπάρχει) με το ίδιο μπλοκ mcpServers όπως το Cursor. Επανεκκινήστε το Windsurf.
8. OpenAI Codex CLI: εγκαταστήστε με npm install -g @openai/codex (απαιτείται Node.js), μετά επεξεργαστείτε το ~/.codex/config.toml:

   [mcp_servers.filodos]
   command = "npx"
   args = ["-y", "mcp-remote", "https://filodos.gr/api/mcp",
           "--header", "Authorization: Bearer YOUR_KEY"]

9. pi: εκτελέστε μία φορά σε τερματικό:
   pi mcp add filodos --url https://filodos.gr/api/mcp --header 'Authorization=Bearer YOUR_KEY'
10. Άλλα εργαλεία (Zed, Amazon Q, Continue, OpenCode, Muse Code και άλλα που διαβάζουν ρύθμιση mcpServers JSON): χρησιμοποιήστε το ίδιο μπλοκ όπως το Cursor. Αν το πεδίο url δεν συνδέεται, χρησιμοποιήστε το μπλοκ mcp-remote από το βήμα Claude Desktop.
11. Δοκιμή: ρωτήστε τον βοηθό «πού είναι ο στόλος μου τώρα;». Αν απαντήσει με τις ζωντανές θέσεις, η σύνδεση λειτουργεί.
12. Δοκιμή: ρωτήστε τον βοηθό «πού βρίσκεται ο στόλος μου τώρα;». Αν απαντήσει με τις ζωντανές θέσεις, η σύνδεση λειτουργεί.

Η σελίδα Βοηθοί AI του πίνακα ελέγχου κάνει τη διαδικασία με κλειδί βήμα-βήμα, στα ελληνικά και στα αγγλικά, με το κλειδί ήδη μέσα σε κάθε απόσπασμα.

Εργαλεία

Ο βοηθός βλέπει δώδεκα εργαλεία μόνο ανάγνωσης. Κάθε εργαλείο διαβάζει ό,τι διαβάζει και το αντίστοιχο endpoint του δημόσιου API, με το ίδιο εύρος οργανισμού. Κάθε γραμμή απάντησης κουβαλεί και έναν σύνδεσμο dashboard_url προς τη σελίδα του πίνακα ελέγχου. Οι ημερομηνίες είναι πάντα στη ζώνη ώρας του στόλου (Ευρώπη/Αθήνα).

• list_vehicles — η λίστα του στόλου: όνομα, κατάσταση, τρέχοντες οδηγοί, καταγεγραμμένα χιλιόμετρα. Δικαίωμα analytics:read. Παράμετροι: limit (προεπιλογή 200), offset, include_inactive (προεπιλογή true). Η απάντηση έχει total και next_offset. Με το include_inactive η λίστα περιλαμβάνει και οχήματα που το Traccar δεν επιστρέφει πια, και κάθε γραμμή έχει active.
• get_vehicle_position — τα νεότερα στίγματα GPS ενός οχήματος (προεπιλογή: το τελευταίο). Δικαίωμα positions:read. Παράμετροι: device_id, limit.
• get_vehicle_trips — οι διαδρομές ενός οχήματος, νεότερες πρώτα, με τον οδηγό κάθε διαδρομής. Δικαίωμα trips:read. Παράμετροι: device_id, since, until, limit (προεπιλογή 100, μέγιστο 500), offset, include_addresses. Η απάντηση έχει rows, total και next_offset.
• get_vehicle_track — η πορεία GPS ενός οχήματος, με μία πολυγραμμή για κάθε διαδρομή. Χρησιμοποιήστε το για να σχεδιάσετε χάρτη. Δικαιώματα trips:read και positions:read. Παράμετροι: device_id, since, until (διαφορά έως 7 ημέρες), max_points (προεπιλογή 2000). Η απάντηση δείχνει πότε αφαίρεσε σημεία.
• get_driver_trips — οι διαδρομές ενός οδηγού σε όλα τα οχήματα που χρησιμοποίησε. Δικαίωμα trips:read. Παράμετροι: driver_id ή driver_name, since, until, limit, offset, include_addresses.
• get_driving_events — τα συμβάντα οδήγησης ενός οχήματος (υπέρβαση, απότομα φρεναρίσματα, κόπωση, ADAS, SOS, διαβάσεις ζωνών). Δικαίωμα events:read. Παράμετροι: device_id.
• get_site_visits — οι παραμονές σε ζώνες (επισκέψεις σημείων). Δικαίωμα events:read. Παράμετροι: device_id, since, until, limit (κενό όριο = τελευταίες 30 ημέρες).
• get_daily_summary — η ημερήσια σύνοψη ενός οχήματος: ανά διαδρομή, ζώνες υπέρβασης, ρελαντί, νυχτερινά χιλιόμετρα, κόστος. Δικαίωμα reports:read. Παράμετροι: device_id, day (κενό = χθες), προαιρετικές τιμές κόστους.
• get_weekly_report — η εβδομαδιαία σύνοψη Δευτέρα–Κυριακή με αφήγηση και βαθμολογία. Δικαίωμα reports:read. Παράμετροι: device_id, week (κενό = η τελευταία ολοκληρωμένη εβδομάδα).
• get_driver_overview — συγκεντρωτικά ανά οδηγό σε όλα τα οχήματα που οδήγησε: σύνολα, παραβάσεις ανά τύπο, βαθμολογία. Δικαίωμα drivers:read. Χωρίς παραμέτρους.
• get_safety_scores — οι αποθηκευμένες βαθμολογίες περιόδων ενός οχήματος με την ανάλυσή τους. Δικαίωμα scores:read. Παράμετροι: device_id.
• get_telemetry_bursts — οι συνόψεις των πακέτων «μαύρου κουτιού» (ανά δευτερόλεπτο GPS/επιτάχυνση). Δικαίωμα telemetry:read. Παράμετροι: device_id, since, until, limit.

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

Ασφάλεια

• Μόνο ανάγνωση. Κανένα εργαλείο δεν γράφει τίποτα, δεν στέλνει εντολή σε όχημα και δεν αλλάζει ρυθμίσεις.
• Το κλειδί ή το OAuth διακριτικό ταξιδεύει στην κεφαλίδα Authorization σε κάθε αίτημα — ποτέ στη διεύθυνση URL, οπότε δεν καταγράφεται στα logs.
• Με σύνδεση OAuth (ChatGPT) το διακριτικό διαρκεί μία ώρα και ανανεώνεται μόνο του όσο χρησιμοποιείται. Δεν γράφει ποτέ τίποτα.
• Ο διακομιστής δέχεται το πολύ 120 αιτήματα το λεπτό ανά κλειδί. Πάνω από αυτό απαντά 429 για ένα λεπτό.
• Λάθη: 401 άγνωστο κλειδί ή ληγμένο διακριτικό, 403 λείπει το δικαίωμα του εργαλείου, 404 όχημα άλλου οργανισμού ή άγνωστο (δεν αποκαλύπτεται ποιο).

Ανακαλέστε το κλειδί όποτε θέλετε από τη σελίδα Βοηθοί AI ή Κλειδιά API — όλοι οι βοηθοί σταματούν αμέσως. Για βοηθούς που συνδέθηκαν με σύνδεση Filodos (OAuth), η πρόσβαση λήγει με το διακριτικό, και η οριστική διακοπή γίνεται από την ομάδα μας με ένα αίτημα στη διεύθυνση support@filodos.gr.