MCP құралдарына OAuth scopes қалай тағайындалады?

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

Жақсы scopes схемасы құралдар тізімін қайталамайды. Ол бизнес объектілерімен орындалатын рұқсат етілген операцияларды сипаттайды, қайтарылатын әрекеттерді қайтарылмайтын әрекеттерден бөледі және серверге сұрау контекстін тексеру құқығын қалдырады. Бұл OAuth атауларын ойлап табу емес, қолжетімділікті жобалау жұмысы.

Scope серверді емес, әрекетті сипаттауы керек

mcp:access сияқты жалпы scope көбіне команда құқықтар мәселесін кейінге қалдырғанын білдіреді. Ол кейін әдетте жою, экспорттау немесе бекіту құралы алғаш қосылған кезде келеді. Сол уақытта ескі токендер беріліп қойған, оларға бірнеше клиент тәуелді болады.

Алдымен мына сұрақтан бастаңыз: модель бұл құралды қосымша растаусыз таңдаса, шақырушы тарап нақты не істей алады? «Біздің MCP серверімізді шақыра алады» деген жауап қауіп туралы ештеңе айтпайды. «Қалдықтарды көре алады», «өтінім жасай алады», «тарифті жариялай алады» және «маршрутизация ережелерін өзгерте алады» деген жауаптар жеткілікті ақпарат береді.

Scope атауының практикалық үлгісі әдетте домен мен етістіктен тұрады:

inventory:read
inventory:write
orders:read
orders:write
orders:approve
billing:export
admin:manage

Бұл әмбебап сөздік емес. Бір команда үшін orders:approve лимитті келісуді білдірсе, басқа команда үшін қайтарымды рәсімдеуді білдіруі мүмкін. Ең маңыздысы, мағынасы тұрақты болсын: адам, policy engine және құрал авторы осы жол қандай әрекетке рұқсат беретінін бірдей түсінуі керек.

Әр техникалық әдіске олардың саны көп болғаны үшін ғана жеке scope қоспаңыз. Мысалы, inventory.get_item, inventory.search_items және inventory.list_low_stock үшеуі де бірдей сезімталдық деңгейіндегі деректерді ғана қайтарса, inventory:read scope-ын талап ете алады. Ал inventory.export_all үшін бөлек inventory:export қажет, өйткені оның нәтижесі файлға, поштаға немесе сыртқы агентке оңай түседі.

Кері қате де болады: етістіктерді тым кең алу. orders:write төленген тапсырысты болдырмауды, ақшаны қайтаруды немесе бағаларды жаппай өзгертуді автоматты түрде қамтымауы керек. Егер әрекет клиент алдындағы міндеттемені өзгертсе, ақшаға әсер етсе немесе оны қайтару қиын болса, оны кәдімгі өңдеуден бөлек ұстаңыз.

Құрал, операция және ресурс бір нәрсе емес

Командалар қолжетімділікті бақылаудың бүкіл мәселесін бір scopes тізімімен шешуге тырысады. Бұл мүмкін емес, себебі scope бір ғана сұраққа жауап береді: токенге қандай әрекеттер класына негізінен рұқсат берілген?

Әр MCP құралы шақыруында кемінде төрт түрлі өлшем бар:

1. Құрал кіру нүктесін анықтайды, мысалы create_refund.
2. Операция әрекеттің мағынасын сипаттайды: оқу, жасау, өзгерту, бекіту, экспорттау, әкімшілендіру.
3. Ресурс әрекет неге қатысты орындалатынын көрсетеді: тапсырыс, шарт, нақты клиент, жоба немесе филиал.
4. Субъект пен контекст әрекетті кім шақыратынын, қай ұйымнан және қай ортада шақырылатынын, қандай қосымша шарттар барын анықтайды.

Scope әдетте операция мен доменді қамтиды. Ресурстар мен ұйым шекараларын тексеру бөлек болуы керек. orders:read токені бар банк қызметкері екі банк те бір MCP серверін қолданғаны үшін басқа банктің тапсырыстарын оқи алмауы тиіс.

Мынау жиі кездесетін қате:

orders:read:tenant-482
orders:read:tenant-721
orders:read:tenant-913

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

Токенде кәдімгі orders:read мәнін сақтап, нақты ұйымға құқықты тексерілетін claims, серверлік policy немесе құрылымдалған рұқсат арқылы алған дұрыс. RFC 9396, OAuth 2.0 Rich Authorization Requests, осы мақсатта authorization_details параметрін енгізеді: клиент қажетті қолжетімділіктің машина оқитын сипаттамасын береді, ал authorization server дәлірек рұқсат бере алады. Бұл қолжетімділік шотқа, құжаттар жиынына, сомаға немесе кезеңге тәуелді болғанда пайдалы.

Scope пен ресурс шектеуі бірге жұмыс істеуі керек. Біріншісі қауіпті операциялар класын шақыруға жол бермейді. Екіншісі рұқсат етілген операцияны бөтен немесе сәйкес емес объектіге қолдануға жол бермейді.

Оқу, өзгерту және әкімшілендіру үшін әртүрлі шекара қажет

MCP сервері үшін алдымен құралдар тізімін емес, салдарлар матрицасын жасаған пайдалы. Ол «write» ішінде тым әртүрлі әрекеттер жасырынған жерлерді тез көрсетеді.

Оқу әрқашан қауіпсіз бола бермейді. Клиенттер бойынша іздеу жеке деректерді қайтаруы мүмкін, ал он мың жолды экспорттау бір реттік өзгерістен қауіпті болуы ықтимал. Сондықтан read «келісімсіз және аудитсіз» дегенді білдірмейді. Ол операция бастапқы деректерді өзгертпейтінін ғана білдіреді. Зиянды бағалау үшін бұл жеткіліксіз.

Әкімшілік әрекеттерді шағын өнімнің өзінде бөлек ұстаңыз. Пайдаланушы қосу, сақтау policy-сін ауыстыру, кілт шығару, төлем бағытын өзгерту және аудитті өшіру бір бизнес доменінен тыс қолжетімділікті кеңейтуі мүмкін. admin:manage scope-ы да өздігінен тым кең болуы ықтимал. Егер міндеттер шынымен әртүрлі адамдар арасында бөлінсе, admin:identity, admin:keys және admin:policy қажет болуы мүмкін.

Құқықтар схемасының кемшілігін құрал сипаттамасындағы «тек әкімші сұраса ғана қолдан» деген мәтінмен жаппаңыз. Модель бұл сипаттаманы оқуы мүмкін, бірақ шешімді сервер өзі қабылдауы тиіс. Сипаттама шақыру ықтималдығына әсер етеді. Scope пен сервер policy-і шақырудың орындалатынын анықтайды.

Операциялар картасы OAuth кодынан бұрын жасалуы керек

Authorization server-ді баптамас бұрын барлық MCP құралдарының кестесін жасаңыз. Оны толықтай сервер әзірлеушісіне тапсырмаңыз: деректер иесі мен процесс иесі шақыру салдарын жақсырақ біледі. Бұл кесте құрал командасы, идентификация командасы және аудит арасындағы келісімге айналады.

Әр операция үшін бес өрісті толтырыңыз:

Мысалы, команда сатып алулармен жұмыс істейтін MCP серверін жасап жатыр делік. Картаның алғашқы нұсқасы былай көрінуі мүмкін:

operations:
  purchase_order.get:
    required_scopes: [procurement:read]
    resource_check: same_organization

  purchase_order.create_draft:
    required_scopes: [procurement:write]
    resource_check: requester_can_create_for_cost_center

  purchase_order.submit:
    required_scopes: [procurement:submit]
    resource_check: requester_is_draft_owner

  purchase_order.approve:
    required_scopes: [procurement:approve]
    resource_check: approver_limit_covers_total
    step_up_if: total_exceeds_approval_limit

  supplier.export:
    required_scopes: [supplier:export]
    resource_check: export_allowed_for_organization

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

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

Сервер құрал орындалмай тұрып бас тартуы керек

MCP клиенті пайдаланушыға consent screen көрсете алады. Модель тек қолжетімді құралдарды таңдай алады. Gateway сұраулардың бір бөлігін сүзуі мүмкін. Бірақ бұл деңгейлердің ешқайсысы MCP серверіндегі тексерісті алмастырмайды.

Қолжетімділікті сервер құрал атауын түсініп, аргументтерді талдағаннан кейін, бірақ дерекқорға, кезекке, сыртқы API-ге немесе жанама әсерге жүгінбей тұрып тексеріңіз. Осы сәтте сервер клиенттің қандай әрекетті және қай объектіге сұрағанын біледі.

Тексерістің жеңілдетілген схемасы:

async function authorizeToolCall(ctx, call) {
  const rule = policy.forTool(call.name);
  const claims = await verifyAccessToken(ctx.authorization);

  requireAudience(claims, "https://mcp.example.kz");
  requireScope(claims.scope, rule.requiredScopes);

  const resource = await resolveResource(call.name, call.arguments);
  await rule.checkResourceAccess({ claims, resource, args: call.arguments });

  if (rule.requiresStepUp({ claims, resource, args: call.arguments })) {
    throw insufficientScope(rule.stepUpScopes);
  }
}

verifyAccessToken тек JWT қолтаңбасын тексерумен шектелмеуі керек. Серверге issuer (iss), аудитория (aud), жарамдылық мерзімі, рұқсат етілген қолтаңба алгоритмі және scopes тексерісі қажет. Access token мөлдір болмаса, сервер әдетте интроспекция жасайды немесе оның нәтижесін қысқа мерзімге сенімді кеште сақтайды.

Құқықты ешқашан ішкі жол бойынша тексермеңіз. scope.includes("write") сияқты код orders:write қажет жерде profile:write мәнін де өткізіп жібереді. scope жолын мәндер жиыны ретінде талдап, толық элементтерді салыстырыңыз және бірнеше міндетті құқықтың семантикасын ашық анықтаңыз.

function requireScope(scopeString, expected) {
  const granted = new Set((scopeString ?? "").split(/\s+/).filter(Boolean));
  const missing = expected.filter(scope => !granted.has(scope));

  if (missing.length) {
    throw new AuthorizationError("insufficient_scope", { missing });
  }
}

Егер құралға екі тәуелсіз құқық қажет болса, мысалы нақты бөлімшенің клиенттерін экспорттау, ережені scope атауына жасырмаңыз. customer:export мәнін әрекет рұқсаты ретінде, ал бөлімшеге тиесілілікті ресурстық шектеу ретінде тексеріңіз.

Scope challenge артық қолжетімділіктен жақсы

2025 жылғы 25 қарашадағы MCP спецификациясы серверге 401 жауабында талап етілетін scopes-ты WWW-Authenticate тақырыбында көрсетуге кеңес береді. Клиент ағымдағы сұрау үшін challenge ішіндегі scopes-ты беделді дерек ретінде қабылдауы керек. Бұл құқықтарды кезең-кезеңімен арттырудың қалыпты механизмін береді: клиент минималды жиыннан бастап, нақты қорғалған операцияны орындауға тырысқанда ғана қосымша құқық сұрайды.

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

Сервер жауабы мынадай болуы мүмкін:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.kz/.well-known/oauth-protected-resource", scope="procurement:approve"
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32001,
    "message": "Approval permission is required"
  }
}

Мұндай challenge-ті «қолжетімділікке тыйым салынды» деген жай хабарламамен шатастырмаңыз. Клиент authorization server-ден дәл жетіспейтін құқықты сұрауы үшін оған машина оқитын деректер қажет. Дегенмен кез келген MCP клиенті scopes арттыруды мінсіз қолдайды деп ойламаңыз. Нақты клиенттердің әрекетін интеграциялық тестілерде тексеріп, авторизацияны қайталай алмайтын клиенттер үшін түсінікті бас тарту қалдырыңыз.

MCP қауымдастығының қазіргі жұмысында бұл SDK сиқырына сүйенуге болмайтын тұс болып отыр. 2026 жылғы ақпандағы Tool Scopes жұмыс тобының кездесуінде қатысушылар спецификация OAuth пен scope challenge-ті қолдайтынын, бірақ scopes-ты анықтау және оларды құралдармен сәйкестендіру бойынша жалпы ұсынымдар әлі жеткіліксіз екенін, ал құрал аргументтері кейде қажет құқықты өзгертетінін атап өтті. Бұл практикалық ережені растайды: операциялар картасын жеке policy layer ішінде сақтаңыз және оны JSON Schema-дан кітапхана өзі шығарады деп күтпеңіз.

Бір токен беріп, оны ыңғайлылық деп атамаңыз

Бастапқы кезеңдегі ең танымал кеңес мынадай: «әзірге агентке толық қолжетімділік берейік, кейін тарылтамыз». Ол танымал, өйткені алғашқы демонстрация тез өтеді. Бірақ бұл қате: іске қосылғаннан кейін қолжетімділікті тарылту сценарийлерді, refresh token-дерді және пайдаланушы күтулерін бұзады, ал рұқсаттар конфигурацияларға тарап үлгереді.

Артық қолжетімділікке жиі әкелетін төрт нұсқа бар:

• Барлық құралға арналған бір mcp:full_access scope-ы.
• Бекіту, қайтару, жою және жаппай импорт операцияларына жай ғана write беру.
• Әкімшілік құқықтарды machine-to-machine токеніне қосу.
• Алдын ала тек бір оқу операциясын білетін клиентке барлық scopes_supported мәндерін беру.

MCP OAuth тәсілін пайдаланады, бірақ OAuth серверді ең аз құқық қағидасын ұстануға мәжбүрлемейді. Policy-ді команда таңдайды. MCP спецификациясында scopes таңдау стратегиясы қарастырылған: сервердің challenge-і басымдыққа ие, ал негізгі scopes жиыны кәдімгі жұмыс үшін минималды болуы керек. Бұл пайдалы мақсат, бірақ challenge болмаған кезде максимум құқық беруге себеп емес.

Machine-to-machine сценарийінде шекаралар одан да маңызды. Client credentials клиент қызметкер атынан емес, қолданба ретінде әрекет еткенде жарайды. MCP-дің client credentials-ке арналған ресми кеңейтімі дәл осы жағдайды сипаттайды: автоматтандырылған жүйе интерактивті пайдаланушы келісімінің орнына application-level credential алады.

Егер техникалық клиент каталогты әр түн сайын синхрондаса, оған admin:manage қажет емес. catalog:read беріңіз және қажет болса, синхрондаудың нақты бағыты үшін catalog:write қосыңыз. Токен аудиториясын нақты MCP ресурсымен шектеңіз, оның жарамдылық мерзімін қысқартыңыз және әр сервиске бөлек client identity қолданыңыз. Барлық фондық міндетке бір техникалық клиент қолдану баптаулардағы бірнеше жазбаны үнемдейді, бірақ инцидентті тергеуді қиындатады.

RFC 9700 OAuth 2.0 қауіпсіздігінің заманауи ұсынымдарын бекітеді: redirect URI-ді дәл сәйкестендіру, redirect-based flow-ларды қорғау және қауіпті деп танылған режимдерден бас тарту. Интерактивті авторизациясы бар MCP үшін бұл ұқыпты scopes нашар қорғалған authorization code flow схемасын құтқармайтынын білдіреді. Public client үшін Authorization Code пен PKCE қолданыңыз және access token-дерді URL арқылы жібермеңіз.

Токен MCP ресурсына байланыстырылуы керек

Scopes тізімі мінсіз болса да, бір API-ге арналған токенді басқа API қабылдаса, ол көмектеспейді. MCP спецификациясы OAuth Resource Indicators қолдануды талап етеді: клиент авторизация сұрауында да, токен сұрауында да resource параметрін қосып, MCP серверінің канондық URI-ін көрсетеді. Сервер токеннің дәл өзіне арналғанын тексереді.

Бұл кадрлық деректер, сатып алулар, аналитика және әкімшілендіру үшін бөлек MCP серверлері бар ұйымдарда маңызды. Кадр сервері үшін шығарылған employee:read токені сол issuer қолтаңбасын кездейсоқ қабылдайтын кез келген endpoint-ке әмбебап рұқсат болмауы керек.

Тексеріс әдетте екі шартқа келіп тіреледі:

iss = күтілетін authorization server
and
resource/aud = осы MCP серверінің канондық URI-і

Authorization server aud мәні бар JWT шығарса, aud тексеріңіз. Егер мақсатты ресурсты көрсетудің басқа тәсілін қолданса, оны келісімде бекітіп, сәйкессіздік кезінде бас тартуды тестілеңіз. Токенді қолтаңбасы жарамды болғаны үшін ғана қабылдамаңыз. Жарамды қолтаңба оны кім шығарғанын көрсетеді. Бірақ бұл сервердің оны қабылдауы керегін көрсетпейді.

Қашықтағы MCP серверлері үшін discovery де қолжетімділік моделінің бөлігі. Protected Resource Metadata клиентке қай authorization server-пен жұмыс істеу керегін хабарлайды, ал WWW-Authenticate оны metadata URL-іне бағыттай алады. Сервер бірнеше мақұлданған авторизация тәсілімен жұмыс істеуі керек болса, әр клиентте issuer мәнін қатты кодтамаңыз. Бірақ клиентке сенім policy-сіз кез келген issuer таңдауға да рұқсат бермеңіз.

Тестілер тек сәтті шақыруды емес, бас тартуды да дәлелдеуі керек

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

Әр операция тобына арналған минималды тест жиыны:

cases:
  - name: reader_can_get_own_order
    token_scopes: [orders:read]
    tenant: alpha
    tool: get_order
    args: { order_id: "alpha-104" }
    expected: success

  - name: reader_cannot_update_order
    token_scopes: [orders:read]
    tenant: alpha
    tool: update_order
    args: { order_id: "alpha-104", status: "cancelled" }
    expected: insufficient_scope

  - name: reader_cannot_read_other_tenant
    token_scopes: [orders:read]
    tenant: alpha
    tool: get_order
    args: { order_id: "beta-104" }
    expected: forbidden

  - name: writer_cannot_approve_order
    token_scopes: [orders:write]
    tenant: alpha
    tool: approve_order
    args: { order_id: "alpha-104" }
    expected: insufficient_scope

insufficient_scope пен forbidden мәндерін ажыратыңыз. Біріншісі токенде операция түріне құқық жетіспейтінін білдіреді. Екіншісі операция түріне рұқсат бар, бірақ нақты объектіге немесе шартқа тыйым салынғанын білдіреді. Бұл айырмашылық клиенттің дұрыс әрекеті және командаңыздың тергеуі үшін қажет. Барлық жағдайға «403 access denied» қайтарсаңыз, бас тартудың мағыналық бөлігін жоғалтасыз.

Аргументтер шекарасын да тексеріңіз. Бір transfer_funds құралы лимитке дейін кәдімгі payments:write scope-ын, ал лимиттен жоғары сомаға payments:approve және қосымша аутентификацияны талап етуі мүмкін. Егер policy тек құрал атауына қараса, модель формалды түрде рұқсат етілген әдіс арқылы үлкен соманы бере алады.

Журналға subject, client ID, issuer, audience, құрал атауын, талап етілген scopes-ты, нақты берілген scopes-ты, шешім түрін және ресурс идентификаторын қауіпсіз түрде жазыңыз. Access token-ді жазбаңыз. Тек жөндеу ыңғайлы болсын деп жеке деректері бар аргументтерді толық күйінде журналға көшірмеңіз.

Схема жаңа модельдер мен жаңа маршруттарға төтеп беруі керек

Модельдер арасындағы маршрутизация қолжетімділік ережелерін өзгертпейді. Бір агент MCP құралдарын бірнеше провайдер арқылы шақырса, құқық JSON-RPC сұрауын қай модель құрғанына емес, токен мен сервер policy-іне байланысты анықталады. Бұл команда құнын, кідірісті немесе құрал шақыру сапасын жақсарту үшін модельді ауыстырғанда аса маңызды.

AI Router OpenAI-үйлесімді сұрауды қабылдап, оны әртүрлі модельдерге бағыттай алады, бірақ MCP сервері scopes-ты өз орындау нүктесінде тексеруге міндетті. Авторизацияны prompt-қа, модель таңдауға немесе аргументтердің бизнес мағынасын көрмейтін gateway-ге көшірмеңіз.

Атаулардың әдемілігінен схеманың тұрақтылығы маңызды. Қажет болмаса, orders:read мәнін orders:view деп өзгертпеңіз: ескі токендер, consent history және policy ережелері алшақтай бастайды. Құқықтың мағынасы шынымен өзгерсе, жаңа scope қосыңыз, көшу кезеңін қолдаңыз және ескісін жоспар бойынша қайтарып алыңыз. Бар scope атауының мағынасын үнсіз өзгертпеңіз.

Жаңа құралды іске қоспас бұрын қысқа review талап етіңіз: операция, минималды scope, ресурстық тексеріс, күшейту шарттары және бас тарту тестілері. Егер құрал авторы осы бес тармақты толтыра алмаса, құрал продакшенге дайын емес. OAuth тәртіпті өздігінен орнатпайды, бірақ оны тексеруге мүмкіндік береді.