قم بتأمين خادم MCP الخاص بك: قائمة مرجعية للمطورين مكونة من 8 نقاط

1. أضف المصادقة إلى نقطة نهاية MCP الخاصة بك

"إنه موجود على المضيف المحلي" ليس نموذجًا أمنيًا. ملحقات المتصفح والعمليات المحلية وأي تعليمات برمجية تعمل عليها يمكن أن تصل نفس الآلة localhost:3000. ينمو MCP البعيد بسرعة؛ كلود سطح المكتب، المؤشر، ويدعم كل من Windsurf الاتصال بخوادم MCP البعيدة عبر HTTPS.

تتطلب رمز حامل على كل طلب. خادم Botoi's MCP في api.botoi.com/mcp يقبل واجهة برمجة التطبيقات المفاتيح عبر Authorization header. بدون مفتاح صالح، تحصل على 5 طلبات في الدقيقة الواحدة و100 في اليوم؛ مع واحد، حدود النطاق لخطتك.

إذا قام وكلاؤك بتمرير JWTs بدلاً من المفاتيح الثابتة، فقم بفك تشفيرها لاستخراج النطاقات والهوية. وإليك كيف لفحص JWT من رأس طلب MCP:

curl -s -X POST https://api.botoi.com/v1/jwt/decode \\
  -H "Content-Type: application/json" \\
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ2VudC1jdXJzb3ItNDIiLCJzY29wZSI6InJlYWQ6ZG5zIHJlYWQ6c3NsIiwiaWF0IjoxNzE3MDAwMDAwfQ.signature"
  }'

{
  "success": true,
  "data": {
    "header": { "alg": "RS256", "typ": "JWT" },
    "payload": {
      "sub": "agent-cursor-42",
      "scope": "read:dns read:ssl",
      "iat": 1717000000
    },
    "signature": "signature"
  }
}

ال sub المطالبة تحدد الوكيل. ال scope يسرد المطالبة ما في وسعها من الأدوات الوصول. تحقق من جانب خادم التوقيع قبل الوثوق بهذه القيم.

2. أدوات النطاق لكل مفتاح API

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

// Scope tools per API key using an allowlist
interface AgentPermissions {
  allowedTools: Set<string>;
  maxBurst: number;
  dailyLimit: number;
}

const AGENT_PERMISSIONS: Record<string, AgentPermissions> = {
  "key_readonly_monitor": {
    allowedTools: new Set(["lookup_dns", "lookup_ssl", "lookup_ip"]),
    maxBurst: 10,
    dailyLimit: 500,
  },
  "key_full_access": {
    allowedTools: new Set(["*"]),  // wildcard for all tools
    maxBurst: 30,
    dailyLimit: 5000,
  },
};

function canUseTool(apiKey: string, toolName: string): boolean {
  const perms = AGENT_PERMISSIONS[apiKey];
  if (!perms) return false;
  if (perms.allowedTools.has("*")) return true;
  return perms.allowedTools.has(toolName);
}

3. التحقق من صحة مدخلات الأداة باستخدام مخططات Zod

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

يقوم خادم Botoi's MCP بتحويل تعريفات مسار OpenAPI إلى مخططات Zod عند بدء التشغيل باستخدام schema-builder.ts. ال buildZodSchema تقرأ الوظيفة مواصفات OpenAPI والخرائط كل نوع خاصية إلى نوع Zod، ويحدد الحقول المطلوبة:

import { z } from "zod";
import { buildZodSchema } from "./schema-builder";

// Build a Zod schema from your OpenAPI spec for each tool
const dnsSchema = z.object(buildZodSchema("/v1/dns/lookup", "post"));

function validateToolInput(toolName: string, input: unknown) {
  const schemas: Record<string, z.ZodTypeAny> = {
    lookup_dns: dnsSchema,
    // ... one schema per tool
  };

  const schema = schemas[toolName];
  if (!schema) {
    throw new Error(\`Unknown tool: \${toolName}\`);
  }

  const result = schema.safeParse(input);
  if (!result.success) {
    return {
      error: "Invalid input",
      issues: result.error.issues.map((i) => ({
        path: i.path.join("."),
        message: i.message,
      })),
    };
  }

  return { data: result.data };
}

إنشاء مخططات Zod من مدخلات العينة

إذا لم يكن لديك مواصفات OpenAPI، فقم بإنشاء مخططات Zod من أمثلة مدخلات الأداة:

curl -s -X POST https://api.botoi.com/v1/schema/json-to-zod \\
  -H "Content-Type: application/json" \\
  -d '{
    "json": {
      "domain": "github.com",
      "check_mx": true,
      "timeout_ms": 5000
    }
  }'

{
  "success": true,
  "data": {
    "schema": "z.object({ domain: z.string(), check_mx: z.boolean(), timeout_ms: z.number() })"
  }
}

التحقق من صحة المدخلات مقابل مخطط JSON في وقت التشغيل

للتحقق من صحة وقت التشغيل بدون Zod، استخدم مخطط JSON. أرسل المخطط ومدخلات الوكيل إلى /v1/schema/validate:

curl -s -X POST https://api.botoi.com/v1/schema/validate \\
  -H "Content-Type: application/json" \\
  -d '{
    "schema": {
      "type": "object",
      "required": ["domain"],
      "properties": {
        "domain": { "type": "string", "minLength": 1 },
        "record_type": { "type": "string", "enum": ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] }
      },
      "additionalProperties": false
    },
    "data": { "domain": "stripe.com", "record_type": "MX" }
  }'

إرجاع المدخلات الصالحة:

{
  "success": true,
  "data": {
    "valid": true,
    "errors": []
  }
}

إذا مر وكيل "record_type": "INVALID"، فستحصل على أخطاء قابلة للتنفيذ قبل تشغيل أداتك:

{
  "success": true,
  "data": {
    "valid": false,
    "errors": [
      {
        "path": "/record_type",
        "message": "must be equal to one of the allowed values"
      }
    ]
  }
}

4. قم بتعيين التعليقات التوضيحية للأداة

يحدد بروتوكول MCP أربعة تلميحات توضيحية: readOnlyHint, destructiveHint, idempotentHint، و openWorldHint. هذه تخبر الوكلاء ما إذا كانت الأداة تقرأ البيانات، يعدل الحالة، أو يكون آمنًا لإعادة المحاولة، أو يتصل بالخدمات الخارجية. تتجاهلها معظم خوادم MCP.

يشرح خادم MCP الخاص بـ Botoi جميع الأدوات الـ 49. إليك ما يبدو عليه الأمر عمليًا:

// curated-tools.ts (from Botoi's MCP server)
export const CURATED_TOOLS: Record<string, CuratedTool> = {
  lookup_dns: {
    path: "/v1/dns/lookup",
    method: "post",
    title: "DNS Lookup",
    description: "Query DNS records for a domain.",
    annotations: {
      readOnlyHint: true,   // reads data, changes nothing
      openWorldHint: true,  // contacts external DNS servers
    },
  },
  storage_paste_create: {
    path: "/v1/paste/create",
    method: "post",
    title: "Create Paste",
    description: "Store text content and return a short URL.",
    annotations: {
      destructiveHint: true,  // creates new data
      idempotentHint: false,  // each call creates a new paste
    },
  },
};

سيتجنب الوكلاء الذين يحترمون التعليقات التوضيحية استدعاء الأدوات المدمرة دون تأكيد ويفضلون ذلك أدوات غير فعالة عند إعادة محاولة الطلبات الفاشلة. ضعها على كل أداة.

5. حد السعر لكل هوية وكيل

من المفترض ألا يستنفد أحد العملاء المارقين العالقين في حلقة إعادة المحاولة حصة واجهة برمجة التطبيقات (API) الخاصة بك بالكامل. الحد من المعدل القياسي عن طريق عنوان IP لا يكفي؛ يمكن لوكلاء متعددين مشاركة نفس عنوان IP، ويمكن لوكيل واحد تدوير عناوين IP.

قم باستخراج هوية الوكيل من مفتاح API أو JWT، ثم قم بتطبيق حدود لكل هوية باستخدام نافذة منزلقة أو دلو الرمز المميز المخزن في KV:

// Hono middleware for per-agent rate limiting
import type { Context, Next } from "hono";

const BURST_LIMIT = 5;   // requests per minute
const DAILY_LIMIT = 100;  // requests per day

async function rateLimitAgent(c: Context, next: Next) {
  // Extract agent identity from API key or JWT
  const apiKey = c.req.header("Authorization")?.replace("Bearer ", "");
  const agentId = apiKey || c.req.header("X-Forwarded-For") || "anonymous";

  // Check burst limit (sliding window in KV)
  const burstKey = \`rate:\${agentId}:burst\

6. قم بتسجيل كل استدعاء للأداة بإسناد الوكيل

عندما يحدث خطأ ما في الإنتاج، عليك الإجابة على ثلاثة أسئلة: أي وكيل اتصل بأي الأداة ومتى وبأي مدخلات. بدون سجلات الاستدعاء، فأنت تقوم بالتصحيح الأعمى.

قم بتجزئة الإدخال بدلاً من تخزين الوسائط الأولية. يمنحك هذا ما يكفي للارتباط وإلغاء التكرار دون تسجيل البيانات الحساسة:

// Log every tool invocation with agent identity
interface ToolInvocationLog {
  timestamp: string;
  agent_id: string;
  tool_name: string;
  input_hash: string;   // SHA-256 of the input (not the raw input)
  duration_ms: number;
  status: "success" | "error";
}

async function logToolInvocation(
  agentId: string,
  toolName: string,
  input: unknown,
  startTime: number,
  status: "success" | "error"
) {
  const inputStr = JSON.stringify(input);
  const inputHash = await crypto.subtle.digest(
    "SHA-256",
    new TextEncoder().encode(inputStr)
  );
  const hashHex = Array.from(new Uint8Array(inputHash))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");

  const log: ToolInvocationLog = {
    timestamp: new Date().toISOString(),
    agent_id: agentId,
    tool_name: toolName,
    input_hash: hashHex,
    duration_ms: Date.now() - startTime,
    status,
  };

  // Send to your logging pipeline (Datadog, Loki, Cloudflare Logpush)
  console.log(JSON.stringify(log));
}

أرسل هذه السجلات المنظمة إلى خط الأنابيب الحالي لديك (Datadog، Grafana Loki، Cloudflare Logpush). أنشئ تنبيهات للأنماط غير المعتادة: يقوم وكيل واحد بإجراء 10 أضعاف حجم المكالمات العادية، أو للقراءة فقط وكيل يحاول استدعاء الأدوات المدمرة.

7. تثبيت تعريفات الأداة والتحقق من سلامتها

وجد تقرير باراكودا أن المهاجمين يقومون بإدخال تعريفات الأدوات الضارة في أطر عمل الوكيل من خلال التبعيات للخطر. إذا قام شخص ما بتعديل بيان أداة MCP الخاص بك (الأسماء أو الأوصاف أو المعلمات المخططات)، سيقوم الوكلاء باستدعاء الأدوات ذات السلوك المختلف عما كنت تقصده.

قم بتجزئة بيان أداتك في وقت الإنشاء. عند بدء التشغيل، أعد حساب التجزئة وقارن:

import crypto from "node:crypto";
import Botoi from "@botoi/sdk";

const botoi = new Botoi();

// Your tool manifest (the source of truth)
const tools = [
  { name: "dns_lookup", path: "/v1/dns/lookup" },
  { name: "ip_lookup", path: "/v1/ip/lookup" },
  { name: "email_validate", path: "/v1/email/validate" },
  // ... all your tools
];

const manifest = JSON.stringify(tools);

// Hash it at build time and store the expected hash
const EXPECTED_HASH = "a3f2b8c1d4e5f6..."; // from your CI build

// At startup, verify integrity
function verifyManifestIntegrity() {
  const currentHash = crypto
    .createHash("sha256")
    .update(manifest)
    .digest("hex");

  if (currentHash !== EXPECTED_HASH) {
    throw new Error(
      \`Tool manifest tampered. Expected \${EXPECTED_HASH}, got \${currentHash}\`
    );
  }

  console.log("Tool manifest integrity verified.");
}

// Or use the Botoi API for environments without Node crypto
async function verifyWithApi() {
  const result = await botoi.hash.sha256({ input: manifest });
  if (result.data.hash !== EXPECTED_HASH) {
    throw new Error("Tool manifest tampered.");
  }
}

قم بإنشاء التجزئة باستخدام Botoi API

لبيئات CI أو أوقات تشغيل الحافة بدون node:crypto:

curl -s -X POST https://api.botoi.com/v1/hash \\
  -H "Content-Type: application/json" \\
  -d '{
    "text": "[{\\"name\\":\\"dns_lookup\\",\\"path\\":\\"/v1/dns/lookup\\"},{\\"name\\":\\"ip_lookup\\",\\"path\\":\\"/v1/ip/lookup\\"}]",
    "algorithm": "sha256"
  }'

{
  "success": true,
  "data": {
    "hash": "a3f2b8c1d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678",
    "algorithm": "sha256"
  }
}

قم بتخزين التجزئة المتوقعة كمتغير بيئة. قارنه في وقت النشر. إذا تباعدت التجزئة ، منع النشر.

8. العمليات التدميرية في وضع الحماية

تحتاج الأدوات التي تكتب البيانات أو تؤدي إلى آثار جانبية أو تتصل بالخدمات الخارجية إلى تدفق تأكيد. لا تسمح للوكيل بإنشاء 1000 عملية لصق أو إطلاق خطافات الويب دون مراجعة بشرية.

// Confirmation flow for destructive MCP tools
interface ToolResult {
  content: Array<{ type: string; text: string }>;
  isError?: boolean;
}

function handleDestructiveTool(
  toolName: string,
  input: Record<string, unknown>,
  confirmed: boolean
): ToolResult {
  const destructiveTools = new Set([
    "paste_create",
    "short_url_create",
    "webhook_inbox_create",
  ]);

  if (!destructiveTools.has(toolName)) {
    // Non-destructive: execute immediately
    return executeTool(toolName, input);
  }

  if (!confirmed) {
    // Return a preview instead of executing
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          action: "confirmation_required",
          tool: toolName,
          input,
          message: \`This tool will create new data. Pass "confirmed": true to proceed.\`,
        }),
      }],
    };
  }

  // Confirmed: execute the destructive operation
  return executeTool(toolName, input);
}

النمط واضح ومباشر: تقوم الأدوات التدميرية بإرجاع معاينة عند الاتصال الأول. يظهر الوكيل المعاينة للمستخدم. فقط بعد تأكيد المستخدم، يرسل الوكيل مكالمة ثانية معه "confirmed": true.

بالنسبة للأدوات التي تتصل بالخدمات الخارجية (openWorldHint: true)، فكر في الإضافة مهلة وقاطع الدائرة. إذا كانت واجهة برمجة التطبيقات الخارجية بطيئة أو معطلة، فلا ينبغي أن يكون خادم MCP الخاص بك كذلك شنق إلى الأبد في انتظار الرد.

كيف يطبق خادم MCP الخاص بـ Botoi هذه الفحوصات

خادم Botoi's MCP في api.botoi.com/mcp بمثابة مرجع عمل لهذا قائمة مرجعية. فيما يلي كيفية تعيين كل عنصر:

يمكنك الاتصال بخادم Botoi's MCP من Claude Desktop أو Claude Code أو Cursor أو VS Code أو Windsurf. ال صفحة إعداد MCP لديه التكوين لكل عميل.

قائمة التحقق من أمان خادم MCP الخاصة بك

وهنا القائمة المرجعية الكاملة، مكثفة. قم بطباعته أو تثبيته أو لصقه في دليل التشغيل الخاص بفريقك:

• يتطلب المصادقة على كل نقطة نهاية MCP (رمز Bearer، مفتاح API، أو JWT)
• قم بتعيين كل مفتاح واجهة برمجة التطبيقات (API) إلى القائمة المسموح بها من الأدوات المسموح بها
• تحقق من صحة كل إدخال للأداة باستخدام مخططات Zod أو مخطط JSON قبل التنفيذ
• قم بتعليق كل أداة باستخدام readOnlyHint, destructiveHint, idempotentHint، و openWorldHint
• حد السعر لكل هوية وكيل، وليس لكل IP؛ استخدم كلاً من القبعات الانفجارية واليومية
• قم بتسجيل كل استدعاء للأداة باستخدام معرف الوكيل واسم الأداة وتجزئة الإدخال والمدة والحالة
• قم بتجزئة بيان أداتك في وقت الإنشاء؛ التحقق عند بدء التشغيل وحظر عمليات النشر التي تم العبث بها
• معاينات العودة من الأدوات المدمرة؛ تتطلب تأكيدًا صريحًا قبل التنفيذ

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