SentinelX Core MCP

Мост MCP/OAuth для SentinelX Core. Предоставляет ваш серверный агент в качестве инструментов MCP с проверкой токенов OIDC.

SentinelX Core MCP располагается между MCP-клиентами (Claude, ChatGPT, Cursor или любым другим агентом, совместимым с MCP) и запущенным экземпляром SentinelX Core. Он проверяет входящие токены OAuth Bearer через конечную точку JWKS, а затем перенаправляет вызовы инструментов к вышестоящему агенту.

Архитектура

Claude / ChatGPT / Cursor / any MCP client
        │
        │  MCP  +  OAuth Bearer token
        ▼
  sentinelx-core-mcp   (public, port 8098)
        │  validates token via OIDC/JWKS
        │  HTTP  +  internal Bearer token
        ▼
  sentinelx-core        (local only, port 8091)
        │
        └─ command allowlist, structured editing, uploads, services

Два отдельных уровня аутентификации:

Related MCP server: mcp_sdk_eyra_accelerator_v19

Предоставляемые инструменты MCP

Требования

• Запущенный экземпляр SentinelX Core

• OIDC-совместимый провайдер идентификации (Keycloak, Auth0, Authentik, Zitadel или любой провайдер с конечной точкой JWKS)

• Python 3.11+

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

Установка на сервер

git clone https://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=your_internal_agent_token

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

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

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

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

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

Локальные значения по умолчанию:

• Порт MCP: 8099

• Вышестоящий SentinelX Core: http://127.0.0.1:8092

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

Подключение обратного прокси-сервера

Конечная точка MCP по адресу /mcp должна быть доступна через HTTPS. Пример конфигурации Nginx:

server {
    listen 443 ssl http2;
    server_name sentinelx.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location = /mcp {
        proxy_pass http://127.0.0.1:8098/mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Authorization $http_authorization;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_read_timeout 3600s;
        add_header Cache-Control "no-cache";
    }
}

Подключение к Claude

Добавьте MCP-сервер в настройках Claude:

https://sentinelx.example.com/mcp

Claude запросит вход через OAuth при первом использовании. После авторизации он получит доступ ко всем инструментам, которые разрешены областями (scopes) вашего токена.

Подключение к ChatGPT

Зарегистрируйте URL MCP-сервера как GPT Action или в конфигурации коннектора ChatGPT. Поток OAuth работает с любым OIDC-провайдером, поддерживающим поток Authorization Code.

Дымовое тестирование MCP (curl)

Конечная точка MCP использует JSON-RPC поверх HTTP. Минимальная сессия:

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

SESSION=$(curl -si -X POST https://sentinelx.example.com/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":"1","method":"initialize",
    "params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}
  }' | grep -i mcp-session-id | awk '{print $2}' | tr -d '\r')

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

curl -s -X POST https://sentinelx.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

3. Вызов ping (публичный)

curl -s -X POST https://sentinelx.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"ping","arguments":{}}}' \
  | sed -n 's/^data: //p' | jq

4. Вызов защищенного инструмента

curl -s -X POST https://sentinelx.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION" \
  -H "Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN" \
  -d '{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"sentinel_exec","arguments":{"cmd":"uptime"}}}' \
  | sed -n 's/^data: //p' | jq

Настройка провайдера идентификации

Подходит любой OIDC-совместимый провайдер: Keycloak, Auth0, Authentik, Zitadel или ваш собственный. Вам потребуется:

1. Клиент, настроенный для потока Authorization Code (интерактивный) или Client Credentials (машина-машина)

2. Пользовательские области (scopes), соответствующие инструментам, которые вы хотите предоставить (sentinelx:exec, sentinelx:edit и т.д.)

3. JWKS URI вашего провайдера

4. Для Claude и ChatGPT: правильные redirect URI, зарегистрированные в клиенте

Установите их в файле окружения:

OIDC_ISSUER=https://your-provider.example.com/realms/your-realm
OIDC_JWKS_URI=https://your-provider.example.com/realms/your-realm/protocol/openid-connect/certs
OIDC_EXPECTED_AUDIENCE=   # set to your client ID, or leave empty to skip audience validation

Об OIDC_EXPECTED_AUDIENCE

• Установите ваш client ID, если провайдер включает его в утверждение aud (обычно для конфиденциальных клиентов)

• Оставьте пустым, если не уверены — сервер пропустит проверку аудитории

• Если токены отклоняются, декодируйте токен (echo $TOKEN | cut -d. -f2 | base64 -d | jq) и проверьте утверждение aud

Подключение Claude

Добавьте MCP-сервер в настройках Claude:

https://sentinelx.example.com/mcp

Claude перенаправит вас на провайдер идентификации при первом использовании. Убедитесь, что:

• Redirect URI https://claude.ai/api/mcp/auth_callback зарегистрирован в вашем OIDC-клиенте

• Ваш сервер предоставляет /.well-known/oauth-protected-resource с правильным значением authorization_servers

Подключение ChatGPT

Зарегистрируйте URL MCP как GPT Action. Добавьте https://chatgpt.com/aip/g-*/oauth/callback в redirect URI вашего клиента.

Полное пошаговое руководство с Keycloak — включая получение токена, настройку Claude, дымовые тесты и устранение неполадок — см. в docs/keycloak-example.md.

Не используете Keycloak? См. docs/oidc-alternatives.md для руководств по быстрому старту с Authentik, Zitadel и Zitadel Cloud.

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

Инструменты завершаются ошибкой Missing Authorization header MCP-клиент не отправляет токен OAuth. Убедитесь, что процесс авторизации завершен успешно.

Invalid access token Проверьте, что OIDC_ISSUER и OIDC_JWKS_URI точно соответствуют вашему провайдеру идентификации. Временно включите AUTH_DEBUG=true, чтобы увидеть детали проверки токена в логах.

Missing required scope Токен не включает область (scope), требуемую для этого инструмента. Добавьте область в конфигурацию OIDC-клиента и повторно авторизуйтесь.

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

MCP запускается, но не может связаться с SentinelX Core Проверьте, что SENTINELX_URL указывает на запущенный экземпляр core, а SENTINELX_TOKEN совпадает с SENTINEL_TOKEN в core.

Заметки по безопасности

• Держите службу MCP за HTTPS и обратным прокси-сервером

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

• Периодически обновляйте SENTINELX_TOKEN и учетные данные OIDC-клиента

• Регулярно просматривайте лог аудита выполнения (/var/log/sentinelx/exec.log)

• AUTH_DEBUG=true записывает утверждения токена в логи — отключайте в продакшене

Связанные проекты

• sentinelx-core — Базовый HTTP-агент: выполнение команд, структурированное редактирование, загрузки и управление службами.

Лицензия

MIT