الـ MCP (Model Context Protocol) بيدي Claude وصول مباشر لخدمات خارجية في الوقت الفعلي. على عكس ملفات الذاكرة اللي بتخزّن context ثابت، اتصالات الـ MCP بتخلّي Claude يجيب بيانات حيّة — الـ GitHub issues بتاعتك، قاعدة بيانات الـ production، قنوات Slack، أو أي خدمة عندها MCP server. في الموديول ده، هنغطي إزاي تضيف servers، وتفهم الـ scopes، وتستخدم أدوات الـ MCP بفعالية.
إضافة MCP Servers
أسرع طريقة لإضافة server هي أمر claude mcp add. اختار الـ transport المناسب لنوع الـ server: http للـ servers البعيدة، ws للـ servers البعيدة اللي محتاجة اتصال مستمر ثنائي الاتجاه (بتبعت أحداث من غير ما يُطلب منها)، stdio للـ processes اللي بتشتغل محليًا، وsse للـ servers البعيدة القديمة اللي لسه ما اتنقلتش لـ HTTP. (ملاحظة: الـ SSE مهجور — استخدم HTTP servers بدل كده حيث ما يكون متاحًا.) الـ WebSocket (ws) لازم يتضبط عن طريق JSON (حدد type: "ws" في .mcp.json) بدل flag الـ --transport، ومش بيدعم OAuth أو --transport. على Windows الأصلي، غالبًا هتحتاج تستخدم cmd /c لما تشغّل stdio servers بتستخدم npx.
# Add a remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Add a local Node.js server via stdio
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github
# Add with an auth header
claude mcp add --transport http my-api https://api.example.com/mcp \
--header "Authorization: Bearer $MY_TOKEN"أدر الـ servers بتاعتك بأوامر claude mcp list وclaude mcp get <name> وclaude mcp remove <name>. أمر /mcp جوه الـ session بيعرض الاتصالات النشطة وبيفعّل OAuth flows للـ servers اللي محتاجة authentication عبر المتصفح. من الإصدار v2.1.186 تقدر تشغّل الـ OAuth flow ده من غير ما تفتح session: claude mcp login <name> بيعمل authentication لـ server مظبوط مباشرةً من الـ shell بتاعك، وclaude mcp logout <name> بيمسح الـ credentials المخزّنة بتاعته. ضيف --no-browser عشان يطبع الـ authorization URL بدل ما يفتح المتصفح — مفيد عبر SSH، حيث تفتح الـ URL على جهازك المحلي وتلصق الـ redirect URL كامل في الـ prompt. من الأوامر المفيدة كمان: claude mcp reset-project-choices وclaude mcp add-from-claude-desktop وclaude mcp serve لما تحب Claude Code نفسه يشتغل كـ MCP server.
إعدادات الـ MCP بتتخزن في ~/.claude.json (ملف الإعدادات المحلي بتاعك) أو .mcp.json في root المشروع (مشترك مع الفريق). ملف .mcp.json بيتعمل له commit في git وبيطلب موافقة زملائك أول مرة يستعملوه. توسيع الـ environment variables بيشتغل في كل حقول الإعدادات — استخدم ${VAR:-default} كـ fallback:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}للجلسات السريعة — تجارِب مؤقتة، أو CI runs، أو محاولة إعادة إنتاج باق في بيئة معزولة — --mcp-config بيحمّل MCP servers من ملفات JSON من غير ما تلمس إعداداتك المحفوظة. الـ flag بياخد ملف JSON واحد أو أكتر (مفصولين بمسافة)، فنفس الأمر ممكن يضع shared config فوق local overrides. مع --strict-mcp-config بيتجاهل أي مصدر MCP تاني للجلسة دي، وده أنضف طريقة لإعادة إنتاج باق على مجموعة servers محددة:
# حمّل ملف إعدادات واحد للجلسة دي بس
claude --mcp-config ./ci-servers.json
# اجمع أكتر من ملف (مفصولين بمسافة)
claude --mcp-config "./shared-servers.json ./local-overrides.json"
# أعد إنتاج باق على server واحد بالظبط، متجاهلًا إعدادات الـ user/project
claude --strict-mcp-config --mcp-config ./repro.jsonالـ MCP servers دلوقتي بتتوصّل بشكل متزامن (concurrent) بشكل افتراضي. لما يكون عندك عدة servers متعرّفة — stdio servers محلية وremote connectors من claude.ai — بتتهيأ كلها بالتوازي عند بدء التشغيل بدل ما تشتغل واحد ورا التاني. ده بيقلل وقت بدء التشغيل بشكل ملحوظ للمشاريع اللي فيها تكاملات MCP كتيرة.
في نوعين مختلفين من الـ timeout بيتحكموا في سلوك الـ MCP. اضبط timeout بدء تشغيل الـ server باستخدام متغير البيئة MCP_TIMEOUT (مثلًا، MCP_TIMEOUT=10000 claude بيحط timeout للاتصال بـ 10 ثواني عند بدء التشغيل). أما تنفيذ الأدوات (tool execution) فله حد منفصل: ضيف حقل timeout بالميلي ثانية في إدخال الـ server في ملف .mcp.json — مثلًا "timeout": 600000 لعشر دقائق — عشان تحدد أقصى مدة لأي tool call واحد للـ server ده. القيمة دي على مستوى كل server بتتجاوز متغير البيئة MCP_TOOL_TIMEOUT لهذا الـ server فقط، وهي حد زمني صارم (hard wall-clock limit) مش بيمتد بإشعارات التقدّم (progress notifications)، والقيم الأقل من 1000 بيتم تجاهلها. كمان، الـ timeout اللي على مستوى كل server وقيمته 1000 أو أكتر بيشتغل كحد أدنى (floor) على الـ idle timeout: Claude Code مش بيلغي الـ tool calls بتاعة الـ server ده بسبب الـ idleness قبل ما يعدّي الـ per-server timeout (محتاج Claude Code v2.1.203 أو أحدث).
الـ MCP connectors اللي متعرّفة في Claude.ai ممكن تظهر تلقائيًا في Claude Code. لو عرّفت server من خلال الـ web interface، هيبقى متاح في جلسات الـ CLI بتاعتك من غير إعداد محلي منفصل. ولو نفس الـ server متعرّف محليًا وعبر Claude.ai، التكرار بيتشال تلقائيًا عشان ما ينتهيش عندك اتصالين لنفس الخدمة.
الـ Scopes واكتشاف الأدوات
إعدادات الـ MCP ليها تلات scopes. الـ Local scope (بيتخزن جوه ~/.claude.json تحت المفتاح الخاص بالمشروع) خاص — أنت بس، في المشروع ده بس. الـ Project scope (.mcp.json) مشترك مع الفريق عبر git. الـ User scope (~/.claude.json بشكل عام) بيتطبق على كل مشاريعك.
لما نفس الـ server يتعرّف في أكتر من scope، الـ local configuration بيكسب. ده بيخليك تعدّل إعدادات server مشترك مع الفريق بنسخة محلية للاختبار من غير ما تأثر على أي حد تاني.
الـ MCP prompts بتظهر كـ slash commands بالنمط /mcp__servername__promptname. الـ MCP resources ممكن تتعامل معاها inline بالصيغة @server:protocol://resource/path. الـ Tool Search مفعّل بشكل افتراضي — تعريفات أدوات MCP بتتأجّل وتُكتشف عند الطلب، فبس الأدوات اللي Claude يستخدمها فعلًا في المهمة الحالية بتدخل الـ context. في الإعدادات اللي من غيرها tool search — زي ENABLE_TOOL_SEARCH=false، أو model أقدم من Claude Opus 4.5 و Sonnet 4.5 و Haiku 4.5 على Google Cloud’s Agent Platform — Claude بيستخدم أداة WaitForMcpServers بدل كده. الـ custom ANTHROPIC_BASE_URL gateway مش من الإعدادات دي: الـ tool search عنده مفعّل افتراضيًا. تقدر تتحكم فيه بمتغير البيئة ENABLE_TOOL_SEARCH: قيمة true بتسيب أدوات MCP متأجّلة، بنفس الـ fallbacks اللي بتتحصل لما المتغير يفضل من غير ما تظبطه — فعلى model أقدم من Opus 4 و Sonnet 4، وعلى الـ models الأقدم على Google Cloud’s Agent Platform، وعلى Microsoft Foundry deployments اللي مستضافة على Azure، الأدوات بتفضل بتحمّل مقدمًا وENABLE_TOOL_SEARCH=true مش بيلغي كده — وfalse بتحمّل كل التعريفات مقدمًا في كل turn، وauto بتفعّل الـ tool search بس لما تعريفات الأدوات تتعدى 10% من الـ context window (وauto:N بتحدد نسبة مخصصة). كل description لأداة MCP وتعليمات الـ server محدودة بـ 4,096 character لما تتحمّل مقدمًا، وdescription الأداة اللي بتتحمّل عن طريق tool search محدودة بـ 16,384 character، عشان ما تستهلكش servers اللي بتولّد OpenAPI context زيادة. عشان تغيّر الـ limit لكل MCP server في الـ session بتاعك، اضبط متغير البيئة CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH على عدد الـ characters. المتغير ده محتاج Claude Code v2.1.280 أو أحدث. تحذير بيظهر وقت الـ output بتاع أداة MCP لو تجاوز 10,000 token. عشان تزيد الـ limit، اضبط متغير البيئة MAX_MCP_OUTPUT_TOKENS (الافتراضي 25,000).
عشان تلغي الـ deferral لـ server معين، ضيف alwaysLoad: true في الـ config بتاعه — كل الأدوات من الـ server ده هتتخطى الـ tool-search deferral وتكون دايمًا متاحة في الجلسة. ضبط alwaysLoad: true كمان بيوقف الـ startup لحد ما الـ server ده يتوصل — دي محاولة اتصال مستقلة محدودة بـ 5 ثواني كحد أقصى — لأن أدواته لازم تكون موجودة وقت بناء أول prompt؛ باقي الـ servers المضبوطة بتفضل بتتوصل في الخلفية.
Claude Code بيتصل بالـ MCP servers عن طريق واحد من اثنين client runtimes. الـ v1 runtime بيستخدم MCP TypeScript SDK 1.x؛ والـ v2 runtime بيستخدم SDK 2.0، اللي بيضيف MCP protocol revision 2026-07-28. Claude Code بيختار الـ runtime عند بداية الجلسة ويفضل عليه لحد ما تقفل — والـ v2 runtime هو الافتراضي في الإصدارات الأخيرة. في الـ v2 runtime، Claude Code بيسأل الـ HTTP servers والـ stdio servers والـ claude.ai connector servers هل بتدعم الـ revision الأحدث ويستخدمها مع اللي بيدعموها — ودي تشمل connectors بتاعت جلسات الـ cloud والـ Remote Control. بالنسبة للـ local stdio servers، التفاوض ده اتطرح تدريجيًا من v2.1.285 (في جلسات الـ feature-flag، أو في أي مكان تضبط فيه MCP_PROTOCOL_NEGOTIATION=auto)، واعتبارًا من v2.1.292 بقى الافتراضي في كل تثبيت (every install)، بما في ذلك Bedrock و Vertex و Foundry. أي server تاني (زي الـ SSE) بيتصل زي ما الـ v1 بيعمل. اضبط متغير البيئة MCP_PROTOCOL_NEGOTIATION على legacy عشان يخلي كل الـ servers على الـ handshake الأقدم، أو على auto عشان يسأل الـ connector والـ stdio servers في كل جلسة. وعشان تختار الـ runtime بنفسك بدل كده، اضبط MCP_SDK_GENERATION على v1 أو v2.
الـ subagent-scoped MCP بيخليك تدي agents معينة وصول لـ servers باقي الـ session مش محتاجها:
---
name: data-analyst
description: Analyze production data
mcpServers:
- database
- playwright:
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
---أنماط استخدام عملية
لما يكون GitHub MCP متوصل، تقدر تتعامل مع الـ PRs والـ issues والـ commits بلغة طبيعية. Claude بيسأل الـ server، يجيب بيانات حيّة، ويرد:
List all open PRs that haven't been reviewed in more than 3 days.
Create an issue for the login timeout bug with medium priority.
/mcp__github__pr_review 456الـ database MCP بيخليك تعمل queries بلغة طبيعية من غير ما تكتب SQL بنفسك:
Find all users who placed more than 5 orders in the last 30 days.
What's the average order value by country for Q1 2026?للـ workflows المعقدة، أكتر من MCP server بيشتغلوا مع بعض بشكل طبيعي. workflow يومي ممكن: يجيب PR metrics من GitHub MCP، ويعمل query لبيانات المبيعات من database MCP، ويكتب تقرير عبر filesystem MCP، وينشره عبر Slack MCP — كل ده في session واحدة.
الـ MCP elicitation بتسمح لـ server يوقف الـ workflow ويطلب input منظم من المستخدم. لما server يحتاج معلومة مش قادر يجيبها لوحده — تصريح OAuth، أو تأكيد قبل عملية خطيرة، أو form بـ parameters خاصة بالمشروع — بيعمل dialog تفاعلي. المستخدم بيشوف حقول form أو URL للمتصفح، بيدي الرد، والـ server بيكمّل من حيث ما وقف. الـ hooks Elicitation وElicitationResult بيخلوك تعترض أو تعدّل الحوارات دي برمجيًا.
أفضل ممارسات الأمان: استخدم دايمًا environment variables للـ credentials، ما تعملش commit لـ tokens في git أبدًا، استخدم read-only tokens لما تحتاج تقرأ بيانات بس، وحدد وصول الـ server للحد الأدنى المطلوب. للمؤسسات، managed-mcp.json بيخلّي المسؤولين يفرضوا allowlist من الـ servers المسموح بيها على مستوى المنظمة.
المؤسسات تقدر كمان تفلتر الـ servers اللي المستخدمين بيظبطوها بإعدادين تانيين: allowedMcpServers وdeniedMcpServers. جنب managed-mcp.json اللي بتنشر set ثابت من الـ servers، وإعداد managedMcpServers المُدار اللي بيقدّم servers جنب اللي المستخدم بيضيفها، الاتنين هم آلية التالتة لتقييد الوصول لـ MCP — allowedMcpServers هي قائمة السماح وdeniedMcpServers هي قائمة الحظر. ابتداءً من v2.1.305، allowedMcpServers مبقتش تفلتر stdio server من managed-mcp.json متغيرات متعرفة في env بس، فسيرفر كان allowlist بتاعك مش شايفه بقى بيتحمّل بعد التحديث؛ استخدم deniedMcpServers لو عايز تفضله مقفول.
من الإمكانيات المهمة التانية في الـ MCP: servers الـ MCP ممكن تبعت إشعارات list_changed عشان تحدّث الأدوات والـ prompts والـ resources المتاحة ديناميكيًا من غير ما تحتاج تعمل reconnect. لو HTTP server أو SSE server انقطع في نص الجلسة، Claude Code بيعمل reconnect تلقائيًا بـ exponential backoff — لحد خمس محاولات، كل مرة بتبدأ بتأخير ثانية وبتتضاعف. للتوصيلات الأولية عند بدء التشغيل، نفس الـ backoff بيتطبّق بس لحد تلات محاولات في حالة أخطاء مؤقتة زي استجابة 5xx، أو رفض الاتصال، أو timeout (ابتداءً من v2.1.121). لما يكون فيه server أو أكتر فشل في الاتصال أو مستني authentication، /mcp reconnect all في الـ terminal التفاعلي بيعيد محاولة الاتصال بيهم كلهم مرة واحدة (v2.1.284+) — أسرع من إعادة الاتصال بكل server لوحده من لوحة /mcp.
مهام MCP (MCP Tasks)
مش كل نداء MCP بيكون سؤال سريع. بعض الـ servers بيشغّلوا شغل طويلة بنفسهم — زي تصدير تقرير أو build — كـ MCP tasks، باستخدام MCP tasks extension. نداء الأداة عند Claude بيرجع بمجرد ما الـ server يقبل الشغل، فClaude بيكمل شغله بدل ما يستنى النتيجة. ولما الشغل يخلص، الـ transcript بيقول كده وClaude بياخد النتيجة — اطلبها من Claude لما تحتاجها.
عشان Claude يستنى نتيجة الـ task بدل ما يكمّل شغله، اضبط CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1:
# Make Claude wait for an MCP task's result
export CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1ده مش نفس إبقاء كل نداء MCP في الـ foreground. الشغل اللي بياخد أكتر من حد الـ automatic-backgrounding الافتراضي (دقيقتين) لسه بيتحوّل لـ background call عادي، وكمان بيضيّع قدرة الـ MCP task إنه يفضل موجود بعد ما الجلسة تتقفل. ولو عايز كل نداء MCP يفضل في الـ foreground، اضبط:
# Keep every MCP call in the foreground
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0القنوات (Channels): بعت أحداث لجلسة شغّالة
القنوات هي MCP servers بتبعت أحداث لجلستك الشغّالة عشان Claude يتفاعل وأنت مش قدام الـ terminal. على عكس MCP servers العادية اللي Claude بيسألها عند الحاجة، القناة بتوصّل رسائل بشكل استباقي — جسر محادثة من Telegram، webhook من CI، أو تنبيه مراقبة. الأحداث بتوصل بس والجلسة مفتوحة.
الـ --channels flag اتضاف في v2.1.80 كـ research preview feature. القنوات محتاجة Claude Code v2.1.80 أو أحدث — افتكر claude --version عشان تتأكد من الإصدار المثبت عندك. التلات plugins دي مُضمّنة: Telegram وDiscord وiMessage. كل واحد بيتثبّت كـ plugin وبيتضبط بالـ credentials بتاعتك. ثبّت plugin قناة بـ /plugin install telegram@claude-plugins-official، اضبطه بأمر /telegram:configure <token>، وبعدين أعد التشغيل بـ flag الـ --channels:
claude --channels plugin:telegram@claude-plugins-officialكل قناة عندها allowlist للمُرسلين — بس الـ IDs اللي ضفتها تقدر تبعت رسائل. Telegram وDiscord بيستخدموا pairing flow: ابعت رسالة للبوت بتاعك، استلم كود، واقبله في Claude Code بـ /telegram:access pair <code> وقفّل الوصول بـ /telegram:access policy allowlist. iMessage بيتخطى الـ pairing لما تبعت لنفسك وبيخلّيك تضيف جهات اتصال بالـ handle.
القنوات محتاجة Anthropic authentication (claude.ai أو Console API key) ومش متاحة على Bedrock أو Vertex AI أو Foundry. مؤسسات Team وEnterprise لازم تفعّل القنوات عن طريق channelsEnabled في الإعدادات المُدارة — مقفولة افتراضيًا. مستخدمي Pro وMax يقدروا يستخدموا القنوات مباشرة بالاشتراك بـ --channels في كل جلسة. المسؤولين كمان يقدروا يحددوا الـ channel plugins المسموح بيها عن طريق إعداد allowedChannelPlugins المُدار.
لما Claude يرد عبر قناة، الرد بيظهر على المنصة الخارجية (Telegram، Discord، إلخ) — الـ terminal بتاعك بيعرض الـ tool call والتأكيد بس مش نص الرد نفسه.