बाहरी Agent MCP एकीकरण

विश्वसनीय सर्वर-साइड एप्लिकेशन से Manager AGI Agents को MCP टूल की तरह उपयोग करें। यह मार्गदर्शिका सेटअप, प्रमाणीकरण, डाउनस्ट्रीम प्राधिकरण, कॉल, रिकवरी और स्थिर त्रुटि अनुबंध बताती है।

त्वरित शुरुआत

1. Web Admin में सक्रिय third-party एप्लिकेशन बनाएँ, कंपनी से जोड़ें और App ID व App Secret कॉपी करें।
2. कंपनी को सक्रिय Agent और प्रभावी प्रकाशित Skills असाइन करें।
3. MCP Streamable HTTP क्लाइंट को Engine HTTPS होस्ट के POST|GET|DELETE /openapi/v1/agents/mcp से जोड़ें।
4. initialize करें, notifications/initialized भेजें, tools/list लें और agent_{id} कॉल करें।

सामान्य assistant प्रकाशित नहीं होता। Secret केवल सर्वर पर रखें।

प्रमाणीकरण और अधिकार सीमा

API वातावरण:

• परीक्षण: https://aim-api-test.proton-system.com
• उत्पादन: https://aim-api.proton-system.com

हर अनुरोध में ये headers भेजें:

Authorization: Basic Base64(KEY:SECRET)
Content-Type: application/json
Accept: application/json, text/event-stream

कस्टम अनुरोध हेडर समर्थित करने वाला रिमोट MCP क्लाइंट निम्न कॉन्फ़िगरेशन का उपयोग कर सकता है:

{
  "mcpServers": {
    "manager-agi": {
      "url": "https://xxx.com/openapi/v1/agents/mcp",
      "headers": {
        "Authorization": "Basic <Base64(AppID:AppSecret)>"
      }
    }
  }
}

सक्रिय एप्लिकेशन को कंपनी स्तर पर स्थायी मंजूरी मिलती है। अभी या बाद में असाइन हुए Agents और नई प्रकाशित Skills, write व high-risk काम सहित, मानवीय मंजूरी के बिना उपलब्ध हो जाते हैं। CompanyRole यह अधिकार कम नहीं करता। Engine फिर भी status, assignment, publication, downstream authorization, schema/risk drift, validation, rate limit, idempotency और audit लागू करता है।

initialization और session

initialize करके response header Mcp-Session-Id सुरक्षित रखें:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"partner-server","version":"1.0.0"}}}

{"jsonrpc":"2.0","method":"notifications/initialized"}

बाद के POST, GET और DELETE में Mcp-Session-Id भेजें। INVALID_MCP_SESSION के बाद फिर initialize करें।

Agent टूल और metadata

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

टूल का नाम agent_{id} है और prefix के बाद पूरा Agent ID आता है। top-level title Agent का नाम है; description में Agent description या खाली होने पर नाम आता है। _meta.easyposAgent केवल public id, name, description, iconUrl देता है। authorizationRequirements में mcpHubId, mcpHubName, authType, status, expiresAt, authorized और authorization आवश्यक होने पर Engine का authorizationUrl होता है। Prompt, quick questions, Skill definitions, internal schemas और credentials बाहर नहीं आते।

डाउनस्ट्रीम प्राधिकरण

जब status MISSING या REAUTH_REQUIRED हो, Engine द्वारा बनाया authorizationUrl खोलें; इसका path /openapi/v1/mcp/authorization/start से शुरू होता है। user authorization पूरी करे तो app tools/list या मूल tools/call फिर चलाता है; ACTIVE का अर्थ है कि Engine app-scoped authorization से execute कर सकता है। expiry या downstream 401 पर यही flow दोबारा करें। token refresh, downstream headers भेजना या failed business call को automatically replay करना नहीं है।

Agent कॉल

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agent_a441d514-2aed-4b86-b12f-7cce1bd90134","arguments":{"requestId":"req-20260825-001","message":"आज के खुले ऑर्डर का सार दें","conversationId":"optional-existing-id"},"_meta":{"progressToken":"req-20260825-001"}}}

requestId आवश्यक, trimmed और अधिकतम 128 UTF-8 bytes है; message आवश्यक और अधिकतम 16 KiB है; conversationId वैकल्पिक है और केवल उसी एप्लिकेशन, कंपनी व Agent में पुनः उपयोग हो सकता है। _meta.progressToken standard MCP progress देता है।

सफल परिणाम में "status":"COMPLETED", "answer", requestId, conversationId, metadata और authorizationRequirements होते हैं। credentials न होने पर isError:true, status:"authorization_required", errorCode:"MCP_AUTHORIZATION_REQUIRED" मिलता है और execution नहीं बनता।

SSE, resume, cancellation और close

MCP progress और एक final result पढ़ें। stream recovery के लिए Basic के साथ Mcp-Session-Id, opaque Last-Event-ID, EasyPOS-Agent-Request-Id, EasyPOS-Agent-Id और Accept: text/event-stream देकर GET करें। replay Agent को दोबारा नहीं चलाता; events बाकी हों तो नए cursor से GET दोहराएँ।

explicit MCP cancellation केवल cancel का अनुरोध है और भेजे गए side effects वापस नहीं होते। transport disconnect स्वीकार किया गया काम cancel नहीं करता। Basic व Mcp-Session-Id के साथ DELETE से session बंद करें।

सीमाएँ और idempotency

requestId एप्लिकेशन के भीतर 90 दिन idempotent है। समान input बिना नई execution unit के result replay करता है; अलग input IDEMPOTENCY_CONFLICT और चल रहा अनुरोध REQUEST_IN_PROGRESS दे सकता है।

त्रुटि अनुबंध

transport त्रुटि HTTP और {"code":"COMPANY_INACTIVE","description":"The company is inactive."} जैसा JSON देती है। MCP/domain त्रुटि isError:true, errorCode और errorDescription देती है। Description स्थिर, non-sensitive English text है; program logic code पर रखें।

सुरक्षा और troubleshooting

TLS और secret manager उपयोग करें तथा logs से authorization headers हटाएँ। browser, mobile, URL या repository में App Secret न रखें। server client को Origin छोड़ना चाहिए; भेजने पर वह अनुमत HTTPS origin होना चाहिए। leak पर एप्लिकेशन disable या Secret reset करें।

खाली tools/list पर कंपनी, Agent, assignment और published Skills जाँचें। authorization आवश्यक हो तो authorizationUrl खोलें और पूरा होने पर discovery या call दोबारा करें; invalid session फिर initialize करें। notification callbackUrl Agent result channel नहीं है; परिणाम MCP/SSE से पढ़ें।