Установка и настройка MCP Server

Primo RPA MCP Server обеспечивает подключение AI-агентов к Primo RPA Orchestrator по протоколу Model Context Protocol (MCP). Компонент устанавливается как отдельная служба и публикуется для клиентов через Nginx Оркестратора.

Сервер распространяется в виде self-contained-сборки: отдельная установка среды .NET не требуется.

1. Системные требования

• Primo RPA Orchestrator версии 1.26.7 или выше.
• Сервер с ОС Windows x64 или Linux x64.
• Сетевое соединение MCP Server с Nginx Оркестратора.
• Учётная запись Оркестратора с разрешениями на чтение проектов, создание ассетов и запуск роботов.
• Возможность настроить Nginx для публикации конечной точки /mcp.

MCP Server можно установить на сервере Оркестратора или на отдельной машине. Если сервер Nginx и MCP Server расположены на разных машинах, потребуется настроить доступ к внутреннему HTTP-порту MCP Server.

2. Комплект поставки

Основные файлы архива:

Имена архивов соответствуют сборке 1.26.7.1. При установке другой сборки используйте имя архива из соответствующего пакета поставки.

3. Настройка MCP Server

3.1. Файлы и порядок загрузки настроек

MCP Server использует настройки из следующих источников (каждый следующий источник переопределяет предыдущий):

1. appsettings.json – общие параметры.
2. appsettings.ProdWin.json или appsettings.ProdLinux.json – параметры соответствующей платформы.
3. Переменные окружения, например ORCHESTRATOR__PASSWORD и MCP__APIKEYS__0.

Значение переменной ASPNETCORE_ENVIRONMENT должно быть ProdWin для Windows или ProdLinux для Linux.

Редактируйте файл настроек своей платформы, а не appsettings.json: последний может быть заменён при обновлении.

3.2. Основные параметры

Ниже приведён пример конфигурации, а не файл с действующими учётными данными:

{
  "Kestrel": {
    "EndPoints": {
      "InternalHttp": {
        "Url": "http://127.0.0.1:5080"
      }
    }
  },
  "orchestrator": {
    "baseUrl": "https://localhost:44392/",
    "userName": "<учётная-запись-Оркестратора>",
    "password": "<пароль>",
    "ignoreSslErrors": false
  },
  "mcp": {
    "apiKeys": ["<уникальный-API-ключ>"]
  }
}

В примере MCP Server и Nginx располагаются на одном сервере. Если Nginx установлен на другой машине, укажите в Kestrel.EndPoints.InternalHttp.Url сетевой интерфейс, доступный серверу Nginx, и ограничьте доступ к этому порту межсетевым экраном.

Важно: в исходной сборке могут присутствовать тестовые учётные данные. Перед первым запуском обязательно замените пароль и ключи. Не используйте одинаковые или общедоступные ключи и ограничьте доступ к конфигурационным файлам.

3.3. Дополнительные параметры

Для изменения параметров добавьте соответствующие вложенные объекты в файл appsettings.ProdWin.json или appsettings.ProdLinux.json.

3.4. Настройка доступных проектов

По умолчанию AI-агентам доступны активные проекты с тегом MCP.

1. Откройте нужный RPA-проект в Оркестраторе.
2. Назначьте ему тег MCP либо тег, указанный в catalog.orchestratorSource.projectTag.
3. Убедитесь, что проект имеет активную версию.
4. Проверьте наличие инструмента в ответе tools/list.

Перезапуск MCP Server после изменения тега не требуется: при следующем запросе tools/list список формируется заново.

Для возврата результата робот должен получать имя глобального ассета через входную переменную assetResultName и записывать в ассет результат с помощью активности Set asset. Подробнее – «Операции MCP Server».

4. Установка в Windows

Команды выполняются в PowerShell 7 от имени администратора.

Шаг 1. Распаковка архива

Распакуйте архив в папку установки, например C:\Primo\McpServer:

Expand-Archive .\primo-rpa-mcp-1.26.7.1.zip -DestinationPath 'C:\Primo\McpServer'

Шаг 2. Настройка конфигурации

Откройте файл C:\Primo\McpServer\appsettings.ProdWin.json, укажите адрес Оркестратора, учётные данные, уникальные API-ключи и параметры внутреннего HTTP-сервера, приведённые в разделе 3.

Если Nginx и MCP Server расположены на одном сервере, рекомендуется ограничить прослушивание адресом 127.0.0.1.

Шаг 3. Проверка запуска из консоли

Set-Location 'C:\Primo\McpServer'
$env:ASPNETCORE_ENVIRONMENT = 'ProdWin'
.\PrimoRpa.McpServer.Api.exe

При успешном запуске сервер выводит сообщения журнала в консоль. Для завершения нажмите Ctrl+C.

Шаг 4. Регистрация и запуск службы

[System.Environment]::SetEnvironmentVariable(
  'ASPNETCORE_ENVIRONMENT',
  'ProdWin',
  [System.EnvironmentVariableTarget]::Machine
)
 
New-Service -Name 'Primo.McpServer.Api' `
  -BinaryPathName 'C:\Primo\McpServer\PrimoRpa.McpServer.Api.exe' `
  -DisplayName 'Primo RPA MCP Server' `
  -StartupType Automatic
 
Start-Service 'Primo.McpServer.Api'
Get-Service 'Primo.McpServer.Api'

Ожидаемое состояние службы – Running. В приложении Службы Windows (services.msc) отображаемое имя – Primo RPA MCP Server, внутреннее имя – Primo.McpServer.Api. По материалам разработчика служба выполняется от имени Local System.

Если переменная ASPNETCORE_ENVIRONMENT=ProdWin уже задана при установке Оркестратора, повторно устанавливать её не нужно. Если служба уже зарегистрирована, повторное выполнение New-Service не требуется.

Шаг 5. Настройка межсетевого экрана (при необходимости)

Если Nginx расположен на другой машине, разрешите подключение к порту MCP Server только с IP-адреса Nginx:

New-NetFirewallRule -DisplayName 'McpServer.Api (5080)' `
  -Direction Inbound -LocalPort 5080 -Protocol TCP `
  -RemoteAddress '<IP-адрес Nginx>' -Action Allow

В этой конфигурации MCP Server должен прослушивать сетевой адрес, доступный машине Nginx; адрес 127.0.0.1 подходит только для локальных подключений.

Обновление в Windows

Перед обновлением сохраните платформенный файл настроек:

Stop-Service 'Primo.McpServer.Api'
Copy-Item 'C:\Primo\McpServer\appsettings.ProdWin.json' "$env:TEMP\appsettings.ProdWin.json"
Expand-Archive '.\primo-rpa-mcp-1.26.7.1.zip' -DestinationPath 'C:\Primo\McpServer' -Force
Copy-Item "$env:TEMP\appsettings.ProdWin.json" 'C:\Primo\McpServer\appsettings.ProdWin.json' -Force
Remove-Item "$env:TEMP\appsettings.ProdWin.json"
Start-Service 'Primo.McpServer.Api'

Указанное имя архива замените именем устанавливаемой версии. После обновления проверьте конфигурацию на наличие новых параметров, состояние службы и доступность /mcp/health.

5. Установка в Linux

Команды выполняются пользователем с правами sudo.

Шаг 1. Распаковка архива

Разместите архив в ~/install и выполните команды:

# Выполните только при отсутствии пользователя primo-rpa-service
sudo useradd --system --no-create-home --shell /sbin/nologin primo-rpa-service
 
sudo mkdir -p /opt/Primo/McpServer
sudo unzip ~/install/primo-rpa-mcp-1.26.7.1-linux.zip -d /opt/Primo/McpServer
sudo chmod +x /opt/Primo/McpServer/PrimoRpa.McpServer.Api
sudo chown -R primo-rpa-service:primo-rpa-service /opt/Primo/McpServer

Если пользователь primo-rpa-service уже существует, пропустите команду useradd.

Шаг 2. Настройка конфигурации

Откройте файл:

sudo nano /opt/Primo/McpServer/appsettings.ProdLinux.json

Заполните параметры, перечисленные в разделе 3. После сохранения ограничьте доступ к файлу:

sudo chmod 640 /opt/Primo/McpServer/appsettings.ProdLinux.json

Шаг 3. Регистрация службы systemd

Скопируйте unit-файл из архива:

sudo cp /opt/Primo/McpServer/Primo.McpServer.Api.service /etc/systemd/system/Primo.McpServer.Api.service

В поставляемом unit-файле предусмотрены окружение ProdLinux, рабочая папка /opt/Primo/McpServer, пользователь primo-rpa-service и перезапуск службы при сбое. Если используется другая папка установки, скорректируйте пути в unit-файле.

Шаг 4. Запуск и проверка состояния

sudo systemctl daemon-reload
sudo systemctl enable --now Primo.McpServer.Api
sudo systemctl status Primo.McpServer.Api --no-pager

Ожидаемое состояние – active (running).

Для просмотра сообщений службы выполните:

sudo journalctl -u Primo.McpServer.Api -f

Если Nginx находится на другом сервере, разрешите соединения на порт 5080 только с его адреса.

Обновление в Linux

sudo systemctl stop Primo.McpServer.Api
sudo unzip -o ~/install/primo-rpa-mcp-1.26.7.1-linux.zip \
  -d /opt/Primo/McpServer -x appsettings.ProdLinux.json
sudo chmod +x /opt/Primo/McpServer/PrimoRpa.McpServer.Api
sudo chown -R primo-rpa-service:primo-rpa-service /opt/Primo/McpServer
sudo systemctl start Primo.McpServer.Api

Параметр -x appsettings.ProdLinux.json исключает файл настроек из распаковки, поэтому действующая конфигурация сохраняется. После обновления проверьте необходимость новых параметров и работоспособность службы.

6. Настройка Nginx

MCP Server публикуется через Nginx Оркестратора. Добавьте upstream и правило маршрутизации в соответствующие блоки существующего конфигурационного файла Nginx:

# Добавьте в контекст http (вне блока server)
upstream mcp {
    server 127.0.0.1:5080;
}
 
# Добавьте внутрь существующего блока server Оркестратора
location /mcp {
    proxy_pass http://mcp;
    proxy_buffering off;
    proxy_read_timeout 180s;
}

В примере Nginx и MCP Server находятся на одной машине. Если они расположены на разных машинах, замените адрес в upstream на IP-адрес или имя сервера MCP.

• proxy_pass http://mcp; передаёт запросы без изменения пути /mcp.
• proxy_buffering off; требуется для потоковых ответов SSE при вызове инструментов.
• proxy_read_timeout 180s; должен превышать значение dispatcher.timeoutSeconds (по умолчанию 120 с).

Проверьте конфигурацию и примените изменения:

sudo nginx -t
sudo nginx -s reload

Сетевые соединения: AI-агенты подключаются по HTTPS к Nginx Оркестратора. Nginx обращается к MCP Server по внутреннему HTTP-порту (в примерах 5080). MCP Server обращается к Оркестратору по адресу orchestrator.baseUrl.

Безопасность. Внутреннее соединение на порту 5080 использует HTTP. Если Nginx находится на другой машине, разрешите соединение только из защищённого сетевого сегмента и только с адреса Nginx. Не открывайте этот порт в Интернет. При совместном размещении ограничьте прослушивание 127.0.0.1:5080.

7. Проверка работоспособности

После установки проверьте службу, сетевое соединение, авторизацию и доступность инструментов.

7.1. Проверка состояния MCP Server

При публикации через Nginx выполните:

curl https://orchestrator.example.local:44392/mcp/health

Для локальной проверки без Nginx:

curl http://127.0.0.1:5080/mcp/health

Ожидается HTTP 200 и ответ с "status":"healthy" и "orchestratorReachable":true. HTTP 503 и "orchestratorReachable":false означают, что MCP Server работает, но не может подключиться к Оркестратору.

Если на тестовом стенде используется самоподписанный сертификат, для диагностики можно добавить -k в curl. В промышленной среде используйте доверенный TLS-сертификат и проверку его подлинности. В PowerShell для вызова используйте curl.exe.

7.2. Проверка через Swagger

1. Откройте в браузере https://orchestrator.example.local:44392/mcp/swagger/index.html.

2. Нажмите Authorize, введите API-ключ без префикса Bearer и подтвердите авторизацию.

3. Откройте McpEndpoint → POST /mcp → Try it out.

4. Введите тело запроса:

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

5. Нажмите Execute. Ожидается HTTP 200 и ответ:

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

6. Для проверки доступных проектов повторите запрос, заменив method на tools/list.

Важно: для подключения AI-агентов используется только POST /mcp. Другие маршруты Swagger (в том числе /mcp/catalog/...) относятся к техническому API и в данном руководстве не рассматриваются.

7.3. Типичные проблемы

См. также

• Интеграция с AI-агентами через MCP – назначение и схема взаимодействия.
• Операции MCP Server – использование инструментов, запуск проектов и получение результатов.