Тема
Вызов и ответ
Подключение
| Параметр | Значение |
|---|---|
| Протокол | 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после истечения срока подключение потребует войти снова.- метаданные защищённого ресурса (RFC 9728) по адресу
Постоянный токен доступа. Его выпускает бизнес, при подключении токен вставляют в кабинет. Платформа хранит его без срока и не обновляет.
Ответ 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_chars | 32000 | символов в сериализованном structuredContent ответа |
max_page_size | 200 | элементов на странице спискового инструмента |
principal_max_ttl_sec | 300 | секунд жизни подписанного принципала |
transcript_default_chars | 12000 | символов в окне расшифровки по умолчанию |
transcript_max_chars | 24000 | символов в окне расшифровки наибольшее |