mcp-remote

اربط عميل MCP يدعم الخوادم المحلية (stdio) فقط بخادم MCP بعيد، مع دعم المصادقة:

ملاحظة: هذا نموذج إثبات مفهوم (proof-of-concept) عملي لكن يجب اعتباره تجريبيًا.

لماذا نحتاج إلى هذا؟

حتى الآن، يُثبَّت معظم خوادم MCP المنتشرة محليًا باستخدام ناقل stdio. وهذا يحقق بعض الفوائد: يمكن لكل من العميل والخادم أن يثقا ببعضهما ضمنيًا لأن المستخدم منحهما الإذن بالتشغيل. ويمكن إضافة الأسرار مثل مفاتيح API باستخدام متغيرات البيئة دون أن تغادر جهازك أبدًا. كما أن البناء على npx وuvx مكّن المستخدمين من تجنّب خطوات التثبيت الصريحة أيضًا.

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

مع أحدث مواصفات التفويض الخاصة بـ MCP، أصبح لدينا الآن طريقة آمنة لمشاركة خوادم MCP مع العالم دون تشغيل تعليمات برمجية على أجهزة المستخدمين المحمولة. أو على الأقل، سيكون ذلك ممكنًا لو كانت جميع عملاء MCP الشهيرة تدعمها بالفعل. معظمها يدعم stdio فقط، وتلك التي تدعم HTTP+SSE لا تدعم بعد تدفقات OAuth المطلوبة.

من هنا تأتي أهمية mcp-remote. بمجرد أن يدعم عميل MCP الذي اخترته الخوادم البعيدة المفوَّضة، يمكنك إزالته. وإلى ذلك الحين، أضف هذا الأمر المكوّن من سطر واحد واستعد لعملاء MCP الذين تريدهم!

الاستخدام

تستخدم جميع عملاء MCP الأكثر شيوعًا (Claude Desktop وCursor وWindsurf) تنسيق الإعدادات التالي:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}

الترويسات المخصصة

لتجاوز المصادقة، أو لإرسال ترويسات مخصصة مع جميع الطلبات إلى خادمك البعيد، مرّر وسائط --header عبر سطر الأوامر:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "..."
      }
    },
  }
}

ملاحظة: لدى Cursor وClaude Desktop (ويندوز) خطأ برمجي لا يتم فيه تخطي المسافات داخل args عند استدعاء npx، مما يؤدي إلى إفساد هذه القيم. يمكنك تجاوز ذلك باستخدام:

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // spaces OK in env vars
  }
},

الخيارات (Flags)

• إذا كان npx يُنتج أخطاءً، ففكّر في إضافة -y كوسيطة أولى لقبول تثبيت حزمة mcp-remote تلقائيًا.

      "command": "npx",
      "args": [
        "-y"
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]

• لإجبار npx على التحقق دائمًا من وجود نسخة محدّثة من mcp-remote، أضف خيار @latest:

      "args": [
        "mcp-remote@latest",
        "https://remote.mcp.server/sse"
      ]

• لتغيير المنفذ الذي يستمع عليه mcp-remote لإعادة توجيه OAuth (افتراضيًا 3334)، أضف وسيطة إضافية بعد عنوان الخادم. لاحظ أنه مهما كان المنفذ الذي تحدده، إذا كان غير متاح فسيتم اختيار منفذ مفتوح عشوائيًا.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "9696"
      ]

• لتغيير المضيف الذي يسجّله mcp-remote كعنوان URL لاستدعاء OAuth (افتراضيًا localhost)، أضف خيار --host.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--host",
        "127.0.0.1"
      ]

• للسماح باتصالات HTTP في الشبكات الخاصة الموثوقة، أضف خيار --allow-http. ملاحظة: يجب استخدامه فقط في الشبكات الخاصة الآمنة حيث لا يمكن اعتراض حركة المرور.

      "args": [
        "mcp-remote",
        "http://internal-service.vpc/sse",
        "--allow-http"
      ]

• لتفعيل سجلات تصحيح أخطاء مفصّلة، أضف خيار --debug. سيكتب هذا سجلات مطوّلة إلى ~/.mcp-auth/{server_hash}_debug.log مع طوابع زمنية ومعلومات مفصّلة عن عملية المصادقة والاتصالات وتحديث الرموز.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--debug"
      ]

• لتفعيل وكيل HTTP(S) صادر لـ mcp-remote، أضف خيار --enable-proxy. عند تفعيله، سيستخدم mcp-remote إعدادات الوكيل من متغيرات البيئة الشائعة (مثل HTTP_PROXY وHTTPS_PROXY وNO_PROXY).

    "args": [
      "mcp-remote",
      "https://remote.mcp.server/sse",
      "--enable-proxy"
    ],
    "env": {
      "HTTPS_PROXY": "http://127.0.0.1:3128",
      "NO_PROXY": "localhost,127.0.0.1"
    }

• لتجاهل أدوات محددة من الخادم البعيد، أضف خيار --ignore-tool. سيؤدي هذا إلى استبعاد الأدوات المطابقة للأنماط المحددة من استجابات tools/list وحظر طلبات tools/call. يدعم أنماط أحرف البدل باستخدام *.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--ignore-tool",
        "delete*",
        "--ignore-tool",
        "remove*"
      ]

يمكنك تحديد عدة خيارات --ignore-tool لتجاهل أنماط مختلفة. أمثلة:

• delete* - يتجاهل جميع الأدوات التي تبدأ بـ "delete" (مثل deleteTask وdeleteUser)
• *account - يتجاهل جميع الأدوات التي تنتهي بـ "account" (مثل getAccount وupdateAccount)
• exactTool - يتجاهل فقط الأداة المسماة حرفيًا "exactTool"

• لتغيير مهلة انتظار استدعاء OAuth (افتراضيًا 30 ثانية)، أضف خيار --auth-timeout بقيمة بالثواني. وهذا مفيد إذا كانت عملية المصادقة على جانب الخادم تستغرق وقتًا طويلاً.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--auth-timeout",
        "60"
      ]

استراتيجيات النقل

يدعم MCP Remote استراتيجيات نقل مختلفة عند الاتصال بخادم MCP. يتيح لك هذا التحكم في ما إذا كان يستخدم أحداث الخادم المرسلة (SSE) أو نقل HTTP، وبأي ترتيب يجربها.

حدد استراتيجية النقل باستخدام خيار --transport:

npx mcp-remote https://example.remote/server --transport sse-only

الاستراتيجيات المتاحة:

• http-first (الافتراضي): يجرب نقل HTTP أولاً، ويعود إلى SSE إذا فشل HTTP بخطأ 404
• sse-first: يجرب نقل SSE أولاً، ويعود إلى HTTP إذا فشل SSE بخطأ 405
• http-only: يستخدم نقل HTTP فقط، ويفشل إذا كان الخادم لا يدعمه
• sse-only: يستخدم نقل SSE فقط، ويفشل إذا كان الخادم لا يدعمه

بيانات تعريف عميل OAuth الثابتة

يدعم MCP Remote توفير بيانات تعريف ثابتة لعميل OAuth بدلاً من استخدام القيم الافتراضية لـ mcp-remote. وهذا مفيد عند الاتصال بخوادم OAuth التي تتوقع معرّفات أو نطاقات صلاحيات (scopes) محددة للعميل/البرنامج.

قدّم بيانات تعريف العميل كسلسلة JSON أو كمسار ملف مسبوق بـ @ مع خيار --static-oauth-client-metadata:

npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-metadata '@/Users/username/Library/Application Support/Claude/oauth_client_metadata.json'

معلومات عميل OAuth الثابتة

وفقًا للمواصفات، يُشجَّع الخوادم - دون إلزام - على دعم تسجيل العميل الديناميكي لـ OAuth.

بالنسبة لهذه الخوادم، يدعم MCP Remote توفير معلومات ثابتة لعميل OAuth بدلاً من ذلك. وهذا مفيد عند الاتصال بخوادم OAuth التي تتطلب عملاء مسجّلين مسبقًا.

قدّم معلومات العميل كسلسلة JSON أو كمسار ملف مسبوق بـ @ مع خيار --static-oauth-client-info: