الأدوات والسلوك
ربط خادم MCP بعيد
اربط خدمة أدوات قائمة بنقطة نهاية صريحة وقائمة بالأدوات المسموح بها ومرجع لبيانات اعتماد يديره المشغّل.
لتكامل Next.js ومتطلبات الواجهة الخلفية Python، راجع Next.js.
خادم MCP البعيد هو خدمة تشغّلها بالفعل أو تثق بها. أما الخادم المدمج فيُعرَّف داخل تطبيقك باستخدام الأداة المساعدة للواجهة الخلفية بلغة Python. ويمكن ربط كليهما بملف تعريف وكيل أو بعملية تشغيل مقبولة باستخدام معرّف خادم بسيط.
يجب على المشغّل السماح بوجهة نقطة النهاية وتجهيز أي مرجع لبيانات اعتماد الخدمة البعيدة. لا يمكن للجهات المستدعية من المتصفح تسجيل نقاط نهاية أو تقديم مراجع لبيانات اعتماد خاصة. نفّذ ذلك باستخدام مفتاح للواجهة الخلفية يملك نطاق صلاحية التهيئة.
const server = await agents.mcpServers.create({
name: "Knowledge search",
kind: "remote",
url: "https://tools.example/mcp/",
allowed_tools: ["search_documents"],
required: true,
secret_ref: "knowledge-service",
})
const ready = await agents.mcpServers.validate(server.id)
console.log(ready.status, ready.tools)
const session = await agents.sessions.create({ title: "Research request" })
const run = await session.send(
"Find the published support policy and summarize the escalation steps.",
{
idempotencyKey: persistedRequestId,
mcp_server_ids: [server.id],
},
)
secret_ref مرجع يجهّزه المشغّل، وليس قيمة سرية ولا اسم متغير بيئة يمكن للمستخدم اختياره بحرية. احذفه عند استخدام خدمة مسموح بها لا تحتاج إلى بيانات اعتماد. تتحقق واجهة API من الوجهات وعمليات إعادة التوجيه والإمكانات المطلوبة.
إعادة استخدام الأدوات من خلال ملف تعريف
const profile = await agents.profiles.create({
name: "Support researcher",
instructions: "Use the approved sources. Cite the document identifiers.",
mcp_server_ids: [server.id],
max_cost_microusd: 300_000,
timeout_seconds: 120,
})
const session = await agents.sessions.create({
title: "Support research",
profile_id: profile.id,
})
تحتفظ عملية التشغيل بإصدار الأدوات والفهرس الذي اعتُمد عند قبولها. لا تؤدي إعادة تهيئة الخادم إلى توسيع صلاحيات العمل الجاري بصمت. ويمنع إلغاء صلاحية الخادم استخدامه مستقبلًا؛ أما إلغاء العمل الجاري فيظل إجراءً صريحًا مستقلًا.
إذا فشل التحقق، فافحص الحالة المُعادة ورسالة الخطأ الآمنة. لا تعتبر نجاح اتصال TCP دليلًا على أن الخادم يوفّر الأدوات المتوقعة أو تفويضًا صالحًا للاستخدام.