Skip to content

Вызов и ответ ​

Подключение ​

ПараметрЗначение
Протоколstreamable-http
Формат вызоваjsonrpc-2.0
АвторизацияBearer: токен по OAuth или постоянный, способ выбирают при подключении сервера в кабинете NORM

Платформа шлёт токен в заголовке Authorization: Bearer <токен> каждого запроса к серверу. Откуда она его берёт, выбирают при подключении сервера в кабинете NORM.

  • OAuth по спецификации авторизации MCP. При подключении открывается страница входа сервера авторизации, токен платформа получает сама. Для этого серверу нужны:

    • метаданные защищённого ресурса (RFC 9728) по адресу /.well-known/oauth-protected-resource с путём MCP-адреса или в корне сайта. Для https://example.com/mcp платформа сначала спросит https://example.com/.well-known/oauth-protected-resource/mcp, потом https://example.com/.well-known/oauth-protected-resource. В resource — адрес MCP-сервера, в authorization_servers — адрес сервера авторизации, платформа берёт первый;
    • метаданные сервера авторизации (RFC 8414 или OpenID Connect Discovery): issuer совпадает с адресом из authorization_servers, в response_types_supported есть code;
    • PKCE с методом S256 в code_challenge_methods_supported;
    • динамическая регистрация клиента (RFC 7591, registration_endpoint): платформа регистрируется сама, публичным клиентом без секрета.

    Токен платформа обновляет сама по refresh_token, когда его срок подходит к концу. Срок она знает только из expires_in. Токен без expires_in платформа считает бессрочным и не обновляет, а ответ на обновление без expires_in не принимает. Без refresh_token после истечения срока подключение потребует войти снова.

  • Постоянный токен доступа. Его выпускает бизнес, при подключении токен вставляют в кабинет. Платформа хранит его без срока и не обновляет.

Ответ HTTP 401 на любой запрос платформа считает отказом токена. В кабинете подключение получит пометку «Требуется повторный вход», если токен получен по OAuth, или «Требуется новый токен», если он постоянный.

Если схема аргументов, которую сервер объявил в tools/list, запрещает дополнительные поля, платформа перед вызовом убирает аргументы, которых в ней нет. Поэтому новые необязательные аргументы контракта не ломают сервер со строгой схемой. При открытой схеме ничего не убирается.

Принципал ​

Кто вызывает инструмент, сервер узнаёт из принципала — подписанного платформой токена в отдельном заголовке.

ПараметрЗначение
ЗаголовокX-Norm-Principal
Алгоритм подписиES256
Ключи для проверки/.well-known/norm-jwks.json по адресу из утверждения iss
Наибольший срок жизни300 с

Утверждения принципала. Кто пользователь, из какого тенанта, с какими правами, каким способом вошёл и каким токеном провайдера это можно подтвердить.

ПолеОбязательноТипЗачем
audдаstringДля какого сервера выпущен: чужой принципал сервер отвергает.
auth_methodдаstringКак пользователь вошёл на платформу.
correlation_idдаstringСквозной номер запроса: по нему находят вызов в журналах всех сторон.
delegation_idдаstringПо какому поручению агент действует от имени пользователя.
expдаintegerДо какого момента действует, в секундах Unix-времени.
iatдаintegerКогда выпущен, в секундах Unix-времени.
issдаstringКто выпустил принципал: так сервер понимает, чьим ключом проверять подпись.
jtiдаstringУникальный номер принципала: сервер может запоминать его, чтобы не принять один и тот же дважды.
roleдаstringРоль пользователя на платформе.
scopesдасписок stringЧто пользователю разрешено делать.
subдаstringКакой пользователь делает вызов.
tenantдаstringИз какой компании пользователь: данные чужой компании не отдают.
provider_tokenнетstringТокен провайдера входа, если серверу нужно подтвердить личность у него.

Сервер проверяет принципал в два шага. Первый обязателен: подпись по ключам платформы, совпадение aud со своим подключением и срок действия. Второй — по выбору бизнеса: подтвердить у провайдера по auth_method и provider_token, что пользователь ещё действующий. Токен провайдера разрешён только для этой проверки, не для доступа к данным провайдера от имени пользователя; в журналах и отчётах он маскируется.

Ответ инструмента ​

Успешный ответ любого инструмента каталога — это structuredContent из двух частей: обязательного конверта и данных инструмента в поле data. Поля data описаны у каждого инструмента в разделе «Каталог инструментов».

Конверт ответа. Обязательная часть успешного ответа любого инструмента каталога: откуда данные, насколько свежи, есть ли продолжение. Дополнительные поля разрешены: ответ сервера может быть шире контракта.

ПолеОбязательноТипЗачем
freshnessдаFreshnessНа какой момент данные верны и не устарели ли они.
source_refsдасписок SourceRefОткуда взяты данные: чтобы сослаться на источник.
pageнетPageЕсть ли продолжение и как его запросить.

SourceRef ​

Ссылка на источник. Система-источник, ключ записи в ней и человекочитаемая подпись.

ПолеОбязательноТипЗачем
refдаstringКакая запись в этой системе: чтобы найти её там.
sourceдаstringИз какой системы данные.
labelнетstringПодпись для человека, если ссылку нужно показать.

Freshness ​

Свежесть. Момент данных, срок годности в секундах и признак устаревания.

ПолеОбязательноТипЗачем
as_ofдаstring (date-time)На какой момент данные верны.
staleдаbooleanУстарели ли данные; true — на них лучше не опираться без проверки.
ttl_secдаintegerСколько секунд данные можно считать свежими.

Page ​

Страница. Есть ли ещё данные и непрозрачный курсор для следующей страницы.

ПолеОбязательноТипЗачем
has_moreдаbooleanЕсть ли ещё страницы.
next_cursorнетstringЧто передать в cursor, чтобы получить следующую страницу.

Постраничная выдача ​

Инструмент с пометкой «списковый» отдаёт данные страницами. Он обязан принимать аргументы limit и cursor и возвращать в конверте page. Курсор непрозрачен: клиент передаёт page.next_cursor как есть, не разбирая его.

ListInput ​

Вход спискового инструмента. Размер страницы и непрозрачный курсор. Обязателен у инструмента, помеченного list: true.

ПолеОбязательноТипЗачем
cursorнетstringКакую страницу прислать: next_cursor из прошлого ответа. Без него — первую.
limitнетintegerСколько записей прислать на одной странице.

Пределы ​

ПределЗначениеЧто ограничивает
max_result_chars32000символов в сериализованном structuredContent ответа
max_page_size200элементов на странице спискового инструмента
principal_max_ttl_sec300секунд жизни подписанного принципала
transcript_default_chars12000символов в окне расшифровки по умолчанию
transcript_max_chars24000символов в окне расшифровки наибольшее