MCP एकीकरण

मॉड्यूलर संगठनों के लिए, कनेक्ट किए गए संगठन में एक सक्रिय CRM मॉड्यूल और एकीकरण के लिए आवश्यक स्कोप होने चाहिए। CRM एक्सेस उपलब्ध न होने पर अंतर्निहित API HTTP 403 के साथ module_not_active लौटाता है। दोबारा प्रयास करने से पहले Subscription में मॉड्यूल एक्सेस ठीक करें; केवल API कुंजी बदलने से यह त्रुटि ठीक नहीं होती।

Scoutello संगठन के डेटा तक नियंत्रित एक्सेस के लिए एक रिमोट Model Context Protocol (MCP) सर्वर उपलब्ध कराता है। इसमें Scoutello REST API जैसे ही एकीकरण, API कुंजियाँ, स्कोप, टेनेंट जाँच, रेट सीमाएँ और रिकॉर्ड व्यवहार लागू होते हैं।

जब किसी AI क्लाइंट या एजेंट को Scoutello ऑपरेशन को टूल के रूप में खोजकर कॉल करना हो, तब MCP का उपयोग करें। जब किसी एप्लिकेशन को पारंपरिक HTTP एंडपॉइंट या जनरेट किए गए OpenAPI क्लाइंट की आवश्यकता हो, तब REST का उपयोग करें। दोनों इंटरफ़ेस एक ही अंतर्निहित डेटा कॉन्ट्रैक्ट का उपयोग करते हैं।

कनेक्ट करने से पहले

किसी संगठन प्रशासक को Organization settings → Developer/API में एकीकरण बनाना होगा। इसकी कुंजी बनाते या बदलते समय:

1. केवल वे पढ़ने और लिखने वाले स्कोप चुनें जिनकी MCP क्लाइंट को आवश्यकता है।
2. कुंजी दिखाई जाने पर पूरी sctl_api_ कुंजी सेव करें। Scoutello इसे केवल एक बार दिखाता है।
3. कुंजी को सोर्स कंट्रोल में रखने के बजाय MCP क्लाइंट के सीक्रेट या एनवायरनमेंट कॉन्फ़िगरेशन में स्टोर करें।

एक ही एकीकरण कुंजी REST और MCP दोनों को कॉल कर सकती है। MCP के लिए अलग कुंजी बनाना आवश्यक या अनुशंसित नहीं है। पुरानी sctl_mcp_ कुंजियाँ स्वीकार नहीं की जातीं।

कनेक्शन मान

क्लाइंट को इन मानों के साथ कॉन्फ़िगर करें:

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

YOUR_API_KEY को सेव की गई एकीकरण कुंजी से बदलें। क्लाइंट कॉन्फ़िगरेशन के फ़ॉर्मैट अलग-अलग हो सकते हैं, लेकिन ऊपर दिया गया ट्रांसपोर्ट, URL और HTTP हेडर समान रहना चाहिए। यदि कोई क्लाइंट Authorization सेट नहीं कर सकता, तो इसके बजाय कुंजी x-api-key में भेजी जा सकती है। दोनों हेडर कॉन्फ़िगर न करें।

पुराना https://admin.scoutello.com/api/mcp URL अब भी संगतता उपनाम के रूप में उपलब्ध है। नए कनेक्शन के लिए वर्शन वाला /api/v1/mcp एंडपॉइंट इस्तेमाल करें।

कनेक्शन सत्यापित करें

क्लाइंट के कनेक्ट होने के बाद सबसे पहले whoami टूल कॉल करें। यह वर्तमान एकीकरण और संगठन, क्रेडेंशियल की समाप्ति और उपयोग संबंधी जानकारी, रेट-लिमिट स्थिति और दिए गए स्कोप लौटाता है, लेकिन संगठन के रिकॉर्ड उजागर नहीं करता।

यदि whoami में अनपेक्षित संगठन या एकीकरण दिखाई दे, तो किसी अन्य टूल को कॉल करने से पहले क्लाइंट डिस्कनेक्ट करें और उसकी कुंजी ठीक करें।

टूल और स्कोप

MCP सर्वर केवल वर्तमान कुंजी को दिए गए टूल उपलब्ध कराता है। संबंधित पढ़ने का स्कोप होने मात्र से क्लाइंट किसी लिखने वाले टूल को खोज या कॉल नहीं कर सकता।

API स्कोप	MCP टूल
contacts.read	contacts_list, contacts_get, contacts_get_by_external_id
contacts.write	contacts_batch_upsert
tasks.read	tasks_list, tasks_get, tasks_get_by_external_id
tasks.write	tasks_batch_upsert
protocols.read	protocols_list, protocols_get, protocols_get_by_external_id
protocols.write	protocols_batch_upsert
opportunities.read	opportunities_list, opportunities_get, opportunities_get_by_external_id
opportunities.write	opportunities_batch_upsert
projects.read	projects_list, projects_get, projects_get_by_external_id
projects.write	projects_batch_upsert (प्रतिभागी अपसर्ट सहित)
milestones.read	milestones_list, milestones_get, milestones_get_by_external_id
milestones.write	milestones_batch_upsert
members.read	members_list
events.read	events_list, events_get, events_get_by_external_id
events.write	events_batch_upsert
mails.read	mails_list, mails_get
mail-drafts.read	mail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id
mail-drafts.write	mail_drafts_batch_upsert (केवल मानव समीक्षा की तैयारी के लिए)
tags.read	tags_list

प्रमाणीकृत कनेक्शन के लिए whoami हमेशा उपलब्ध रहता है। टूल इनपुट और परिणाम, उनसे जुड़े REST ऑपरेशन जैसे ही स्कीमा और रिस्पॉन्स एनवेलप का पालन करते हैं।

contacts_list, पहले नाम, उपनाम और कंपनी के नाम, type, status और tagIds पर सीमित search स्वीकार करता है (1–50 ID का ऐरे, जो चुने गए किसी भी टैग से मेल खाता है)। सभी सर्च टोकन किसी नाम फ़ील्ड से मेल खाने चाहिए; सभी फ़िल्टर AND के साथ लागू होते हैं। इन फ़िल्टर को हर कर्सर पेज पर बनाए रखें। उदाहरण के लिए, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } पूरा डेटा खंगाले बिना मेल खाने वाले मौजूदा अकाउंट ढूँढता है।

Scoutello लॉगिन से जुड़े गैर-सदस्य CRM संपर्क पढ़े और संदर्भित किए जा सकते हैं, जबकि सदस्यता/अकाउंट फ़ील्ड छिपे रहते हैं और संपर्क संपादन सुरक्षित रहते हैं। केवल बाहरी लिंक वाला अपसर्ट externalId, उसके scoutelloId और वैकल्पिक externalUpdatedAt का उपयोग करके पढ़े जा सकने वाले संपर्क को पंजीकृत कर सकता है; सभी CRM फ़ील्ड छोड़ दें। बाद के पुनः प्रयासों/मेटाडेटा अपडेट में scoutelloId छोड़ दें। संपर्क सीमा और लिंकिंग नियम देखें।

सुरक्षित तरीके से लिखें

बैच अपसर्ट टूल Scoutello डेटा को तुरंत बदल सकते हैं। समान एकीकरण और बाहरी आईडी के साथ अनुरोध दोहराने पर बदलाव दोबारा नहीं होता। फिर भी बदलाव लागू करने से पहले लक्षित संसाधन, संगठन और स्कोप की समीक्षा करनी चाहिए।

डेटा में बदलाव किए बिना मिलान और सत्यापन चलाने के लिए mode को validate पर सेट करें। परिणामों की जाँच करने के बाद, मान्य रिकॉर्ड स्वीकार करने के लिए mode: "apply" के साथ कॉल दोहराएँ। MCP में डेटा हटाने की कार्रवाइयाँ उपलब्ध नहीं हैं।

किसी एकीकरण को रोकने पर उसकी कुंजियों का उपयोग करने वाले REST और MCP, दोनों के अनुरोध अस्वीकार हो जाते हैं। कुंजी बदलने पर उसके क्रेडेंशियल बदल जाते हैं, और एकीकरण निरस्त करने पर उससे संबंधित सभी क्रेडेंशियल स्थायी रूप से निष्क्रिय हो जाते हैं।

समस्या-समाधान

परिणाम	क्या जाँचें
401 प्रमाणीकरण त्रुटि	पुष्टि करें कि पूरी कुंजी मौजूद है और हेडर में Bearer का उपयोग हो रहा है; कुंजी के आसपास उद्धरण चिह्न नहीं होने चाहिए।
403 अनुमति संबंधी त्रुटि	एकीकरण की कुंजी बदलते समय आवश्यक स्कोप दें, फिर नई कुंजी से क्लाइंट को अपडेट करें।
MCP URL पर 404	पुष्टि करें कि URL /api/v1/mcp पर समाप्त होता है। हो सकता है कि उस Scoutello परिवेश में MCP सेवा अभी सक्षम न हो।
429 अनुरोध सीमा की त्रुटि	दोबारा प्रयास करने से पहले लौटाए गए सीमा-रीसेट समय तक प्रतीक्षा करें। REST और MCP एक ही एकीकरण कोटा साझा करते हैं।
टूल उपलब्ध नहीं है	whoami से कुंजी के स्कोप जाँचें; अनुपलब्ध टूल को खोज के परिणामों से जानबूझकर हटा दिया जाता है।

रिकॉर्ड फ़ील्ड, पृष्ठों में विभाजन, बैच के व्यवहार और त्रुटि-उत्तर के प्रारूप के लिए Scoutello API संदर्भ देखें।

जुड़े हुए प्रोजेक्ट की योजना

पहले प्रोजेक्ट बनाएँ, फिर उसके माइलस्टोन, और उसके बाद एकीकरण की स्थिर बाहरी आईडी का उपयोग करके कार्य और प्रोटोकॉल बनाएँ। नए माइलस्टोन तक पहुँच के लिए milestones.read/milestones.write आवश्यक है; असाइन किए जा सकने वाले सदस्यों को देखने के लिए members.read दें। मौजूदा क्रेडेंशियल के स्कोप अपने-आप विस्तृत नहीं होते। कुंजी बदलने या पहुँच देने के बाद टूल की खोज रीफ़्रेश करें और whoami की जाँच करें।

प्रोजेक्ट/माइलस्टोन के assignedContacts के लिए सदस्य के संपर्क रिकॉर्ड की आईडी और कार्य के assignedScoutelloUserIds या अवसर के ownerScoutelloUserId के लिए यूज़र आईडी का उपयोग करें। कार्य/प्रोटोकॉल के संदर्भों में projectScoutelloId या projectExternalId, तथा माइलस्टोन/अवसर के समतुल्य आईडी युग्म स्वीकार किए जाते हैं। केवल माइलस्टोन की कड़ी देने पर उससे प्रोजेक्ट पहचाना जाता है; बेमेल संदर्भ होने पर बैच की संबंधित प्रविष्टि अस्वीकार हो जाती है। प्रोजेक्ट के प्रतिभागियों के अपसर्ट नई प्रविष्टियाँ जोड़ते हैं और अनुरोध में छोड़ दी गई मौजूदा प्रविष्टियाँ बनाए रखते हैं।

प्रोटोकॉल में संपर्क से जुड़े बिना प्रोजेक्ट/माइलस्टोन नोट्स और draft/final स्थिति रखी जा सकती है। इस जुड़े हुए काम का आयात कोई संदेश नहीं भेजता। सूची टूल में REST जैसे ही प्रोजेक्ट, स्थिति, असाइनमेंट और नियत तिथि के फ़िल्टर उपलब्ध हैं, जो संबंधित इकाई पर लागू होते हैं। updatedSince सहित ठीक वही फ़िल्टर प्रत्येक कर्सर पृष्ठ में आगे भेजें। पूर्ण डेटा अनुबंध तथा खाली मान और छोड़े गए फ़ील्ड के अर्थ के लिए API संदर्भ देखें।

हर निर्भर बैच को सत्यापित करें, लागू करें, हर परिणाम की जाँच करें और डेटा भरने की प्रक्रिया पूरी मानने से पहले रिकॉर्ड फिर से पढ़ें। परीक्षण रन उन मूल रिकॉर्ड का संदर्भ नहीं ढूँढ सकता जो केवल किसी अन्य परीक्षण रन में मौजूद हों। scoutelloId का उपयोग करके किसी अस्पष्ट शुरुआती कड़ी का पुनः प्रयास करते समय, पहले बाहरी आईडी से रिकॉर्ड पढ़ें; कड़ी बन जाने के बाद शुरुआती लिंकिंग की आईडी फिर से नहीं भेजी जा सकतीं।

बिक्री प्रोजेक्ट के एजेंट के लिए निर्देश

बिक्री प्रोजेक्ट के लिए बनाए गए या दोबारा उपयोग किए गए हर संपर्क में contacts_batch_upsert के अंदर projectScoutelloId या projectExternalId से उस प्रोजेक्ट का स्पष्ट संदर्भ होना चाहिए। नोट्स या बाहरी आईडी में प्रोजेक्ट का उल्लेख सदस्यता नहीं बनाता। प्रोजेक्ट संदर्भ वाले संपर्कों को लिखने के लिए projects.write भी आवश्यक है। contacts.read और projects.read के साथ संपर्क फिर से पढ़ें और projectParticipations सत्यापित करें; मौजूदा सदस्यताएँ और समूह बनाए रखें। प्रोजेक्ट के बाहर के सामान्य संपर्कों के लिए प्रोजेक्ट संदर्भ आवश्यक नहीं है।

कंपनियों और सत्यापित व्यक्तियों को अलग-अलग संपर्कों के रूप में रखें। किसी व्यक्ति को कंपनी से companyScoutelloId या companyExternalId के माध्यम से जोड़ें, केवल companyName के माध्यम से नहीं। संपर्क, कंपनी से संबंध और सदस्यता के बदलाव प्रत्येक बैच प्रविष्टि में एक साथ लागू होते हैं; अमान्य संदर्भ होने पर संपर्क का कोई आंशिक रिकॉर्ड नहीं बनता। काल्पनिक व्यक्ति न बनाएँ और स्रोत बताने वाले टैग लागू न करें।

भेजी जाने वाली ईमेल mail_drafts_batch_upsert के साथ तैयार करें, प्रोटोकॉल के मुख्य पाठ के रूप में कभी नहीं। नए mail-drafts.read और mail-drafts.write स्कोप स्पष्ट रूप से दें; तैयारी के लिए contacts.read और projects.write भी आवश्यक हैं। मौजूदा क्रेडेंशियल को नई अनुमतियाँ अपने-आप नहीं मिलतीं। निर्माण के लिए स्थिर बाहरी आईडी, expectedVersion: 0, प्रोजेक्ट/संपर्क के स्पष्ट संदर्भ, स्वीकार किए गए अनुमोदक की यूज़र आईडी और कॉन्फ़िगर किए गए 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 प्रदान करें। members_list (members.read) से समीक्षक के यूज़र आईडी खोजे जा सकते हैं। सोशल टूल केवल तभी दिखाए जाते हैं, जब उनका स्कोप प्रदान किया गया हो:

स्कोप	टूल
social-channels.read	social_channels_list
social-posts.read	social_posts_list, social_posts_get
social-post-drafts.read	social_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id
social-post-drafts.write	social_post_drafts_batch_upsert, social_media_create_upload, social_media_finalize_upload

चैनल की क्षमताओं और Scoutello द्वारा बनाए गए इतिहास को पढ़ें, एसेट अपलोड करें, फिर नामित समीक्षक के साथ चैनल के सभी वैरिएंट सबमिट करें। अपलोड टूल HTTP PUT निर्देश लौटाते हैं: मूल फ़ाइल बाइट्स को MCP के बाहर ट्रांसफ़र करें, फिर { "assetId": "..." } से अपलोड पूरा करें। टूल आर्ग्युमेंट में बेस64 फ़ाइलें एम्बेड न करें।

नए ड्राफ़्ट के लिए expectedVersion: 0 और लंबित संशोधनों के लिए वर्तमान वर्ज़न का उपयोग करें। mode: "validate" कोई लेखन कार्य नहीं करता। टूल समीक्षा URL लौटाता है; प्रकाशन या शेड्यूलिंग की अनुमति केवल डैशबोर्ड का उपयोग करने वाला व्यक्ति दे सकता है। किसी पोस्ट को अनुमोदित, प्रकाशित, रद्द या हटाने के लिए कोई MCP टूल उपलब्ध नहीं है। अनुमोदन, अस्वीकृति के कारणों और प्रत्येक चैनल के डिलीवरी परिणामों के लिए ड्राफ़्ट/इतिहास टूल को पोल करें। समीक्षा किए गए ड्राफ़्ट के लिए आगे के प्रस्तावों में नई बाहरी आईडी आवश्यक होती है।

इनपुट उदाहरणों, अपलोड सीमाओं, पेजिनेशन और विलंबित समीक्षा व्यवहार के लिए मानवीय समीक्षा हेतु सोशल पोस्ट देखें।