Руководство по интеграции MCP

Возврат результата авторизации

Установите SDK:

pnpm add mcp-auth-web

Среды API (engineUrl — базовый адрес без пути):

Тестовая: https://aim-api-test.proton-system.com
Рабочая: https://aim-api.proton-system.com

Полный URL возврата авторизации: https://xxx.com/openapi/v1/mcp/authorization/callback

SDK добавляет путь автоматически.

После успешного входа верните учётные данные:

import { createMcpAuthClient } from 'mcp-auth-web'

const mcpAuth = createMcpAuthClient({
  engineUrl: 'https://aim-api-test.proton-system.com',
})

mcpAuth.complete({
  Authorization: `Bearer ${token}`,
})

При ошибке входа или отмене:

mcpAuth.fail({ code, message })
mcpAuth.cancel()

Начиная с mcp-auth-web@0.3.1, getMcpAuthErrorMessage(error) возвращает безопасные стандартные сообщения SDK на китайском языке. Интерфейс отвечает за отображение; коды ошибок можно использовать для перевода. Перехватывайте ошибки complete(), fail() и cancel(). Не вызывайте fail() безусловно в catch метода complete() и не раскрывайте учётные данные или URL авторизации из исходных ошибок.

import { getMcpAuthErrorMessage } from 'mcp-auth-web'

try {
  mcpAuth.complete({ Authorization: `Bearer ${token}` })
} catch (error) {
  message.error(getMcpAuthErrorMessage(error))
}

engineUrl — адрес Engine, предоставленный платформой. complete напрямую принимает Headers учётных данных, которые использует MCP. SDK читает exp из Bearer JWT в Authorization и автоматически формирует expiresAt, поэтому срок действия передавать не нужно.

SDK автоматически выбирает HTTPS callback или существующее окно авторизации App. В mcp-auth-web@0.3.0 изменён формат входных данных complete; при обновлении удалите оболочку headers и передаваемый вручную expiresAt. Без engineUrl продолжает использоваться существующее окно авторизации App.

Если метод вернул false, на странице нет доступного способа вернуть авторизацию:

if (!mcpAuth.isAvailable()) {
  message.error('Текущая среда не поддерживает возврат результата авторизации')
}

Для проверки запустите авторизацию в App и завершите вход. Возврат в App со статусом «Авторизовано» означает успех. В production страница входа и Engine должны использовать доступный устройству HTTPS с действующим сертификатом. Не записывайте учётные данные и URL авторизации в журналы.

Общие аннотации риска Tool

Tool для чтения:

annotations: {
  readOnlyHint: true
}

Tool для записи:

annotations: {
  destructiveHint: true
}

Типы Tool

1. Tool со списком

Если Tool возвращает кандидатов, из которых пользователь выбирает значение для другого параметра Tool, добавьте в корень outputSchema следующий объект:

outputSchema: {
  type: "object",
  properties: {...}, // необязательно
  "x-prerequisiteCandidate": {
    itemsPath: "data",
    valuePath: "id",
    labelPath: "name"
  }
}

Назначение трёх полей:

itemsPath: расположение массива кандидатов в результате Tool.
valuePath: поле каждого кандидата, которое станет итоговым значением.
labelPath: поле каждого кандидата, которое показывается пользователю.

Например, Tool возвращает:

{
  "data": [
    { "id": "1", "name": "Магазин A" },
    { "id": "2", "name": "Магазин B" }
  ]
}

Тогда:

itemsPath: "data" означает, что список кандидатов находится в массиве data.
valuePath: "id" означает, что id выбранного элемента передаётся целевому Tool.
labelPath: "name" означает, что карточка выбора показывает name элемента.

Контрольный список