MCP құралының схемасы жабық болуы керек

MCP құралының схемасы ішкі API қабылдай алатын нәрсенің бәрін емес, модельге дәл қазір жасауға рұқсат етілген бір қауіпсіз сұрауды сипаттауы керек. Егер құрал еркін объектіні, ұзын мәтінді және бірнеше жасырын режимді қабылдаса, модель ерте ме, кеш пе артық дерек жібереді. Кейде бұл жай ғана шу болады. Кейде модель басқа біреудің идентификаторын, ішкі сүзгіні, құжаттағы нұсқауды немесе әзірлеуші «болашаққа» қалдырған параметрді береді.

Мәселе модельдің нұсқауды нашар орындауында емес. MCP құралы аргументтерді машиналық интерфейс арқылы алады, ал машиналық интерфейс кіріс деректерін өзі шектеуі керек. Промпт «қызметтік өрістерді жібермеуді» сұрауы мүмкін, бірақ олар пайда болса, сервер оларды қабылдамауы тиіс. Әйтпесе модельге ойлағаныңыздан кеңірек өкілеттік беріп қоясыз.

Model Context Protocol спецификациясы inputSchema параметрін құрал параметрлеріне арналған JSON Schema ретінде анықтайды. MCP-тің қазіргі құжаттамасында $schema ашық көрсетілмеген схемалар үшін JSON Schema 2020-12 диалектісі қолданылады. Ал параметрлері жоқ құрал үшін additionalProperties: false бар объектіні тікелей ұсынады. Бұл дұрыс бастама, бірақ ол сервердегі тексеруді алмастырмайды және кең операцияны өздігінен қауіпсіз етпейді.

Кең объект модельге артық жолдар береді

Кең схема қауіпті, өйткені әр міндетті емес параметр модель контекстен таңдай алатын тағы бір әрекет нұсқасына айналады. object типі бар, бірақ ішкі схемасы жоқ options, filters, metadata, query, payload және params өрістері әсіресе қауіпті. Олар көбіне қолданыстағы API-ға ыңғайлы көпір ретінде пайда болады. Іс жүзінде бұл көпір API-дың барлық ескі мүмкіндігін сыртқа шығарады, соның ішінде агентке бергіңіз келмеген мүмкіндіктерді де.

Қайтарымды дайындайтын құралды елестетіп көріңіз:

{
  "name": "create_refund",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string" },
      "options": { "type": "object" }
    },
    "required": ["order_id"]
  }
}

Бір қарағанда модель тапсырыс нөмірін ғана жіберуі керек сияқты. Бірақ options мына сұрақты ашық қалдырады: төменгі деңгейдегі сервис нақты қандай өрістерді қабылдайды? refund_to_original_method, reason_code, amount, currency, override_limit, notify_customer, actor_id? Олардың бір бөлігін сервер қазір елемегенімен, кездейсоқ әрекетке тәуелділік пайда болады. Ішкі API келесі жаңартудан кейін «зиянсыз» өріс іске қосылып кетуі мүмкін.

Ашық объект модельге де нақты бағыт бермейді. Оның шекарасы жоқ болғандықтан, модель пайдалы параметрлерді құрал сипаттамасынан, құжаттамадан, хат мәтінінен немесе басқа функция нәтижесінен болжауға тырысады. Болжамға рұқсат көбейген сайын журналда талдауға тиіс шақырулар да көбейеді.

Бөлек құралға қысқа міндет берген дұрыс. Мысалы, create_refund_draft тапсырыстың толық сомасына ғана нобай жасап, соманы, қайтару тәсілін немесе еркін метадеректерді қабылдамауы мүмкін. Егер бизнеске ішінара қайтару қажет болса, бөлек тексеруі мен растауы бар басқа маршрут жасаңыз. Бұл артық бюрократия емес. Бұл көруге, тестілеуге және аудиторға түсіндіруге болатын өкілеттік шекарасы.

Жабық схема белгісіз өрістерді қабылдамауы керек

additionalProperties: false properties ішінде көрсетілмеген және patternProperties арқылы рұқсат етілмеген қасиеттерге тыйым салады. Жазық объект үшін бұл модельдің «керек болып қалар» деп бөгде параметрді өткізуіне жол бермеудің ең тікелей тәсілі.

Төменде клиентті бір ғана идентификатор арқылы іздейтін құрал схемасы берілген. Ол әдейі күндер аралығын, SQL тәрізді сүзгіні, жеке деректерді қосу жалаушасын және еркін өрістер жиынын қабылдамайды.

{
  "name": "get_customer_summary",
  "description": "Возвращает краткую сводку по клиенту, доступному текущему пользователю.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "customer_id": {
        "type": "string",
        "minLength": 1,
        "maxLength": 36,
        "pattern": "^[A-Za-z0-9_-]+$",
        "description": "Идентификатор клиента из текущего рабочего контекста."
      }
    },
    "required": ["customer_id"]
  }
}

Бұл схема мына шақыруды орындалмай тұрып қабылдамайды:

{
  "customer_id": "cust_7D2k",
  "include_pii": true
}

Ол customerId деген қате жазылған атауды да қабылдамайды. Бұл тым қатаң көрінуі мүмкін, бірақ мағынасы дұрысқа жақын өрісті үнсіз қабылдау одан да қауіпті: модель операция бір мағынада орындалды деп ойлайды, ал сервер басқа әрекет жасайды. Ескі атаумен үйлесімділік керек болса, оны бөлек адаптерде қалыпқа келтіріп, жария схемада екі атауды да ашық қалдырмаңыз.

Жабу әр ішкі объект үшін де қайталануы керек. Мынау жиі кездесетін қате:

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "recipient": {
      "type": "object",
      "properties": {
        "email": { "type": "string" }
      },
      "required": ["email"]
    }
  },
  "required": ["recipient"]
}

Түбір объект жабық, бірақ recipient ашық күйінде қалды. Оған role, api_key, send_copy_to, is_admin және қолданбалы код оқитын кез келген басқа өріс өте алады. Түзету оңай: additionalProperties: false параметрін дәл recipient ішіне қосыңыз.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "recipient": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "email": {
          "type": "string",
          "minLength": 3,
          "maxLength": 254
        }
      },
      "required": ["email"]
    }
  },
  "required": ["recipient"]
}

additionalProperties пен unevaluatedProperties әртүрлі міндет атқарады

Әзірлеушілер бұл екі кілтсөзді жиі бір-бірінің орнына қолдануға болады деп ойлайды. Қарапайым схемада олар ұқсас. Айырмашылық объектіні allOf, oneOf, if немесе $ref арқылы құрастырғанда көрінеді.

additionalProperties схема орналасқан жердегі properties және patternProperties параметрлеріне қарайды. Сондықтан additionalProperties: false бар базалық объект allOf арқылы басқа ішкі шарт қосқан өрісті қабылдамай қоюы мүмкін. Әзірлеуші бұған жауап ретінде қасиеттерді сыртқы схемада қайталайды. Бірнеше осындай түзетуден кейін схема нақты келісімшарттан алшақтай бастайды.

unevaluatedProperties: false басқаша жұмыс істейді. Ол нәтиже есептелген кезде сәйкес ішкі схемалар өңдемеген қасиеттерге тыйым салады. JSON Schema құжаттамасы бұл жағдайды композициясы бар кеңейтілетін схемаларға арналған шешім ретінде арнайы көрсетеді.

Мысалы, өтінемені адресаттаудың екі тәсіліне рұқсат бергіңіз келеді: қысқа ticket_id арқылы немесе project пен number жұбы арқылы.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "oneOf": [
    {
      "properties": {
        "ticket_id": {
          "type": "string",
          "pattern": "^TKT-[0-9]{1,8}$"
        }
      },
      "required": ["ticket_id"]
    },
    {
      "properties": {
        "project": {
          "type": "string",
          "enum": ["billing", "support", "security"]
        },
        "number": {
          "type": "integer",
          "minimum": 1,
          "maximum": 99999999
        }
      },
      "required": ["project", "number"]
    }
  ],
  "unevaluatedProperties": false
}

Мұнда oneOf жай безендіру емес, маңызды ереже. Ол модель ticket_id, сондай-ақ project пен number параметрлерін бірге жіберетін екіұшты сұрауға тыйым салады. Бұл жеке қауіпсіздік қағидасы: сервер объектіні таңдаудың екі тәсілін алса, қайсысы басым екенін өзі болжамауы керек.

Бірақ алдымен өз стекіңізді тексеріңіз. MCP 2025-11-25 құжаты және одан кейінгі нобайлар JSON Schema 2020-12 нұсқасын, соның ішінде күрделірек композицияларды сипаттайды. Ескі SDK, прокси және валидаторлар көбіне тек type, properties және required параметрлерін өңдейді. Клиент unevaluatedProperties параметрін түсінбесе, модельге әдемі схеманы көрсетуі мүмкін, бірақ сіз күткен тыйымды қолданбауы ықтимал. Репозиторийдегі схема нақты сұрауды тексеретін схемаға тең емес.

Жол шектеулері көлем мен екіұштылықты азайтады

Шектеусіз string типі «кез келген ұзындықтағы кез келген мәтінді қабылдаймын» дегенді білдіреді. Мекенжай, идентификатор, хат тақырыбы және пікір үшін бұл төрт түрлі келісімшарт. Оларды бір типпен сипаттамаңыз.

Ұзындық лимиті тек тым үлкен сұраудан қорғамайды. Ол өрістің не үшін бар екенін нақтылауға мәжбүр етеді. Мән 64 таңбаға сыймаса, ол идентификатор емес шығар. Нобай жасау үшін ондаған мың таңбалық мәтін керек болса, модельдің бәрін құрал аргументіне жинамай, алдын ала сақталған құжатқа сілтеме беруі немесе пайдаланушыдан растау сұрауы керек болуы мүмкін.

Басқарылатын мәндер үшін еркін мәтіннің орнына enum қолданыңыз. Мысалы, жеткізу режимі сипаттамасы бар жол болмауы керек:

{
  "delivery_mode": {
    "type": "string",
    "enum": ["email", "sms", "none"]
  }
}

Бұл pattern: ".*" және «рұқсат етілген нұсқалар: email, sms, none» деген сипаттамадан жақсы. Сипаттама модельге мән таңдауға көмектеседі, ал enum серверді email_and_sms, urgent_sms және сыртқы беттен алынған мәтінді қабылдамауға мәжбүр етеді.

Кодтар мен идентификаторлар үшін ұзындықты нақты үлгімен бірге қолданыңыз. maxLength жалғыз өзі бос орындарға, басқару таңбаларына және сөйлемдерге рұқсат береді. pattern жалғыз өзі регулярлық өрнекке сай келетін өте ұзын жолды өткізуі мүмкін. Бұл шектеулер бірін-бірі толықтырады.

Регулярлық өрнекті бизнес-логикаға айналдырмаңыз. Схема келісімшарт нөмірінің пішінін тексере алады, бірақ келісімшарттың бар екенін, ағымдағы ұйымға тиесілі екенін және шақырушыға қолжетімді екенін анықтай алмайды. Регулярлық өрнек осы тексерулердің орнын басуға тырысқанда, оны оқу қиын әрі қауіпсіз өзгерту дерлік мүмкін болмайды.

Кейде еркін мәтін қажет. Онда шекараны нақты қойыңыз: minLength, maxLength, түсінікті мақсат және серверлік тазалау. Мұндай мәтінді SQL-ге, shell командасына, URL-ге, сұрау үлгісіне немесе жүйелік промптқа ешқашан тікелей қоспаңыз. Жарамды жолдың өзі келесі компонент үшін қауіпті мазмұн болуы мүмкін.

Схема пішінді, сервер рұқсат пен мағынаны тексереді

Серверлік валидация міндетті, өйткені MCP схемасы әрекет орындалатын нүкте емес. Клиент диалектінің бір бөлігін қолдамауы, интеграция қатесіне байланысты тексеруді өткізіп жіберуі немесе шақыруды тікелей жіберуі мүмкін. Мінсіз схема да объектінің кімге тиесілі екенін және ағымдағы күйде операцияға рұқсат бар-жоғын білмейді.

Серверде бір-бірінен бөлек үш тексеру болуы керек:

1. Ол tools/list ішінде жариялаған схеманың дәл өзі бойынша бүкіл кіріс объектісін тексереді.
2. Қолжетімділік субъектісін модель аргументтеріндегі user_id, tenant_id немесе actor мәнінен емес, тексерілген серверлік аутентификациядан анықтайды.
3. Әрекет алдында бизнес шарттарын тексереді: жазба күйін, лимитті, идемпотенттілікті, пайдаланушы келісімін және күйдің рұқсат етілген ауысуын.

Бұл деңгейлерді бөлу маңызды. Экспорт сұрауын елестетіңіз:

{
  "report_id": "rpt_4821",
  "format": "csv"
}

Схема report_id пішінінің дұрыс екенін, ал format мәнінің тізімге кіретінін растайды. Авторизация бұл пайдаланушының rpt_4821 есебін көруге құқығы бар-жоғын анықтайды. Бизнес тексеруі есептің аяқталғанын, қолжетімділік мерзімінің өтпегенін және экспортқа бөлек келісім қажет емес екенін тексереді. Осы деңгейлерді шартты операторлары бар бір өңдеушіге араластырсаңыз, команда келісімшартты емес, ерекше жағдайларды түзете бастайды.

Іс жүзінде серверлік өңдеуші қызықсыз көрінуі керек. Бұл жақсы белгі.

const parsed = ExportReportInput.safeParse(request.arguments);
if (!parsed.success) {
  return {
    isError: true,
    content: [{ type: "text", text: "Некорректные аргументы инструмента." }]
  };
}

const principal = await requireAuthenticatedPrincipal(request);
const report = await reports.findVisibleTo(principal.orgId, parsed.data.report_id);

if (!report) {
  return {
    isError: true,
    content: [{ type: "text", text: "Отчёт недоступен." }]
  };
}

if (report.status !== "ready") {
  return {
    isError: true,
    content: [{ type: "text", text: "Отчёт ещё нельзя экспортировать." }]
  };
}

return exportReport(report, parsed.data.format);

Мұнда не жоқ екеніне назар аударыңыз: модельдің мәлімдемесіне сенім, ұйым идентификаторын аргументтен алу және дерекқор қатесінің мәтінін жауапқа шығару. Сыртқы жауап сұрауды басқа дұрыс деректермен қайталауға болатынын түсіндіруі керек. Ішкі журнал техникалық себепті және командаға арналған корреляция идентификаторын сақтауы тиіс.

OWASP агенттік қосымшалар мен LLM тексеру материалдарында JSON-ның күтілетін құрылымын тексеруді және артық қасиеттерді қабылдамауды бөлек талап етеді. Бұл аудит үшін жасалатын формалдылық емес. Күтпеген өріс қолданбалы логиканы айналып өтуге немесе сенімсіз мәтінді артық өкілетті әрекетке жеткізетін арнаға айналуы мүмкін.

Құрал сипаттамасы тыйым салу механизмі емес

Жақсы сипаттама қажет, бірақ ол шақыруды басқармайды. Сипаттама модельдің құралды таңдауына және аргументтерді құрастыруына әсер етеді. «Жеке деректерді жіберме» деген сөздер схема кез келген жолға мегабайттық көлемге дейін рұқсат берсе, note өрісін тоқтатпайды. «Тек ағымдағы клиентті қолдан» деген сөздер сервер customer_id мәнін қолжетімділік аймағымен салыстырмаса, оны шектемейді.

Сипаттаманы саясатпен араластыру өте жағымсыз қате тудырады. Команда құрал мәтініне қарап, шектеулердің қолданылып тұрғанына сенеді. Кейін басқа клиент, жаңа модель немесе сыртқы нұсқау қажетсіз өрісі бар жарамды JSON құрады. Сервер код арқылы рұқсат етілген нәрсені адал орындайды.

Сипаттаманы мағынаға, схеманы пішінге пайдаланыңыз. Қолжетімділік саясатын серверлік кодта ұстаңыз. Мысалы:

• сипаттама: «Таңдалған алушыға арналған хабарлама нобайын жасайды»;
• схема: алушы қысқа идентификатормен беріледі, тақырып 120 таңбамен шектеледі, белгісіз өрістерге тыйым салынады;
• сервер: алушы ағымдағы пайдаланушыға қолжетімді, үлгіге рұқсат бар, жіберу басталмайды.

Мұндай бөлу кодты қайта қарауды да жеңілдетеді. Қауіпсіздік инженері нақты шектелген келісімшартты, ал процесс иесі одан кейін шын мәнінде қандай әрекеттер орындалатынын тексереді.

Әмбебап action шекараны көбіне бұлдыратады

Танымал ұсыныс мынадай: manage_customer атты бір құрал жасап, оған action өрісін қосып, параметрлерді data ішіне салу. Әзірлеушілерге бұл тәсіл ұнайды, өйткені декларациялар саны азаяды. Модельге де кейде ұнайды, себебі ол бір таныс кіріс нүктесін көреді. Бірақ қауіпсіздік пен қолдау тұрғысынан бұл тәсіл ұтыс бермейді.

Мына пішінді жарияламаған дұрыс:

{
  "type": "object",
  "properties": {
    "action": { "type": "string" },
    "data": { "type": "object" }
  },
  "required": ["action", "data"]
}

Схема update_email үшін қандай деректер, merge_accounts үшін қандай деректер қажет екенін, delete_customer операциясына қандай талап қойылатынын және қай әрекеттерге келісімсіз рұқсат берілетінін айтпайды. Өңдеушіде тез арада тармақтар пайда болады, әр тармақта тексерулер жиыны сәл өзгеше болады. Бірнеше айдан соң ешкім data барлық жерде жабық па және ұйым бірдей тексеріле ме, нақты білмейді.

Егер операциялардың әсері шынымен әртүрлі болса, бөлек құралдар жасаңыз. get_customer_summary мекенжайды өзгерте алмауы керек. create_email_change_draft хат жібермеуі тиіс. confirm_email_change жаңа мекенжайды екінші рет қабылдамай, сервер идентификаторы арқылы бұрын жасалған нобайды растауы керек.

Кейде бірыңғай құрал қажет, мысалы бірнеше бірін-бірі жоққа шығаратын кілті бар іздеу үшін. Онда режимдерді oneOf арқылы рәсімдеп, әр тармақты шектеп, олардың өзара ерекшеленетінін қамтамасыз етіңіз және құқықтарды серверде бәрібір сақтаңыз. action өрісіне өздігінен тыйым салынбайды. Бірақ оның жанындағы ашық data көбіне шекараның жобаланбағанын көрсетеді.

Теріс тесттер тыйымның жұмыс істейтінін көрсетеді

Схема қабылдамау тесттері болмайынша дайын деп саналмауы керек. Оң мысал күтілетін сұраудың өтетінін дәлелдейді. Бірақ артық параметр, қате тип немесе үлкен жол орындаушыға жетпейтіні туралы ештеңе айтпайды.

Әр құрал үшін теріс жағдайлардың шағын жиынын жасаңыз. Бес өріс үшін генератор құрудың қажеті жоқ, бірақ тек сәтті жол тестімен шектелуге болмайды.

[
  {
    "name": "лишнее поле",
    "arguments": {
      "customer_id": "cust_7D2k",
      "include_pii": true
    },
    "valid": false
  },
  {
    "name": "слишком длинный идентификатор",
    "arguments": {
      "customer_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    },
    "valid": false
  },
  {
    "name": "объект вместо строки",
    "arguments": {
      "customer_id": { "value": "cust_7D2k" }
    },
    "valid": false
  },
  {
    "name": "допустимый запрос",
    "arguments": {
      "customer_id": "cust_7D2k"
    },
    "valid": true
  }
]

Бұл мысалдарды SDK жасайтын схемамен ғана емес, серверде қолданылатын валидатормен іске қосыңыз. Содан кейін интеграциялық тест қосыңыз: кіріс жарамсыз болғанда сыртқы әрекеттің mock нұсқасы шақырылмауы керек. Бұл код алдымен өңделмеген өрісті оқып, тек кейін жиналған құрылымды тексеретін жиі қатені ұстайды.

Нұсқалар үйлеспеушілігін де тексеріңіз. oneOf, шартты схемалар немесе unevaluatedProperties қолдансаңыз, нақты хабарландыруларды трафик өтетін клиенттер мен шлюздерге жіберіп көріңіз. MCP спецификациясы дамып келеді, ал қауіпсіздік нақты валидаторға, оның нұсқасына және қосылған орнына тәуелді.

Модельдерді OpenAI-мен үйлесімді бірыңғай шлюз арқылы шақыратын командалар үшін бұл тексеруді сұрау роутеріне сіңірмеудің тағы бір себебі. AI Router модельдерге ортақ жол мен кілт деңгейіндегі бақылауды бере алады, бірақ MCP құралының келісімшарты мен әрекетті орындау туралы шешім құрал серверіне жақын қалуы керек. Нақты объект, пайдаланушы, ұйым және шақыру салдары дәл сол жерде белгілі.

Алдымен келісімшартты кішірейтіңіз, кейін қолайлылық қосыңыз

Құралды жобалауды мына сұрақтан бастаңыз: бір пайдалы әрекетті орындауға мүмкіндік беретін ең аз деректер жиыны қандай? Содан кейін ғана нақты сценарий, тест және авторизация ережесі бар болса, өріс қосыңыз. Ішкі API-да бар болғаны үшін metadata, «болашаққа арналған баптаулар» және міндетті емес жалаушаларды қоспаңыз.

Егер өріс тек серверге қажет болса, оны модельге көрсетпеңіз. Ұйым идентификаторын сессиядан алыңыз. Аймақты, тарифті, қызметтік лимиттерді және эксперимент жалаушаларын сервер жағы анықтасын. Модель мән таңдауы керек болса, еркін объектінің орнына қысқа enum немесе қауіпсіз жеке идентификатор ұсыныңыз.

Қатаң схема агенттік жүйені қателеспейтін етпейді. Бірақ қатені кішірейтеді: модель келісімшартты білдіртпей кеңейте алмайды, ал серверде бас тартуға бір түсінікті себеп болады. Ақшаға, жеке деректерге, қолжетімділікке немесе сыртқы хабарламаларға әсер ететін құралдар үшін бұл ұсақ баптау емес. Бұл қалыпты инженерлік тәртіп.