SentinelX Core MCP

MCP-сервер, который проксирует вызовы инструментов к запущенному экземпляру SentinelX Core.

Этот репозиторий представляет собой переносимый мост MCP/OAuth. Он предназначен для работы отдельно от sentinelx-core, который предоставляет базовый HTTP-агент.

Что он делает

• предоставляет MCP-инструменты, работающие на базе SentinelX Core

• проверяет токены носителя (bearer tokens) через OIDC/JWKS

• пересылает вызовы инструментов к вышестоящему API SentinelX Core

• добавляет отдельную границу продукта для MCP-интеграций

Зависимость от SentinelX Core

Для работы этого проекта требуется запущенный экземпляр SentinelX Core.

Типичная пара для локальной разработки:

• SentinelX Core: http://127.0.0.1:8092

• SentinelX Core MCP: http://127.0.0.1:8099

Типичные примеры установленной пары:

• SentinelX Core: http://127.0.0.1:8091

• SentinelX Core MCP: http://127.0.0.1:8098

Это примеры значений по умолчанию, а не гарантированно свободные порты. Всегда проверяйте фактические значения, настроенные в /etc/sentinelx/sentinelx.env и /etc/sentinelx-core-mcp/sentinelx-core-mcp.env.

Быстрый старт

git clone git@github.com:pensados/sentinelx-core-mcp.git
cd sentinelx-core-mcp
sudo bash install.sh

Затем отредактируйте:

sudo nano /etc/sentinelx-core-mcp/sentinelx-core-mcp.env

Установите как минимум:

MCP_PORT=8098
SENTINELX_URL=http://127.0.0.1:8091
SENTINELX_TOKEN=changeme
OIDC_ISSUER=https://auth.example.com/realms/sentinelx
OIDC_JWKS_URI=https://auth.example.com/realms/sentinelx/protocol/openid-connect/certs
OIDC_EXPECTED_AUDIENCE=
RESOURCE_URL=https://sentinelx.example.com
AUTH_DEBUG=false
LOG_DIR=/var/log/sentinelx-mcp
LOG_FILE=/var/log/sentinelx-mcp/sentinelx-core-mcp.log

Перезапустите и проверьте:

sudo systemctl restart sentinelx-core-mcp
sudo systemctl status sentinelx-core-mcp
sudo journalctl -u sentinelx-core-mcp -n 100 --no-pager

Локальная разработка

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
./run.sh

Значения по умолчанию для локальной разработки:

• Порт MCP: 8099

• URL вышестоящего SentinelX Core: http://127.0.0.1:8092

Ручное дымовое тестирование MCP

Конечная точка MCP не является обычной REST-конечной точкой. Минимальный ручной тест с помощью curl требует:

1. инициализации сессии

2. отправки notifications/initialized

3. вызова tools/list или публичного инструмента, такого как ping

1. Инициализация сессии

curl -i -X POST http://127.0.0.1:8099/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":"init-1",
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{
        "name":"curl",
        "version":"0.1"
      }
    }
  }'

Это должно вернуть 200 OK и заголовок ответа, похожий на:

mcp-session-id: ...

2. Уведомление об инициализации

Замените TU_SESSION_ID на реальное значение, возвращенное сервером:

curl -i -X POST http://127.0.0.1:8099/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: TU_SESSION_ID" \
  -d '{
    "jsonrpc":"2.0",
    "method":"notifications/initialized"
  }'

Это должно вернуть 202 Accepted.

3. Список инструментов

Поскольку ответ доставляется как SSE (event: message + data: ...), удалите префикс data: перед передачей в jq:

curl -s -X POST http://127.0.0.1:8099/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: TU_SESSION_ID" \
  -d '{
    "jsonrpc":"2.0",
    "id":"tools-1",
    "method":"tools/list",
    "params":{}
  }' | sed -n 's/^data: //p' | jq

4. Вызов публичного инструмента ping

curl -s -X POST http://127.0.0.1:8099/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: TU_SESSION_ID" \
  -d '{
    "jsonrpc":"2.0",
    "id":"call-1",
    "method":"tools/call",
    "params":{
      "name":"ping",
      "arguments":{}
    }
  }' | sed -n 's/^data: //p' | jq

Что это проверяет

Эти ручные тесты подтверждают, что:

• MCP-сервер прослушивает порт

• инициализация сессии MCP работает

• формирование протокола корректно

• сервер правильно предоставляет инструменты

• как минимум один вызов публичного инструмента работает от начала до конца

Важное примечание по аутентификации

Для защищенных инструментов MCP по-прежнему требуется реальный токен доступа OAuth/OIDC, принимаемый уровнем MCP.

Внутренний токен SentinelX Core не является тем же самым, что и внешний токен доступа MCP.

Установленные пути

• код: /opt/sentinelx-core-mcp

• файл окружения: /etc/sentinelx-core-mcp/sentinelx-core-mcp.env

• логи: /var/log/sentinelx-mcp

• служба: sentinelx-core-mcp.service

Конфигурация

Пример установленного файла окружения:

MCP_PORT=8098
MCP_TOKEN=
SENTINELX_URL=http://127.0.0.1:8091
SENTINELX_TOKEN=changeme
OIDC_ISSUER=https://auth.example.com/realms/sentinelx
OIDC_JWKS_URI=https://auth.example.com/realms/sentinelx/protocol/openid-connect/certs
OIDC_EXPECTED_AUDIENCE=
RESOURCE_URL=https://sentinelx.example.com
AUTH_DEBUG=false
LOG_DIR=/var/log/sentinelx-mcp
LOG_FILE=/var/log/sentinelx-mcp/sentinelx-core-mcp.log

Примечания по аутентификации

• защищенные инструменты требуют токены носителя (bearer tokens)

• токены проверяются по настроенной конечной точке JWKS

• вышестоящий SentinelX Core по-прежнему применяет свой собственный внутренний токен носителя и списки разрешенных адресов

• Keycloak — рекомендуемый и протестированный вариант, но это не единственный допустимый выбор

• любой совместимый OIDC-провайдер должен работать, если он предоставляет действительный эмитент и конечную точку JWKS

Модель аутентификации

SentinelX Core MCP разработан для токенов носителя OIDC/OAuth на уровне MCP.

Это означает, что в типичном развертывании есть два разных уровня аутентификации:

1. Внешняя аутентификация MCP

   • проверяется sentinelx-core-mcp

   • основана на OIDC_ISSUER, OIDC_JWKS_URI и опциональном OIDC_EXPECTED_AUDIENCE

   • предназначена для MCP-клиентов, таких как ChatGPT или другой потребитель MCP

2. Внутренняя аутентификация SentinelX Core

   • проверяется sentinelx-core

   • основана на SENTINELX_TOKEN

   • используется только мостом MCP при пересылке запросов выше

Рекомендация

Для развертываний, близких к промышленным, используйте реального OIDC-провайдера.

Keycloak является хорошей эталонной реализацией, так как он хорошо изучен и был исходным эталоном, использованным для этого проекта. Однако репозиторий должен оставаться переносимым, поэтому документация рассматривает Keycloak как пример, а не как жесткую зависимость.

С чего начать

• для общего обзора используйте этот README

• для конкретного пошагового руководства по Keycloak см. docs/keycloak-example.md

Устранение неполадок

MCP запускается, но инструменты не работают

Проверьте:

• SENTINELX_URL указывает на запущенный SentinelX Core

• SENTINELX_TOKEN совпадает с вышестоящим ядром

• эмитент OIDC и URI JWKS верны

• токен имеет области действия (scopes), ожидаемые уровнем MCP

Проверьте вышестоящее ядро напрямую

curl -s -H "Authorization: Bearer changeme" http://127.0.0.1:TU_PUERTO_CORE/state | jq

Примечания по безопасности

• держите службу MCP привязанной соответствующим образом для вашего развертывания

• по возможности отдавайте предпочтение локальной привязке с явным внешним уровнем (fronting layer)

• используйте выделенный OIDC-клиент и минимальные области действия (scopes)

• регулярно обновляйте учетные данные и просматривайте логи