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

Ενσωμάτωση MCP

Για αρθρωτές οργανώσεις, η συνδεδεμένη οργάνωση χρειάζεται ένα ενεργό module CRM, καθώς και τα απαιτούμενα scopes της ενσωμάτωσης. Το υποκείμενο API επιστρέφει HTTP 403 με module_not_active όταν η πρόσβαση στο CRM δεν είναι διαθέσιμη. Επιλύστε την πρόσβαση στο module από τις Συνδρομή πριν δοκιμάσετε ξανά· η αλλαγή του API key από μόνη της δεν διορθώνει αυτό το σφάλμα.

Το Scoutello παρέχει έναν απομακρυσμένο διακομιστή Model Context Protocol (MCP) για ελεγχόμενη πρόσβαση στα δεδομένα της οργάνωσης. Χρησιμοποιεί τις ίδιες ενσωματώσεις, τα ίδια API keys, scopes, ελέγχους tenant, όρια ρυθμού και συμπεριφορά εγγραφών με το Scoutello REST API.

Χρησιμοποιήστε το MCP όταν ένας πελάτης ή agent AI πρέπει να ανακαλύπτει και να καλεί λειτουργίες του Scoutello ως εργαλεία. Χρησιμοποιήστε το REST όταν μια εφαρμογή χρειάζεται συμβατικά HTTP endpoints ή έναν παραγόμενο πελάτη OpenAPI. Και οι δύο επιφάνειες χρησιμοποιούν το ίδιο υποκείμενο συμβόλαιο δεδομένων.

Πριν από τη σύνδεση​

Ένας διαχειριστής της οργάνωσης πρέπει να δημιουργήσει μια ενσωμάτωση από τις Ρυθμίσεις οργάνωσης → Developer/API. Κατά τη δημιουργία ή την περιστροφή του key:

  1. Επιλέξτε μόνο τα scopes ανάγνωσης και εγγραφής που χρειάζεται ο πελάτης MCP.
  2. Αποθηκεύστε το πλήρες sctl_api_ key όταν εμφανιστεί. Το Scoutello το εμφανίζει μία φορά.
  3. Αποθηκεύστε το key στο secret ή στη ρύθμιση περιβάλλοντος του πελάτη MCP και όχι στο σύστημα ελέγχου εκδόσεων.

Το ίδιο key ενσωμάτωσης μπορεί να καλεί REST και MCP. Η δημιουργία δεύτερου key ειδικά για MCP δεν απαιτείται ούτε συνιστάται. Παλαιότερα sctl_mcp_ keys δεν γίνονται αποδεκτά.

Τιμές σύνδεσης​

Ρυθμίστε τον πελάτη με τις εξής τιμές:

Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY

Αντικαταστήστε το YOUR_API_KEY με το αποθηκευμένο key ενσωμάτωσης. Οι μορφές ρύθμισης των πελατών διαφέρουν, αλλά το transport, το URL και η παραπάνω κεφαλίδα HTTP παραμένουν ίδια. Αν ένας πελάτης δεν μπορεί να ορίσει το Authorization, μπορεί να στείλει το key στο x-api-key. Μην ρυθμίσετε και τις δύο κεφαλίδες.

Το παλαιότερο URL https://admin.scoutello.com/api/mcp παραμένει ως ψευδώνυμο συμβατότητας. Οι νέες συνδέσεις πρέπει να χρησιμοποιούν το versioned endpoint /api/v1/mcp.

Επαλήθευση της σύνδεσης​

Μετά τη σύνδεση του πελάτη, καλέστε πρώτα το εργαλείο whoami. Επιστρέφει πληροφορίες για την τρέχουσα ενσωμάτωση και οργάνωση, τη λήξη και τη χρήση των διαπιστευτηρίων, την κατάσταση των ορίων ρυθμού και τα εκχωρημένα scopes, χωρίς να εκθέτει εγγραφές της οργάνωσης.

Αν το whoami αναγνωρίζει μη αναμενόμενη οργάνωση ή ενσωμάτωση, αποσυνδέστε τον πελάτη και διορθώστε το key πριν καλέσετε άλλο εργαλείο.

Εργαλεία και scopes​

Ο διακομιστής MCP διαφημίζει μόνο τα εργαλεία που έχουν εκχωρηθεί από το τρέχον key. Ένας πελάτης δεν μπορεί να ανακαλύψει ή να καλέσει ένα εργαλείο εγγραφής χρησιμοποιώντας μόνο το αντίστοιχο scope ανάγνωσης.

Scope APIΕργαλεία MCP
contacts.readcontacts_list, contacts_get, contacts_get_by_external_id
contacts.writecontacts_batch_upsert
tasks.readtasks_list, tasks_get, tasks_get_by_external_id
tasks.writetasks_batch_upsert
protocols.readprotocols_list, protocols_get, protocols_get_by_external_id
protocols.writeprotocols_batch_upsert
opportunities.readopportunities_list, opportunities_get, opportunities_get_by_external_id
opportunities.writeopportunities_batch_upsert
projects.readprojects_list, projects_get, projects_get_by_external_id
projects.writeprojects_batch_upsert (συμπεριλαμβανομένων των upserts συμμετεχόντων)
milestones.readmilestones_list, milestones_get, milestones_get_by_external_id
milestones.writemilestones_batch_upsert
members.readmembers_list
events.readevents_list, events_get, events_get_by_external_id
events.writeevents_batch_upsert
mails.readmails_list, mails_get
mail-drafts.readmail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id
mail-drafts.writemail_drafts_batch_upsert (μόνο για προετοιμασία ανθρώπινου ελέγχου)
tags.readtags_list

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

Το contacts_list δέχεται περιορισμένα search στα πεδία ονόματος, επωνύμου και εταιρείας, το type, το status και το tagIds (πίνακας 1–50 ID, που αντιστοιχούν σε οποιαδήποτε επιλεγμένη ετικέτα). Όλα τα token αναζήτησης πρέπει να αντιστοιχούν σε πεδίο ονόματος· όλα τα φίλτρα συνδυάζονται με AND. Διατηρήστε αυτά τα φίλτρα σε κάθε σελίδα του cursor. Για παράδειγμα, το { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } εντοπίζει υπάρχοντες λογαριασμούς που ταιριάζουν χωρίς σάρωση ολόκληρου του αποθέματος.

Οι επαφές CRM που δεν είναι μέλη και συνδέονται με σύνδεση Scoutello είναι αναγνώσιμες και μπορούν να χρησιμοποιηθούν ως αναφορές, ενώ τα πεδία ιδιότητας μέλους/λογαριασμού παραμένουν κρυφά και οι αλλαγές επαφών εξακολουθούν να προστατεύονται. Ένα upsert μόνο εξωτερικού συνδέσμου μπορεί να καταχωρίσει μια αναγνώσιμη επαφή χρησιμοποιώντας το externalId, το scoutelloId και προαιρετικά το externalUpdatedAt· παραλείψτε όλα τα πεδία CRM. Σε επόμενες επαναλήψεις/ενημερώσεις μεταδεδομένων, παραλείψτε το scoutelloId. Δείτε τους κανόνες ορίων και σύνδεσης επαφών.

Ασφαλής εγγραφή​

Τα εργαλεία μαζικής ενημέρωσης μπορούν να αλλάξουν άμεσα τα δεδομένα του Scoutello. Είναι ιδεντοδύναμα για την ίδια ενοποίηση και τα ίδια εξωτερικά αναγνωριστικά, սակայն οι καλούντες θα πρέπει και πάλι να ελέγχουν τον προβλεπόμενο πόρο, τον οργανισμό και το πεδίο εφαρμογής πριν εφαρμόσουν τις αλλαγές.

Ορίστε το mode σε validate για να εκτελέσετε αντιστοίχιση και επικύρωση χωρίς εγγραφή δεδομένων. Αφού ελέγξετε τα αποτελέσματα, επαναλάβετε την κλήση με mode: "apply" για να αποδεχτείτε τις έγκυρες εγγραφές. Το MCP δεν παρέχει λειτουργίες διαγραφής.

Η παύση μιας ενοποίησης απορρίπτει τόσο τα αιτήματα REST όσο και τα αιτήματα MCP που χρησιμοποιούν τα κλειδιά της. Η περιστροφή αντικαθιστά τα διαπιστευτήριά της, ενώ η ανάκληση απενεργοποιεί μόνιμα κάθε διαπιστευτήριο που ανήκει στην ενοποίηση.

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

ΑποτέλεσμαΤι να ελέγξετε
401 σφάλμα ελέγχου ταυτότηταςΕπιβεβαιώστε ότι υπάρχει ολόκληρο το κλειδί και ότι η κεφαλίδα χρησιμοποιεί το Bearer, χωρίς εισαγωγικά γύρω από το κλειδί.
403 σφάλμα εξουσιοδότησηςΠαραχωρήστε το απαιτούμενο πεδίο εφαρμογής περιστρέφοντας το κλειδί της ενοποίησης και, στη συνέχεια, ενημερώστε τον client με το νέο κλειδί.
404 στη διεύθυνση URL MCPΕπιβεβαιώστε ότι η διεύθυνση URL τελειώνει σε /api/v1/mcp. Η υπηρεσία MCP ενδέχεται να μην έχει ακόμη ενεργοποιηθεί σε αυτό το περιβάλλον Scoutello.
429 σφάλμα ορίου ρυθμούΠεριμένετε μέχρι τον χρόνο επαναφοράς που επιστρέφεται πριν επαναλάβετε την προσπάθεια. Τα REST και MCP καταναλώνουν το ίδιο όριο ενοποίησης.
Το εργαλείο δεν είναι διαθέσιμοΕλέγξτε τα πεδία εφαρμογής του κλειδιού με whoami· τα μη διαθέσιμα εργαλεία παραλείπονται σκόπιμα από την ανακάλυψη.

Για τα πεδία εγγραφών, τη σελιδοποίηση, τη συμπεριφορά μαζικών ενεργειών και τα περιβλήματα σφαλμάτων, συνεχίστε με την αναφορά API του Scoutello.

Σχεδιασμός συνδεδεμένων έργων​

Δημιουργήστε ένα έργο, στη συνέχεια τα ορόσημά του και μετά τις εργασίες και τα πρωτόκολλα, χρησιμοποιώντας σταθερά εξωτερικά αναγνωριστικά ενοποίησης. Για πρόσβαση σε νέα ορόσημα απαιτείται milestones.read/milestones.write· παραχωρήστε το members.read για αναζήτηση μελών που μπορούν να ανατεθούν. Τα υπάρχοντα διαπιστευτήρια δεν αποκτούν αυτόματα διευρυμένα δικαιώματα. Μετά την περιστροφή ή την παραχώρηση πρόσβασης, ανανεώστε την ανακάλυψη εργαλείων και ελέγξτε το whoami.

Χρησιμοποιήστε τα Customer ID των μελών για το assignedContacts έργου/ορόσημου και τα User ID για το assignedScoutelloUserIds εργασίας ή το ownerScoutelloUserId ευκαιρίας. Οι αναφορές εργασιών/πρωτοκόλλων δέχονται το projectScoutelloId ή το projectExternalId, καθώς και τα αντίστοιχα ζεύγη ορόσημου/ευκαιρίας. Οι σύνδεσμοι που περιέχουν μόνο ορόσημο συμπεραίνουν το έργο· οι ασυμφωνίες απορρίπτουν το στοιχείο της μαζικής ενέργειας. Οι συμμετέχοντες έργου ενημερώνονται προσθετικά και οι εγγραφές που παραλείπονται διατηρούνται.

Τα πρωτόκολλα υποστηρίζουν σημειώσεις έργου/ορόσημου χωρίς στοιχεία επικοινωνίας και την κατάσταση draft/final. Οι εισαγωγές αυτής της συνδεδεμένης εργασίας εκτελούνται αθόρυβα και δεν αποστέλλουν ποτέ επικοινωνίες. Τα εργαλεία λίστας εκθέτουν τα ίδια φίλτρα έργου, κατάστασης, ανάθεσης και ημερομηνίας λήξης ανά οντότητα με το REST. Διατηρήστε τα ακριβή φίλτρα, συμπεριλαμβανομένου του updatedSince, σε κάθε σελίδα του cursor. Ανατρέξτε στην αναφορά API για το πλήρες συμβόλαιο και τη σημασιολογία των τιμών null/παραλειπόμενων πεδίων.

Επικυρώστε κάθε εξαρτώμενη μαζική ενέργεια, εφαρμόστε την, ελέγξτε κάθε αποτέλεσμα και διαβάστε ξανά τις εγγραφές πριν θεωρήσετε ότι η συμπλήρωση ολοκληρώθηκε. Μια δοκιμαστική εκτέλεση δεν μπορεί να επιλύσει γονικές εγγραφές που υπάρχουν μόνο σε άλλη δοκιμαστική εκτέλεση. Κατά την επανάληψη μιας αμφίβολης αρχικής σύνδεσης με το scoutelloId, διαβάστε πρώτα με βάση το εξωτερικό αναγνωριστικό· τα αναγνωριστικά bootstrap δεν μπορούν να επαναχρησιμοποιηθούν αφού δημιουργηθεί η σύνδεση.

Οδηγίες agent για έργα πωλήσεων​

Κάθε επαφή που δημιουργείται ή επαναχρησιμοποιείται για έργο πωλήσεων πρέπει να αναφέρεται ρητά σε αυτό το έργο, χρησιμοποιώντας το projectScoutelloId ή το projectExternalId στο contacts_batch_upsert. Η αναφορά ενός έργου σε σημειώσεις ή σε εξωτερικό αναγνωριστικό δεν αποτελεί συμμετοχή. Οι εγγραφές επαφών με αναφορές έργου απαιτούν επίσης το projects.write. Διαβάστε ξανά την επαφή με τα contacts.read και projects.read και επαληθεύστε το projectParticipations· διατηρήστε τις υπάρχουσες συμμετοχές και ομάδες. Οι γενικές επαφές εκτός έργου δεν απαιτούν αναφορά έργου.

Διατηρήστε τις εταιρείες και τα επαληθευμένα άτομα ως ξεχωριστές επαφές. Συνδέστε ένα άτομο με την εταιρεία χρησιμοποιώντας το companyScoutelloId ή το companyExternalId, όχι μόνο το companyName. Οι αλλαγές σε επαφές, σχέσεις εταιρειών και συμμετοχές είναι ατομικές ως προς κάθε στοιχείο της μαζικής ενέργειας· οι μη έγκυρες αναφορές δεν αφήνουν μερική επαφή. Μην επινοείτε άτομα και μην εφαρμόζετε ετικέτες προέλευσης.

Προετοιμάστε τα εξερχόμενα email με το mail_drafts_batch_upsert, ποτέ ως σώματα πρωτοκόλλων. Παραχωρήστε ρητά τα νέα πεδία εφαρμογής mail-drafts.read και mail-drafts.write· η προετοιμασία απαιτεί επίσης τα contacts.read και projects.write. Τα υπάρχοντα διαπιστευτήρια δεν λαμβάνουν αυτόματα νέα δικαιώματα. Χρησιμοποιήστε σταθερό εξωτερικό αναγνωριστικό, το expectedVersion: 0 για τη δημιουργία, ρητές αναφορές έργου/επαφής, το User ID εγκεκριμένου ατόμου που πραγματοποιεί την έγκριση και ρυθμισμένο πεδίο εφαρμογής αποστολέα organization ή personal. Μην μαντεύετε ποτέ διεύθυνση παραλήπτη ή ρύθμιση αποστολέα.

Διατηρήστε την έρευνα στο content.notes· μόνο τα content.subject και content.body αποτελούν εξερχόμενο κείμενο. Η δημιουργία προσχεδίου διασφαλίζει ότι η επαφή συμμετέχει στο έργο. Οι ενημερώσεις πρέπει να χρησιμοποιούν την έκδοση που επιστράφηκε από την πιο πρόσφατη ανάγνωση· τα προσχέδια που έχουν ελεγχθεί ή αποσταλεί απορρίπτουν τις επεξεργασίες. Οι πανομοιότυπες επαναλήψεις επιστρέφουν το αρχικό προσχέδιο χωρίς να δημιουργούν νέο για έλεγχο. Διαβάστε ξανά τα reviewUrl, draftVersion, contentHash, την κατάσταση έγκρισης/αποστολής και το τελικό mailScoutelloId.

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

Προετοιμασία αναρτήσεων στα μέσα κοινωνικής δικτύωσης​

Παραχωρήστε τα social-channels.read, social-posts.read, social-post-drafts.read και social-post-drafts.write as needed. Το members_list (members.read) μπορεί να εντοπίζει αναγνωριστικά χρηστών αξιολογητών. Τα εργαλεία κοινωνικών δικτύων εμφανίζονται μόνο όταν έχει παραχωρηθεί το αντίστοιχο πεδίο εφαρμογής:

Πεδίο εφαρμογήςΕργαλεία
social-channels.readsocial_channels_list
social-posts.readsocial_posts_list, social_posts_get
social-post-drafts.readsocial_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id
social-post-drafts.writesocial_post_drafts_batch_upsert, social_media_create_upload, social_media_finalize_upload

Διαβάστε τις δυνατότητες των καναλιών και το ιστορικό που δημιούργησε το Scoutello, ανεβάστε τα αρχεία και, στη συνέχεια, υποβάλετε πλήρεις παραλλαγές καναλιού με ονομασμένο αξιολογητή. Τα εργαλεία μεταφόρτωσης επιστρέφουν οδηγίες HTTP PUT: μεταφέρετε τα byte του αρχικού αρχείου εκτός MCP και, στη συνέχεια, ολοκληρώστε τη μεταφόρτωση με το { "assetId": "..." }. Μην ενσωματώνετε αρχεία base64 στα ορίσματα των εργαλείων.

Χρησιμοποιήστε το expectedVersion: 0 για νέα προσχέδια και την τρέχουσα έκδοση για εκκρεμείς αναθεωρήσεις. Το mode: "validate" δεν εκτελεί εγγραφές. Το εργαλείο επιστρέφει τη διεύθυνση URL αξιολόγησης· μόνο ένα άτομο που χρησιμοποιεί τον πίνακα ελέγχου μπορεί να εγκρίνει τη δημοσίευση ή τον προγραμματισμό. Δεν υπάρχει εργαλείο MCP για έγκριση, δημοσίευση, ακύρωση ή διαγραφή μιας ανάρτησης. Ελέγχετε περιοδικά τα εργαλεία προσχεδίων/ιστορικού για την έγκριση, τους λόγους απόρριψης και τα αποτελέσματα παράδοσης ανά κανάλι. Για περαιτέρω προτάσεις, τα προσχέδια που έχουν αξιολογηθεί απαιτούν νέο εξωτερικό αναγνωριστικό.

Ανατρέξτε στην ενότητα αναρτήσεις κοινωνικών δικτύων για αξιολόγηση από άτομα για παραδείγματα εισόδου, όρια μεταφόρτωσης, σελιδοποίηση και συμπεριφορά σε περίπτωση καθυστερημένης αξιολόγησης.