التوثيق
خادم MCP
POST /mcp خادم MCP بـJSON-RPC 2.0 مكتوب يدويًا — بلا SDK وبلا جلسات. كل طلب يحمل مفتاح Bearer agw_… نفسه؛ تعرض tools/list ما يجوز للمفتاح استدعاؤه فقط، وتفرض tools/call الصلاحيات نفسها كما في نقاط /v1. أدوات الذاكرة تظهر فقط للمفاتيح ذات صلاحيات الذاكرة.
الأدوات
| الحقل | scope | الوصف |
|---|---|---|
search_web | search | بحث ويب — خط /v1/search نفسه (query, k?, lang?). |
read_url | read | نص صفحة نظيف — محرك الجلب والاستخلاص الخاص بـ /v1/read (url). |
research | search | حزمة الأدلة الخاصة بـ /v1/research (question, depth?). |
remember | memory:write | تخزين عناصر في الذاكرة الخاصة (items[]). |
recall | memory: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_…" } } } }
نقطة 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/* تُقبَل بصمت. |
id | string | number | اختياري | يُعاد في الرد كما هو. |
params | object | اختياري | وسائط الطريقة — 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"}'
import requests r = requests.post("https://agw.orcanox.xyz/mcp", headers={"Authorization": "Bearer agw_…"}, json={"jsonrpc":"2.0","id": 1,"method":"tools/list"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/mcp", { method: "POST", headers: { "Authorization": "Bearer agw_…", "Content-Type": "application/json" }, body: JSON.stringify({"jsonrpc":"2.0","id": 1,"method":"tools/list"}) }); console.log(r.status, await r.json());
الاستجابة
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"} |
| 405 | method_not_allowed | {"code":"method_not_allowed","message":"POST only — MCP speaks JSON-RPC over POST"} |