Операции MCP Server

В этом разделе описано, как AI-агент взаимодействует с RPA-проектами Primo RPA Orchestrator через MCP Server. Операции приведены в последовательности типового сценария: подключить агента → получить доступные проекты → вызвать проект → получить результат.

Перед началом. MCP Server должен быть установлен и доступен по HTTPS. Администратор должен настроить API-ключ, учётную запись Оркестратора и разрешить доступ к нужным проектам. См. «Установка и настройка MCP Server».

1. Подключение AI-агента

MCP Server принимает запросы по одному адресу:


POST https://orchestrator.example.local:44392/mcp
Authorization: Bearer <API-ключ>
Content-Type: application/json

orchestrator.example.local:44392 – пример адреса Nginx Оркестратора. Подставьте фактический адрес своего сервера. Ключ берётся из параметра mcp.apiKeys в настройках MCP Server.

Клиент должен поддерживать транспорт Streamable HTTP. При ручной проверке можно отправить JSON-RPC-запрос через Swagger или HTTP-клиент.

Проверка подключения

Отправьте запрос:


{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ping"
}

Ожидаемый ответ:


{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}

Что означает id: это идентификатор конкретного JSON-RPC-запроса, который клиент назначает самостоятельно для сопоставления запроса с ответом. Это не идентификатор проекта, робота или инструмента. При вызове проекта его имя указывается отдельно в params.name.

Для проверки через Swagger откройте https://orchestrator.example.local:44392/mcp/swagger/index.html, нажмите Authorize и введите API-ключ без слова Bearer. Затем выберите McpEndpoint → POST /mcp → Try it out и отправьте приведённый запрос.

2. Получение списка доступных проектов

Задача: определить, какие RPA-проекты AI-агент может запускать.

Метод MCP: tools/list.

Адрес HTTP-запроса: POST /mcp (отдельного HTTP-адреса /tools/list нет).

Тело запроса:


{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Ответ содержит массив result.tools. Каждый элемент описывает один доступный RPA-проект:

Поле	Назначение
`name`	Имя инструмента. Используется в `params.name` при вызове `tools/call`. Не обязательно совпадает с названием проекта буквально.
`description`	Описание проекта или автоматически сформированный текст.
`inputSchema`	Схема входных параметров проекта и служебных параметров запуска.
`inputSchema.properties`	Допустимые параметры и их типы.
`inputSchema.required`	Обязательные параметры.

Почему видны не все проекты

По умолчанию MCP Server выбирает активные версии проектов с тегом MCP. Значение тега задаётся параметром catalog.orchestratorSource.projectTag в конфигурации сервера.

Чтобы добавить проект в список доступных агенту, назначьте проекту в Оркестраторе тег MCP (либо другой тег, указанный в конфигурации). Чтобы скрыть проект, снимите тег. Если параметр projectTag пуст, отображаются все активные проекты. Список обновляется при каждом новом вызове tools/list, перезапуск службы не требуется.

Если настроено catalog.orchestratorSource.requireAssetNameParam: true, проекты без переменной для возврата результата дополнительно исключаются из списка инструментов.

Как формируется имя инструмента

Имя создаётся из названия проекта: приводится к нижнему регистру, кириллица транслитерируется, недопустимые символы заменяются подчёркиванием. Максимальная длина – 64 символа. При совпадениях добавляются числовые суффиксы.

Для вызова используйте точное значение name из ответа tools/list, а не предполагаемое имя проекта.

3. Подготовка RPA-проекта к запуску через MCP

Чтобы агент мог получить результат выполнения, подготовьте проект:

В Оркестраторе откройте нужный RPA-проект и назначьте ему тег MCP.
Добавьте входную переменную In с именем assetResultName (если администратор не изменил параметр catalog.orchestratorSource.assetNameParam).
Убедитесь, что в Main.ltw включён приём аргументов: <UseArgs>true</UseArgs>.
В конце проекта добавьте активность Set asset. Она должна записывать строковый результат в глобальный ассет, имя которого робот получает через переменную assetResultName.
При необходимости задайте входные аргументы проекта, их описания, значения по умолчанию и ограничения в Оркестраторе.

Имя ассета создаёт MCP Server отдельно для каждого вызова. Передавать assetResultName вручную в tools/call не требуется.

Ограничения входных параметров

В Оркестраторе откройте RPA-проекты → Все RPA-проекты → Аргументы (In, Out, InOut), задайте ограничения для аргументов In и InOut, затем нажмите Применить и Сохранить.

Поддерживаются обязательность, допустимые значения, числовые минимумы и максимумы, ограничения длины строки и регулярные выражения. Ограничения дат в inputSchema не переносятся; множественный выбор для аргументов агента не поддерживается.

4. Запуск RPA-проекта

Задача: инициировать выполнение проекта роботом и получить результат.

Метод MCP: tools/call.

Адрес HTTP-запроса: POST /mcp.

Тело запроса (пример):


{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "calc_input_5",
    "arguments": {
      "in_Number": "\"7\""
    }
  }
}

Здесь id: 3 – идентификатор JSON-RPC-запроса, calc_input_5 – имя инструмента из tools/list, а in_Number – входной параметр проекта.

Важно о строковых значениях: в текущей реализации аргументы робота вычисляются как выражения C#. Поэтому строку требуется передавать как строковый литерал C#, помещённый в JSON-строку: "\"7\"". Например, для строки hello world укажите "\"hello world\"". Числовое выражение можно передать строкой "100". Логическое значение передавайте строкой "true", а не JSON-значением true.

Аргументы проверяются по inputSchema до запуска робота. Необязательные аргументы, не указанные в запросе, получают значения по умолчанию из Оркестратора.

4.1. Запуск через очередь проектов

Это режим по умолчанию. Вызовите инструмент без параметра machineIp. Оркестратор поставит проект в очередь в соответствии с её стратегией. Когда проект будет выбран роботом, робот выполнит его, после чего MCP Server вернёт результат.

Учитывайте, что вызов может завершиться по таймауту, если стратегия очереди не позволяет выбрать проект или свободный робот отсутствует. При ошибке проверьте наличие проекта в очереди, настройки её стратегии и состояние роботов.

4.2. Запуск на конкретной машине

Чтобы выполнить проект на определённой машине, передайте machineIp:


{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "calc_input_5",
    "arguments": {
      "in_Number": "\"7\"",
      "machineIp": "10.0.0.15"
    }
  }
}

Оркестратор выберет свободного робота на указанной машине. Если подходящего робота нет, запуск может быть отклонён.

4.3. Скачивание проекта без запуска

Чтобы скачать проект на машину робота, передайте machineIp и downloadOnly: true. Дополнительно можно указать projectPath – целевую папку.


{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "calc_input_5",
    "arguments": {
      "machineIp": "10.0.0.15",
      "downloadOnly": true,
      "projectPath": "C:\\RPA\\Projects"
    }
  }
}

Проект будет скачан, но робот не запустится. Ответ подтверждает передачу команды на скачивание, а не результат выполнения робота. Если не указать projectPath, используется папка проектов робота.

Без machineIp параметр downloadOnly не применяется: проект будет отправлен в очередь запуска. projectPath имеет значение только при скачивании.

5. Получение результата выполнения

При обычном запуске MCP Server:

Проверяет аргументы инструмента.
Создаёт глобальный ассет с уникальным именем вида mcp-<GUID>.
Передаёт имя ассета роботу через входную переменную assetResultName.
Ожидает, пока робот запишет результат в ассет активностью Set asset.
Возвращает значение ассета агенту и удаляет временный ассет.

Ответ tools/call передаётся в формате SSE (text/event-stream). Например, если робот записал строку {"digit":"7"}, событие будет выглядеть так:


data: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"digit\":\"7\"}"}],"isError":false}}

Поле result.content[0].text содержит результат робота; isError: false означает успешное выполнение вызова.

Время ожидания задаёт dispatcher.timeoutSeconds (по умолчанию 120 секунд). При превышении времени ожидания робот автоматически не останавливается: он может продолжить выполнение, но временный ассет уже будет удалён, поэтому результат не вернётся агенту.

6. Диагностика ошибок

Ошибка или признак	Возможная причина и действие
HTTP `401 Unauthorized`	Не передан заголовок `Authorization` или указан неверный API-ключ.
`Tool '…' not found in catalog`	Неправильно указано имя инструмента, нет активной версии проекта или отсутствует требуемый тег. Повторите `tools/list`.
`Argument validation failed`	Аргументы не соответствуют `inputSchema`. Проверьте типы и ограничения, включая кавычки для строковых литералов C#.
`Project … has no 'assetResultName' variable`	В проекте отсутствует входная переменная для имени ассета. Добавьте её.
`Orchestrator error: Failed to enqueue project …`	Проект не принят в очередь. Проверьте правила очереди и запрет повторного добавления.
`Robot execution failed`	Ошибка выполнения робота. Просмотрите журнал робота в Оркестраторе по `operationKey`, указанному в сообщении.
`Robot execution failed: no_output`	Робот завершился, но не записал результат в ассет. Проверьте Set asset, `assetResultName` и `UseArgs`.
`Robot execution timed out`	Превышено время ожидания результата. Проверьте очередь, робота и настройку таймаутов.
`Connection failed`	MCP Server не может подключиться к Оркестратору. Проверьте адрес, порт и сертификат.

Ошибки вызова инструмента передаются в ответе с isError: true. Ошибки JSON-RPC-протокола используют поле error (например, -32601 для неподдерживаемого метода).

7. Справочник MCP-методов

Все перечисленные ниже методы передаются в поле method тела POST /mcp. Они не являются отдельными HTTP-маршрутами.

Метод	Назначение	Формат ответа
`initialize`	Инициализация взаимодействия клиента и сервера.	JSON
`ping`	Проверка ответа MCP Server.	JSON
`tools/list`	Получение инструментов, доступных агенту.	JSON
`tools/call`	Вызов инструмента и получение результата.	SSE

Различие между MCP и техническим API: в Swagger также могут отображаться /mcp/catalog/tools, /mcp/catalog/orchestrator/projects и другие служебные маршруты. Они используются внутренними компонентами сервера и не являются эквивалентами методов tools/list и tools/call для AI-агентов. Для работы по MCP используйте POST /mcp.

См. также

Интеграция с AI-агентами через MCP – назначение и схема взаимодействия.
Установка и настройка MCP Server – конфигурация, запуск и проверка службы.