إعداد خوادم MCP مع Claude Code: شرح عملي خطوة بخطوة

إذا قضيت أي وقت في Claude Code ولاحظت قسم MCP في الإعدادات، فمن المرجّح أنك تساءلت عمّا يفعله فعليًا، ومدى صعوبة إعداده، وهل يستحق الجهد. الإجابة المختصرة: نعم، ويستحق ذلك بقدر كبير. MCP (Model Context Protocol) هو الآلية التي تمكّن Claude من الوصول إلى ما خارج نافذة السياق الخاصة به، واستدعاء دوال حقيقية، والاستعلام عن قواعد بيانات حقيقية، والتفاعل مع واجهات API حقيقية، وكل ذلك من داخل المحادثة.

يستعرض هذا المقال كل شيء بدءًا من فهم ماهية MCP وصولًا إلى تشغيل أول خادم مخصص لك مع Claude Code، ويتضمن أمثلة إعداد حقيقية يمكنك نسخها فورًا.

ما هو MCP فعلًا

MCP بروتوكول مفتوح طوّرته Anthropic، ويوحّد طريقة تواصل نماذج الذكاء الاصطناعي مع الأدوات ومصادر البيانات الخارجية. فكّر فيه كمصافحة منظّمة: يعلن خادمك الأدوات التي يقدّمها، ويستدعيها Claude بالوسائط الصحيحة ويعالج النتائج.

قبل MCP، كان كل تكامل مخصصًا. كنت تكتب تعليمات نظام خاصة، وتجمع مخططات استدعاء الدوال بطرق يدوية، وتأمل أن يلتزم النموذج بالمواصفات. يوحّد MCP كل ذلك في طبقة واحدة متوقعة.

يحدّد البروتوكول ثلاثة عناصر أساسية:

تغطي هذه العناصر الثلاثة تقريبًا كل سيناريو تكامل ستواجهه. تتولى الأدوات الإجراءات، وتتولى الموارد الوصول إلى البيانات، وتتولى الأوامر أنماط التفاعل القابلة لإعادة الاستخدام. والبروتوكول مستقل عن وسيلة النقل، أي أن شيفرة الخادم نفسها تعمل عبر stdio للتطوير المحلي، وعبر HTTP للنشر في بيئات الإنتاج.

وضعا النقل

تعمل خوادم MCP بأحد وضعي نقل. معرفة الفرق بينهما توفّر عليك ساعات من تصحيح الأخطاء.

stdio (الإدخال والإخراج القياسي)

يشغّل العميل (Claude Code) خادمك كعملية فرعية ويتواصل معه عبر stdin و stdout. هذا أبسط إعداد للأدوات المحلية وسير العمل الشخصي. لا حاجة إلى منافذ أو إعدادات شبكية أو مصادقة.

{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"]
    }
  }
}

نسخ الأمر النصي

HTTP مع SSE

يعمل خادمك كعملية HTTP مستقلة، ويتصل به Claude Code عبر الشبكة. هذا هو الخيار المناسب لخوادم الفرق المشتركة، وعمليات النشر في السحابة، أو أي خادم يحتاج إلى البقاء قيد التشغيل بين الجلسات.

{
  "mcpServers": {
    "my-tool": {
      "url": "http://localhost:3000/sse"
    }
  }
}

نسخ الأمر النصي

💡 ابدأ باستخدام stdio. لا يتطلب أي إعداد شبكي، وتصحيح أخطائه أسهل بكثير. انتقل إلى نقل HTTP فقط عندما تحتاج إلى وصول مشترك أو حالة خادم دائمة.

تثبيت SDK لبروتوكول MCP

يبدأ كل خادم MCP بالطريقة نفسها: تثبيت SDK الرسمي وضبط TypeScript لاستخدام ESM.

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

نسخ الأمر النصي

ابدأ إعداد TypeScript:

npx tsc --init

نسخ الأمر النصي

حدّث tsconfig.json ليستهدف وحدات ESM:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "strict": true
  }
}

نسخ الأمر النصي

أضف السكربتات إلى package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

نسخ الأمر النصي

حقل "type": "module" ليس اختياريًا. فمن دونه يعامل Node ملفاتك على أنها CommonJS، فيفشل كل استيراد ESM عند بدء التشغيل.

كتابة أول أداة لك

أنشئ src/index.ts وعرّف أول أداة لك باستخدام مخطط Zod مكتوب النوع:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-first-server",
  version: "1.0.0",
});

server.tool(
  "get_weather",
  "Get current weather for a city",
  {
    city: z.string().describe("City name"),
    units: z.enum(["celsius", "fahrenheit"]).optional().default("celsius"),
  },
  async ({ city, units }) => {
    const temp = units === "celsius" ? "22°C" : "72°F";
    return {
      content: [
        {
          type: "text",
          text: `Weather in ${city}: ${temp}, partly cloudy`,
        },
      ],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

نسخ الأمر النصي

ابنِ المشروع وتحقّق من أن الترجمة تمت بنجاح:

npx tsc
node dist/index.js

نسخ الأمر النصي

هذا خادم MCP يعمل. يعرض أداة واحدة بمخطط مكتوب النوع يتحقق منه Claude قبل الاستدعاء.

التسجيل في Claude Code

افتح إعدادات Claude Code وانتقل إلى قسم MCP. أضف إدخال خادمك باستخدام المسار المطلق إلى الملف المترجم:

{
  "mcpServers": {
    "my-first-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
    }
  }
}

نسخ الأمر النصي

أعد تشغيل Claude Code، وافتح محادثة جديدة واسأل: "ما حالة الطقس في باريس؟"

إذا كان كل شيء مرتبطًا بشكل صحيح، فسيستدعي Claude الأداة get_weather بالقيمة city: "Paris" ويعرض النتيجة في ردّه. سترى استدعاء الأداة يظهر في المحادثة.

💡 استخدم دائمًا المسارات المطلقة في إعداد MCP. المسارات النسبية تتعطل بصمت حسب الطريقة التي يحدد بها Claude Code مجلد العمل وقت التشغيل.

بناء خادم حقيقي بهيكل منظّم

تحتاج الخوادم الحقيقية إلى فصل واضح بين تعريفات المخططات والمعالجات ومنطق الخدمة. فيما يلي بنية الملفات التي تتسع مع نمو المشروع دون أن تصبح صعبة الصيانة:

src/
  index.ts            # Entry point and server setup
  tools/
    definitions.ts    # Zod schemas for each tool input
    handlers.ts       # Business logic per tool
  services/
    api.ts            # External API calls
    db.ts             # Database access layer

نسخ الأمر النصي

يحتوي definitions.ts على جميع مخططات Zod:

import { z } from "zod";

export const searchInputSchema = {
  query: z.string().min(1).describe("Search query text"),
  limit: z.number().int().min(1).max(50).optional().default(10),
};

نسخ الأمر النصي

يحتوي handlers.ts على التنفيذ:

export async function handleSearch(
  args: { query: string; limit?: number }
) {
  const results = await searchApi(args.query, args.limit ?? 10);
  return {
    content: [{ type: "text" as const, text: JSON.stringify(results, null, 2) }],
  };
}

نسخ الأمر النصي

يربط index.ts العناصر ببعضها في استدعاء واحد server.tool() لكل أداة. يعني هذا الفصل أنه يمكنك اختبار المعالجات من دون تشغيل خادم، وتبديل المخططات دون المساس بمنطق العمل.

5 أخطاء شائعة في الإعداد

هذه الأخطاء هي التي تُوقع تقريبًا كل من يبني أول خادم MCP له.

1. نسيان لاحقات الملفات .js في الاستيرادات

يتطلب حل الوحدات في Node16 لاحقات .js صريحة حتى داخل ملفات TypeScript المصدرية. إغفالها يسبب أخطاء استيراد وقت التشغيل مربكة، لأن مترجم TypeScript لا يلتقطها.

// This fails at runtime with ERR_MODULE_NOT_FOUND
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";

// This works correctly
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

نسخ الأمر النصي

2. استخدام console.log() في خوادم stdio

في وضع stdio، يكون stdout هو قناة البروتوكول. أي استدعاء console.log() يكتب نصًا عشوائيًا في هذه القناة ويفسد تدفق MCP. استخدم console.error() لكل مخرجات التصحيح.

3. نسيان await عند اتصال الخادم

// Wrong: process may exit before connection completes
server.connect(transport);

// Correct: wait for connection handshake
await server.connect(transport);

نسخ الأمر النصي

4. المسارات النسبية في إعداد Claude Code

يبدأ Claude Code من مجلدات عمل مختلفة. ضع دائمًا مسارات مطلقة مثبتة في الشيفرة، أو حدّدها عند بدء التشغيل باستخدام import.meta.url.

5. أوصاف أدوات عامة أكثر من اللازم

يستخدم Claude وصف الأداة ليقرر متى يستدعيها. الأوصاف الغامضة مثل "يفعل أشياء" تؤدي إلى استدعاء الأداة أكثر من اللازم أو عدم استدعائها أبدًا. كن محددًا: "اجلب طلب سحب من GitHub باستخدام المالك والمستودع ورقم الطلب."

نقل HTTP لخوادم الفرق

عندما يحتاج خادمك إلى المشاركة عبر فريق أو التشغيل في بيئة سحابية، يكون HTTP مع SSE هو وسيلة النقل المناسبة:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import express from "express";

const app = express();
const server = new McpServer({ name: "team-server", version: "1.0.0" });

const transports: Record<string, SSEServerTransport> = {};

app.get("/sse", async (req, res) => {
  const transport = new SSEServerTransport("/messages", res);
  transports[transport.sessionId] = transport;
  await server.connect(transport);
});

app.post("/messages", express.json(), async (req, res) => {
  const sessionId = req.query.sessionId as string;
  const transport = transports[sessionId];
  if (transport) await transport.handlePostMessage(req, res);
});

app.listen(3000, () => console.error("MCP server listening on :3000"));

نسخ الأمر النصي

يحتفظ كل عميل Claude Code بنقل الجلسة الخاص به، لذا يستطيع عدة مستخدمين الاتصال في الوقت نفسه دون أن يتداخلوا.

عرض الموارد

تتيح الموارد لنموذج Claude قراءة البيانات المنظمة دون استدعاءات أدوات صريحة. وهي العنصر المناسب للإعدادات والتوثيق والحالة المخزّنة مؤقتًا التي ينبغي أن يكون Claude على علم بها دون الحاجة إلى تعريف أداة جلب مخصصة.

server.resource(
  "config://app",
  "Application configuration and feature flags",
  async (uri) => ({
    contents: [
      {
        uri: uri.toString(),
        mimeType: "application/json",
        text: JSON.stringify({
          version: "2.1.0",
          features: { darkMode: true, betaSearch: false },
          limits: { maxResults: 50, timeoutMs: 5000 },
        }),
      },
    ],
  })
);

نسخ الأمر النصي

يمكن لنموذج Claude أن يشير إلى config://app في سياقه ويقرأ هذه البيانات بشكل استباقي، ما يقلل عدد استدعاءات الأدوات اللازمة في المحادثة.

تصحيح الأخطاء باستخدام MCP Inspector

يُعد MCP Inspector ضروريًا أثناء التطوير. يوفر واجهة مرئية تتيح لك استدعاء أدواتك مباشرة دون المرور عبر Claude Code:

npx @modelcontextprotocol/inspector node dist/index.js

نسخ الأمر النصي

افتح http://localhost:5173. سترى جميع الأدوات المسجلة ومخططاتها، ونموذجًا لاستدعاء كل أداة مباشرة بأي مدخلات تختارها. يظهر طلب JSON والرد الخام، ما يجعل اكتشاف عدم تطابق الأنواع أو الحقول المفقودة أمرًا سهلًا.

بالنسبة لخوادم HTTP:

npx @modelcontextprotocol/inspector http://localhost:3000/sse

نسخ الأمر النصي

💡 انتبه لعدم تطابق المخططات. إذا قال Claude Code إن الأداة مسجلة لكنه لا يستدعيها أبدًا، فالسبب الأكثر شيوعًا هو مخطط Zod يرفض الوسائط التي يرسلها النموذج. يتيح لك Inspector إعادة إنتاج هذه المشكلة دون إشراك Claude أصلًا.

الاتصال بالنماذج اللغوية الكبيرة عبر MCP

من أكثر الأنماط قيمة بناء خوادم MCP تنسّق استدعاءات عدة نماذج ذكاء اصطناعي. يصبح خادمك طبقة الوسيط، ويصبح Claude Code المنسّق.

يمكنك عرض أداة توجّه الطلبات إلى Deepseek R1 للاستدلال العميق، أو GPT 5 للكتابة الإبداعية، أو Llama 4 Scout Instruct لمعالجة المستندات بسرعة. يختار Claude الأداة التي يستدعيها حسب المهمة المطروحة.

server.tool(
  "route_to_model",
  "Route a task to the most suitable language model for the job",
  {
    task: z.enum(["reasoning", "creative", "summarize"]),
    input: z.string().describe("The text input to process"),
  },
  async ({ task, input }) => {
    const modelMap = {
      reasoning: "deepseek-r1",
      creative: "gpt-5",
      summarize: "llama-4-scout",
    };
    const result = await callModelApi(modelMap[task], input);
    return { content: [{ type: "text", text: result }] };
  }
);

نسخ الأمر النصي

مع Claude Opus 4.7 كمنسّق، وخادم MCP الخاص بك كطبقة توزيع، تحصل على نظام متعدد النماذج يوجّه الطلبات بذكاء دون بنية تحتية معقدة.

تتيح Picasso IA الوصول إلى API للنماذج، ومنها Claude 4.5 Sonnet و Gemini 2.5 Flash و Claude 4 Sonnet، ما يجعل بناء أدوات MCP متعددة النماذج أمرًا عمليًا دون إدارة مفاتيح API منفصلة ومكتبات عميل لكل مزوّد.

معالجة أخطاء الأدوات

لا ينبغي أن ترمي أدوات MCP استثناءات غير معالجة أبدًا. أعد محتوى خطأ منظمًا حتى يتمكن Claude من الإبلاغ عن الإخفاقات بوضوح وتحديد الخطوة التالية:

server.tool(
  "safe_fetch",
  "Fetch content from an external URL",
  { url: z.string().url() },
  async ({ url }) => {
    try {
      const response = await fetch(url);
      if (!response.ok) {
        return {
          content: [
            {
              type: "text",
              text: `Request failed: HTTP ${response.status} from ${url}`,
            },
          ],
          isError: true,
        };
      }
      return { content: [{ type: "text", text: await response.text() }] };
    } catch (err) {
      return {
        content: [{ type: "text", text: `Network error: ${String(err)}` }],
        isError: true,
      };
    }
  }
);

نسخ الأمر النصي

تشير العلامة isError: true إلى Claude بأن الاستدعاء فشل. عندئذٍ يقرر Claude ما إذا كان سيعيد المحاولة، أو يستخدم بديلًا، أو يعرض الخطأ على المستخدم.

ما الذي تبنيه بعد ذلك

بعد أن تعمل الأساسيات، تنفتح أمامك آفاق عملية. فيما يلي الأنماط التي تنشرها الفرق باستخدام MCP اليوم:

حالة استخدام خط أنابيب الصور قوية بشكل خاص. تبني خادم MCP يقبل أمرًا نصيًا من Claude، ويستدعي نموذج تحويل النص إلى صورة، ويرفع النتيجة إلى التخزين السحابي، ويعيد الرابط، كل ذلك في استدعاء أداة واحد يسلسله Claude بشكل طبيعي في المحادثة دون شيفرة تنسيق إضافية.

بالنسبة للفرق التي تبني سير عمل يتضمن توليد الصور، يمكن ربط أكثر من 90 نموذجًا متاحًا على منصات مثل Picasso IA كأدوات MCP، ما يمنح Claude وصولًا مباشرًا إلى نماذج الانتشار، وأدوات رفع الدقة، وخطوط تحرير الصور من داخل المحادثة.

جرّبها على Picasso IA

إذا أردت أن ترى ما هو ممكن مع نماذج الذكاء الاصطناعي قبل بناء تكاملات MCP الخاصة بك، فإن Picasso IA يضع أكثر من 90 نموذجًا لتحويل النص إلى صورة وعشرات النماذج اللغوية الكبيرة في متصفحك مباشرة. شغّل Claude Opus 4.6 أو GPT 5 أو Deepseek R1 أو Llama 4 Maverick Instruct دون أي إعداد.

إنها أسرع طريقة لاختبار مخرجات النموذج قبل الالتزام بتكامل API. اختر نموذجًا، وأرسل أمرًا نصيًا، وشاهد بدقة ما ستعمل معه في سلسلة أدوات MCP الخاصة بك. سواء كنت تولّد صورًا لمشروع، أو تختبر بنى الأوامر النصية، أو تستكشف كيف تتعامل النماذج المختلفة مع المدخل نفسه، فإن المنصة تمنحك وصولًا سريعًا دون عبء البنية التحتية.

أنشئ حسابًا، واختر نموذجًا، وابدأ بتوليد الصور أو النصوص اليوم، دون الحاجة إلى ملفات إعداد.