التوثيق

خادم MCP

‏POST /mcp‏ خادم ‏MCP‏ بـ‏JSON-RPC 2.0‏ مكتوب يدويًا — بلا SDK وبلا جلسات. كل طلب يحمل مفتاح ‏Bearer agw_…‏ نفسه؛ تعرض ‏tools/list‏ ما يجوز للمفتاح استدعاؤه فقط، وتفرض ‏tools/call‏ الصلاحيات نفسها كما في نقاط ‏/v1‏. أدوات الذاكرة تظهر فقط للمفاتيح ذات صلاحيات الذاكرة.

الأدوات

الحقلscopeالوصف
search_websearchبحث ويب — خط ‏/v1/search‏ نفسه ‏(query, k?, lang?)‏.
read_urlreadنص صفحة نظيف — محرك الجلب والاستخلاص الخاص بـ ‏/v1/read‏ ‏(url)‏.
researchsearchحزمة الأدلة الخاصة بـ ‏/v1/research‏ ‏(question, depth?)‏.
remembermemory:writeتخزين عناصر في الذاكرة الخاصة ‏(items[])‏.
recallmemory:readبحث دلالي في الذاكرة ‏(query, k?)‏.

إعداد العميل

وجِّه أي عميل يدعم ‏MCP‏ إلى النقطة بمفتاحك — الإعداد نفسه لـ‏Claude Desktop‏ و‏Cursor‏ (كلاهما يتكلم ‏streamable-http MCP‏):

claude_desktop_config.json
// Claude Desktop → claude_desktop_config.json
{
  "mcpServers": {
    "agent-gateway": {
      "url": "https://agw.orcanox.xyz/mcp",
      "headers": { "Authorization": "Bearer agw_…" }
    }
  }
}
mcp.json
// Cursor → ~/.cursor/mcp.json
{
  "mcpServers": {
    "agent-gateway": {
      "url": "https://agw.orcanox.xyz/mcp",
      "headers": { "Authorization": "Bearer agw_…" }
    }
  }
}
POST /mcp api-key #

نقطة ‏JSON-RPC 2.0‏ مكتوبة يدويًا — بلا SDK وبلا جلسات. كل طلب يحمل مفتاح ‏Bearer agw_…‏ نفسه؛ الأدوات تُرشَّح حسب صلاحيات المفتاح. ‏GET‏ يُعيد ‏405 Allow: POST‏. الطرق: ‏initialize‏ و‏tools/list‏ و‏tools/call‏ و‏ping‏.

الطلب

الحقلالنوعالوصف
jsonrpc'2.0'مطلوبدائمًا ‏"2.0"‏.
method'initialize' | 'tools/list' | 'tools/call' | 'ping'مطلوب‏initialize | tools/list | tools/call | ping‏ — إشعارات ‏notifications/*‏ تُقبَل بصمت.
idstring | numberاختيارييُعاد في الرد كما هو.
paramsobjectاختياريوسائط الطريقة — ‏tools/call‏ تأخذ ‏{name, arguments}‏.

مثال

curl -X POST https://agw.orcanox.xyz/mcp \
  -H "Authorization: Bearer agw_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id": 1,"method":"tools/list"}'

الاستجابة

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "agent-gateway",
      "version": "0.1.0"
    }
  }
}

الأخطاء

الحالةcodeمثال
401-32001{"code":-32001,"message":"invalid api key"}
403-32003{"code":-32003,"message":"missing required scope: memory:write"}
405method_not_allowed{"code":"method_not_allowed","message":"POST only — MCP speaks JSON-RPC over POST"}