SentinelX Core MCP

MCP-Server, der Tool-Aufrufe an eine laufende SentinelX Core-Instanz weiterleitet.

Dieses Repository ist die portable MCP/OAuth-Brückenschicht. Es ist dazu gedacht, von sentinelx-core, das den zugrunde liegenden HTTP-Agent bereitstellt, getrennt zu bleiben.

Was es tut

• stellt MCP-Tools bereit, die von SentinelX Core unterstützt werden

• validiert Bearer-Token über OIDC/JWKS

• leitet Tool-Aufrufe an die vorgelagerte SentinelX Core-API weiter

• fügt eine separate Produktgrenze für MCP-Integrationen hinzu

Abhängigkeit von SentinelX Core

Dieses Projekt erfordert eine laufende SentinelX Core-Instanz.

Typische lokale Entwicklungskopplung:

• SentinelX Core: http://127.0.0.1:8092

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

Typische installierte Kopplungsbeispiele:

• SentinelX Core: http://127.0.0.1:8091

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

Dies sind Beispiel-Standardwerte, keine garantierten freien Ports. Überprüfen Sie immer die tatsächlichen Werte, die in /etc/sentinelx/sentinelx.env und /etc/sentinelx-core-mcp/sentinelx-core-mcp.env konfiguriert sind.

Schnellstart

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

Bearbeiten Sie dann:

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

Setzen Sie mindestens:

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

Starten Sie neu und überprüfen Sie:

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

Lokale Entwicklung

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

Standardwerte für die lokale Entwicklung:

• MCP-Port: 8099

• Upstream SentinelX Core URL: http://127.0.0.1:8092

Manueller MCP-Rauchtest

Der MCP-Endpunkt ist kein einfacher REST-Endpunkt. Ein minimaler manueller Test mit curl erfordert:

1. Initialisierung einer Sitzung

2. Senden von notifications/initialized

3. Aufruf von tools/list oder eines öffentlichen Tools wie ping

1. Initialisierung einer Sitzung

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"
      }
    }
  }'

Dies sollte 200 OK und einen Antwort-Header wie folgt zurückgeben:

mcp-session-id: ...

2. Benachrichtigung über Initialisierung

Ersetzen Sie TU_SESSION_ID durch den tatsächlichen Wert, der vom Server zurückgegeben wurde:

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"
  }'

Dies sollte 202 Accepted zurückgeben.

3. Tools auflisten

Da die Antwort als SSE (event: message + data: ...) geliefert wird, entfernen Sie das data:-Präfix, bevor Sie es an jq weiterleiten:

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. Aufruf des öffentlichen ping-Tools

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

Was dies validiert

Diese manuellen Tests validieren, dass:

• der MCP-Server empfangsbereit ist

• die MCP-Sitzungsinitialisierung funktioniert

• das Protokoll-Framing korrekt ist

• der Server Tools korrekt bereitstellt

• mindestens ein öffentlicher Tool-Aufruf von Anfang bis Ende funktioniert

Wichtiger Hinweis zur Authentifizierung

Geschützte MCP-Tools erfordern weiterhin ein echtes OAuth/OIDC-Zugriffstoken, das von der MCP-Schicht akzeptiert wird.

Das interne SentinelX Core-Token ist nicht dasselbe wie das externe MCP-Zugriffstoken.

Installierte Pfade

• Code: /opt/sentinelx-core-mcp

• Umgebungsdatei: /etc/sentinelx-core-mcp/sentinelx-core-mcp.env

• Protokolle: /var/log/sentinelx-mcp

• Dienst: sentinelx-core-mcp.service

Konfiguration

Installierte Beispiel-Umgebungsdatei:

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

Hinweise zur Authentifizierung

• geschützte Tools erfordern Bearer-Token

• Token werden gegen den konfigurierten JWKS-Endpunkt validiert

• der vorgelagerte SentinelX Core erzwingt weiterhin sein eigenes internes Bearer-Token und Zulassungslisten

• Keycloak ist eine empfohlene und getestete Option, aber nicht die einzige gültige Wahl

• jeder kompatible OIDC-Anbieter sollte funktionieren, sofern er einen gültigen Aussteller und JWKS-Endpunkt bereitstellt

Authentifizierungsmodell

SentinelX Core MCP ist für OIDC/OAuth-Bearer-Token auf der MCP-Schicht konzipiert.

Das bedeutet, dass es in einer typischen Bereitstellung zwei verschiedene Authentifizierungsschichten gibt:

1. Externe MCP-Authentifizierung

   • validiert durch sentinelx-core-mcp

   • basierend auf OIDC_ISSUER, OIDC_JWKS_URI und optional OIDC_EXPECTED_AUDIENCE

   • gedacht für MCP-Clients wie ChatGPT oder andere MCP-Consumer

2. Interne SentinelX Core-Authentifizierung

   • validiert durch sentinelx-core

   • basierend auf SENTINELX_TOKEN

   • wird nur von der MCP-Brücke verwendet, wenn sie Anfragen an den Upstream weiterleitet

Empfehlung

Verwenden Sie für produktionsnahe Bereitstellungen einen echten OIDC-Anbieter.

Keycloak ist eine gute Referenzimplementierung, da sie gut verstanden wird und die ursprüngliche Referenz für dieses Projekt war. Das Repository sollte jedoch portabel bleiben, daher behandelt die Dokumentation Keycloak als Beispiel und nicht als harte Abhängigkeit.

Wo man anfangen sollte

• für einen allgemeinen Überblick verwenden Sie diese README

• für eine konkrete Keycloak-Anleitung siehe docs/keycloak-example.md

Fehlerbehebung

MCP startet, aber Tools schlagen fehl

Überprüfen Sie:

• SENTINELX_URL zeigt auf einen laufenden SentinelX Core

• SENTINELX_TOKEN stimmt mit dem Upstream-Core überein

• OIDC-Aussteller und JWKS-URI sind korrekt

• das Token verfügt über die von der MCP-Schicht erwarteten Scopes

Überprüfen Sie den Upstream-Core direkt

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

Sicherheitshinweise

• halten Sie den MCP-Dienst für Ihre Bereitstellung angemessen gebunden

• bevorzugen Sie nach Möglichkeit eine reine lokale Bindung mit einer expliziten Fronting-Schicht

• verwenden Sie einen dedizierten OIDC-Client und minimale Scopes

• rotieren Sie Anmeldeinformationen und überprüfen Sie regelmäßig die Protokolle