الوحدة 11 — MCP: ربط Claude Code بأدواتك وبياناتك

يعرف Claude Code، كما يخرج من الطرفيّة، كيف يقرأ ملفّاتك، ويكتب شيفرةً، وينفّذ أوامر shell. يجهل كلّ ما عدا ذلك: مستودعك على GitHub، وقاعدة Postgres للاختبار، ونظام تتبّع التذاكر، وسلّة S3، ونظام المراقبة. الـMCP، أي Model Context Protocol، هو الآليّة الموحَّدة التي يتحدّث بها Claude Code إلى هذه الخدمات دون أن نكتب شيفرة الاندماج بأنفسنا.

المبدأ: بروتوكول واحد، ونقلات متعدّدة

MCP بروتوكول مفتوح. تعرِض الخدمة («خادم MCP») أدوات — إجراءات ذرّيّة مثل read_file وsearch_issues وrun_query — ويستدعيها Claude Code («عميل MCP») كما لو كانت أدوات داخليّة. مفردات الخرج متطابقة عند Claude: لا يهمّ إن كانت الأداة داخل العمليّة أم في أقصى العالم.

الذي يتغيّر هو النقل. أربعة نقلات موثَّقة:

النقل	حالة الاستعمال	ملاحظات
`http` (streamable-http)	خادم بعيد، خدمة سحابيّة	النقل الموصى به للخدمات السحابيّة، يدعم OAuth
`sse`	Legacy، بعض الخدمات لا تزال في SSE فقط	مُصنَّف مهجورًا، فضِّل HTTP
`stdio`	عمليّة محلّيّة، سكربت داخليّ، أداة CLI	مثاليّ لوصول مباشر إلى النظام أو قاعدة محلّيّة
`ws` (WebSocket)	خوادم بعيدة تدفع أحداثًا	لا يدعم OAuth ولا `--transport ws` في CLI؛ يُهيَّأ عبر JSON

يقبل حقل type في ملفّ التهيئة أيضًا streamable-http بديلًا لـhttp — وهو الاسم الرسميّ MCP، مفيد حين تلصق تهيئةً منسوخة من وثائق عميل آخر.

ثلاثة نطاقات لثلاث استخدامات

يُصرَّح خادم MCP في أحد ثلاثة نطاقات، لكلّ منها ملفّ وجهة ورؤية مختلفة.

النطاق	يُحمَّل في	مشترك مع الفريق	يُخزَّن في
Local	هذا المشروع فقط	لا	`~/.claude.json`
Project	هذا المشروع فقط	نعم، تحت الإدارة الإصداريّة	`.mcp.json` في جذر المشروع
User	كلّ مشاريعك	لا	`~/.claude.json`

يُختار النطاق في سطر الأوامر عبر --scope local|project|user (الافتراضيّ: local). عند تكرار الاسم بين النطاقات، الأولويّة هي local > project > user > plugin > موصل claude.ai: يستخدم Claude Code المُدخَل كاملًا من النطاق الأعلى أولويّةً، دون دمج حقل بحقل.

انتبه لفخّ أمنيّ: الخوادم المُصرَّحة في .mcp.json تحت الإدارة الإصداريّة تتطلّب موافقة يدويّة عند أوّل فتح للمشروع. في جلسة claude -p (headless) أو في SDK، لا يوجد سؤال: يُحمِّل Claude Code الخوادم دون طلب، إلّا إذا أضفت --strict-mcp-config أو أدرجت الخادم في disabledMcpjsonServers. مستودع مستنسَخ لتوّه لم يُوافَق بعد على نافذة workspace trust الخاصّة به، يبقى فيه كلّ خادم بحالة ⏸ Pending approval.

تثبيت خادم: الطرق الأربع

خادم بعيد HTTP

هو الخيار الموصى به لربط خدمة سحابيّة. الصياغة:

claude mcp add --transport http <nom> <url>
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer <token>"

خادم بعيد SSE

يُحفَظ للخدمات التي لا تعرض إلّا نقطة SSE. صياغة مماثلة مع --transport sse. ميزة مهجورة، فهاجر إلى HTTP متى سمحت الخدمة.

خادم محلّيّ stdio

خادم stdio عمليّة يُطلقها Claude Code على جهازك، وتتبادل عبر الواصفات القياسيّة. يُفصَل بين خيارات claude mcp add والأمر المطلوب تشغيله بواسطة --:

claude mcp add [options] <nom> -- <commande> [args...]

يحقن Claude Code تلقائيًّا CLAUDE_PROJECT_DIR في بيئة عمليّة الخادم، مشيرًا إلى جذر المشروع. يبقى ثابتًا طوال الجلسة، مستقلًّا عن المجلّد الجاري. تُمرَّر المتغيّرات عبر --env KEY=value، وتُوضَع قبل -- لا مباشرةً بعده إذا تلاه اسم الخادم:

claude mcp add --env AIRTABLE_API_KEY=<clé> --transport stdio airtable \
  -- npx -y airtable-mcp-server

خادم بعيد WebSocket

مخصّص للخوادم التي تدفع أحداثًا دون طلب. لا يقبل --transport قيمة ws في CLI؛ مرّ عبر claude mcp add-json أو حرِّر .mcp.json مباشرةً:

claude mcp add-json events '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer <token>"}}'

تشريح `.mcp.json`

الصيغة المعياريّة، القابلة للإدارة الإصداريّة والمشاركة، تبدو هكذا:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

نقطتان أساسيّتان. مُدخَل بـurl من دون type خطأ: يقرأ Claude Code الخادم عندئذٍ بوصفه stdio فيفشل، ويعرض MCP server "<nom>" has a "url" but no "type". أضِف صراحةً "type": "http" (أو "sse" أو "ws"). يُقبَل توسيع ${VAR} في command وargs وenv وurl وheaders، وله صيغتان: ${VAR} (يفشل بصمت مع تحذير إن غاب) و${VAR:-قيمة افتراضيّة}. يسمح ذلك بإيداع .mcp.json علنًا دون كشف الأسرار — يضع كلّ مطوّر قيمته في بيئته.

إدارة الخوادم

مجموعة أوامر CLI تغطّي دورة الحياة.

الأمر	الدور
`claude mcp add [options] <nom> ...`	إضافة خادم (الافتراضيّ: نطاق local)
`claude mcp add-json <nom> <json>`	إضافة من سلسلة JSON
`claude mcp list`	سرد كلّ الخوادم المُهيَّأة، مع حالة الصحّة
`claude mcp get <nom>`	تفصيل خادم، والـendpoint المُحلَّل، والحالة
`claude mcp remove <nom>`	حذف خادم (يمحو رموز OAuth أيضًا)
`claude mcp login <nom>`	إطلاق تدفّق OAuth من الـshell
`claude mcp logout <nom>`	إبطال المصادقة المخزَّنة
`claude mcp reset-project-choices`	إعادة تعيين موافقات `.mcp.json`

في الجلسة التفاعليّة، يفتح الأمر /mcp لوحةً تعرض الخوادم وحالتها (Connected أو Needs authentication أو Failed to connect أو Pending approval أو cached)، وعدد أدواتها، وتتيح تعطيل خادم دون حذفه، أو إعادة وصله، أو تنظيف مصادقته.

مصادقة OAuth

خادم بعيد يُرجع 401 أو 403 يُوسم بأنّه «needs authentication». افتح /mcp، واختر Sign in، فيفتح متصفّح لتدفّق OAuth. بديل في سطر الأوامر منذ v2.1.186: claude mcp login <nom>.

نقطتان تشغيليّتان دقيقتان. على جلسة SSH بلا متصفّح محلّيّ، يطبع الأمر رابط التفويض لفتحه يدويًّا ثمّ ينتظر لصق رابط إعادة التوجيه — اتّصل بـssh -t لتكون الطرفيّة تفاعليّة. وإذا هيّأت أنت رأس Authorization (عبر --header أو headersHelper)، فلن يُطلق 401 تدفّق OAuth: يعدّ Claude Code الاعتماد قادمًا منك ويُبلِّغ فقط بفشل الاتّصال.

Kiosque: ملفّ `.mcp.json` كامل

يريد فريق Kiosque خادمَين: GitHub لقراءة issues، وفتح PR، وقراءة المراجعات التلقائيّة (HTTP بعيد، مصادقة بـ PAT)؛ وPostgres للقراءة فقط للاستفسار عن قاعدة الاختبار (stdio محلّيّ، DSN في متغيّر بيئة).

تُنشئ نادية الملفّ في الجذر وتُودعه في git. تبقى الأسرار خارجًا، في .env المحلّيّ لكلّ فرد:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_MCP_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--dsn",
        "${KIOSQUE_DB_DSN:-postgresql://readonly:local@localhost:5432/kiosque}"
      ]
    }
  }
}

يُذكَر الحزمة @bytebase/dbhub كما وردت في التوثيق الرسميّ (مثال عمليّ في mcp.md)؛ تُتيح لـClaude الوصول إلى قاعدة علائقيّة عبر DSN، بمستخدم قراءة فقط لمنع أيّ كتابة. يُشير الـDSN الافتراضيّ إلى قاعدة محلّيّة: يبدّل كلّ مطوّر إلى قاعدته عبر KIOSQUE_DB_DSN في بيئته.

عند أوّل فتح، يرى كريم نافذة workspace trust، فيقبل، ثمّ يمرّ كلّ خادم بـ⏸ Pending approval — فيوافق. لـGitHub HTTP، يُطلق بعد ذلك claude mcp login github ويُتمّ تدفّق OAuth (أو يُدخل PAT إن فرضت المنظّمة ذلك). لـPostgres، يُطلق Claude Code الأمر npx -y @bytebase/dbhub ... عند أوّل استعمال.

ما يمكن أن يفعله Claude بعد الاتّصال

على قناة GitHub، يستطيع كريم أن يطلب: «لخِّص آخر 20 issue مفتوحة موسومة bug، وصنّفها حسب الوحدة». يستدعي Claude Code search_issues، ويُجمِّع، ويُلخِّص — دون أن يحتاج كريم إلى كتابة curl. على قناة Postgres: «ما متوسّط سلّة الطلبات المُسلَّمة هذا الشهر؟» — يُركّب Claude Code استفسار SQL للقراءة فقط، ويُنفّذه، ثمّ يُعيد النتيجة بلغة طبيعيّة.

ثلاثة احتياطات تستحقّ التكرار.

مستخدم Postgres يجب أن يكون للقراءة فقط على مستوى القاعدة. hook PreToolUse على أدوات mcp__postgres__* يستطيع التعزيز، لكنّ القاعدة هي مصدر الحقيقة.
PAT GitHub يجب أن يكون دقيقًا (fine-grained) ومحصورًا بالمستودعات التي يحتاج Claude إليها. رمز واسع باب دخول خطر.
.mcp.json تحت الإدارة الإصداريّة لا يجب أن يحوي أيّ سرّ، بل فقط ${VAR} بقيم افتراضيّة عامّة. الأسرار الحقيقيّة تعيش في .env المحلّيّ أو في مدير أسرار.

الـSDK والأدوات المخصّصة

إن لم يفِ أيّ خادم MCP بالحاجة، يمكن كتابة واحد. جانب الخادم يتبع مواصفة MCP الرسميّة ويُبرمَج بأيّ لغة. في جانب Claude Code، مقاربة أخفّ تعرِّف أداةً مخصّصة عبر Agent SDK: يصف التوثيق agent-sdk__custom-tools.md آليّةً لإتاحة دالّة محلّيّة أداةً MCP داخل العمليّة، دون تشغيل خادم خارجيّ. يُفيد ذلك بشكل خاصّ للأدوات الأعماليّة الخاصّة بـKiosque — مثلًا استدعاء API الداخليّ لحساب العمولة — حين لا نريد نشرها خادمًا MCP قابلًا لإعادة الاستعمال.

`/mcp` في الجلسة: لوحة التحكّم

بمجرّد التهيئة، يُعطي /mcp صورة اللحظة. يُعرَض كلّ خادم مع:

نقله وendpoint (مع ${VAR} غير مُوسَّعة على الشاشة — لا سرّ يظهر أبدًا).
حالته: Connected، أو Needs authentication، أو Failed to connect، أو ⏸ Pending approval، أو ⊘ Disabled for this project، أو cached (أدوات مُحمَّلة من ذاكرة اكتشاف).
عدد أدواته.
قائمة لكلّ خادم: Sign in، Re-authenticate، Clear authentication، Reconnect، تعطيل على مستوى المشروع.

عند الفشل، يعرض سطر Issue: رمز HTTP المُعاد (401 أو 403 أو 500…) ونصّ خطأ الخادم، دون تضمين الرابط الكامل — تُحمى الأسرار التي قد يحويها.

تصحيح سريع

خادم بحالة Failed to connect مع 401: الرمز على الأرجح خاطئ أو منتهي الصلاحيّة. بحالة Failed to connect مع رمز شبكة: نفّذ dig أو curl على الرابط يدويًّا للتحقّق من الاتّصال. إن ظلّ Pending approval طويلًا: نطاق العمل ليس trusted؛ اكتب claude في المجلّد وتقبّل النافذة.

الخلاصة

يُوحِّد MCP وصول Claude Code إلى الخدمات الخارجيّة؛ أربعة نقلات: http (موصى به)، وsse (مهجور)، وstdio (محلّيّ)، وws (دفع).
ثلاثة نطاقات: local (~/.claude.json، خاصّ)، وproject (.mcp.json، تحت الإدارة الإصداريّة، يتطلّب موافقة)، وuser (~/.claude.json، كلّ مشاريعك).
CLI: claude mcp add وadd-json وlist وget وremove وlogin وlogout وreset-project-choices. في الجلسة: يفتح /mcp لوحة التحكّم.
.mcp.json: صيغة {"mcpServers": {...}}، وتوسيع ${VAR:-قيمة افتراضيّة} في command وargs وenv وurl وheaders؛ type إلزاميّ للخوادم البعيدة.
المصادقة: OAuth آليّ على الخوادم البعيدة؛ claude mcp login <nom> من دون المرور عبر /mcp؛ رأس Authorization تقدّمه أنت يتجاوز OAuth.
لـKiosque، يكفي .mcp.json بمُدخلَين: GitHub HTTP مُصادَق عليه بـ PAT، وPostgres stdio للقراءة فقط عبر DSN مُمرَّر بـ${VAR:-قيمة افتراضيّة}.

الوحدة التالية: Plugins وmarketplaces: تعبئة أدواتك ومشاركتها — كيف نجمع skills وسب-agents وhooks وخوادم MCP في plugin واحد وننشره لكامل الفريق.

المبدأ: بروتوكول واحد، ونقلات متعدّدة​

ثلاثة نطاقات لثلاث استخدامات​

تثبيت خادم: الطرق الأربع​

خادم بعيد HTTP​

خادم بعيد SSE​

خادم محلّيّ stdio​

خادم بعيد WebSocket​

تشريح .mcp.json​

إدارة الخوادم​

مصادقة OAuth​

Kiosque: ملفّ .mcp.json كامل​

ما يمكن أن يفعله Claude بعد الاتّصال​

الـSDK والأدوات المخصّصة​

/mcp في الجلسة: لوحة التحكّم​

الخلاصة​