SentinelX Core MCP

MCP/OAuth-Brücke für SentinelX Core. Stellt Ihren Server-Agent als MCP-Tools mit OIDC-Token-Validierung bereit.

SentinelX Core MCP fungiert als Vermittler zwischen MCP-Clients (Claude, ChatGPT, Cursor oder jedem anderen MCP-kompatiblen Agenten) und einer laufenden SentinelX Core-Instanz. Er validiert eingehende OAuth-Bearer-Token gegen einen JWKS-Endpunkt und leitet anschließend Tool-Aufrufe an den Upstream-Agenten weiter.

Architektur

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

Zwei separate Authentifizierungsebenen:

Related MCP server: mcp_sdk_eyra_accelerator_v19

Verfügbare MCP-Tools

Anforderungen

• Eine laufende SentinelX Core-Instanz

• Ein OIDC-kompatibler Identitätsanbieter (Keycloak, Auth0, Authentik, Zitadel oder jeder Anbieter mit einem JWKS-Endpunkt)

• Python 3.11+

Schnellstart

Installation auf einem Server

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

Dann konfigurieren:

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

Mindestanforderungen:

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

Neustart und Überprüfung:

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

Lokale Entwicklung

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

Lokale Standardwerte:

• MCP-Port: 8099

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

Installierte Pfade

Verbindung mit einem Reverse Proxy

Der MCP-Endpunkt unter /mcp sollte über HTTPS bereitgestellt werden. Beispiel für eine Nginx-Konfiguration:

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

Verbindung mit Claude

Fügen Sie den MCP-Server in den Einstellungen von Claude hinzu:

https://sentinelx.example.com/mcp

Claude wird bei der ersten Verwendung zur OAuth-Anmeldung auffordern. Nach der Autorisierung hat es Zugriff auf alle Tools, die durch die Scopes Ihres Tokens erlaubt sind.

Verbindung mit ChatGPT

Registrieren Sie die MCP-Server-URL als GPT-Aktion oder in Ihrer ChatGPT-Connector-Konfiguration. Der OAuth-Flow funktioniert mit jedem OIDC-Anbieter, der den Authorization Code Flow unterstützt.

MCP-Smoke-Test (curl)

Der MCP-Endpunkt verwendet JSON-RPC über HTTP. Eine minimale Sitzung:

1. Initialisierung

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. Benachrichtigung über Initialisierung

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. Aufruf von ping (öffentlich)

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. Aufruf eines geschützten Tools

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

Einrichtung des Identitätsanbieters

Jeder OIDC-kompatible Anbieter funktioniert: Keycloak, Auth0, Authentik, Zitadel oder Ihr eigener. Sie benötigen:

1. Einen Client, der für den Authorization Code Flow (interaktiv) oder Client Credentials (Maschine-zu-Maschine) konfiguriert ist

2. Benutzerdefinierte Scopes, die den Tools entsprechen, die Sie bereitstellen möchten (sentinelx:exec, sentinelx:edit usw.)

3. Den JWKS-URI Ihres Anbieters

4. Für Claude und ChatGPT: die korrekten Redirect-URIs, die im Client registriert sind

Setzen Sie diese in der Umgebungsdatei:

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

Über OIDC_EXPECTED_AUDIENCE

• Setzen Sie dies auf Ihre Client-ID, falls Ihr Anbieter diese im aud-Claim enthält (üblich bei vertraulichen Clients)

• Lassen Sie es leer, wenn Sie unsicher sind — der Server überspringt dann die Audience-Validierung

• Wenn Token abgelehnt werden, dekodieren Sie das Token (echo $TOKEN | cut -d. -f2 | base64 -d | jq) und überprüfen Sie den aud-Claim

Verbindung mit Claude

Fügen Sie den MCP-Server in den Einstellungen von Claude hinzu:

https://sentinelx.example.com/mcp

Claude leitet Sie bei der ersten Verwendung zu Ihrem Identitätsanbieter weiter. Stellen Sie sicher, dass:

• Die Redirect-URI https://claude.ai/api/mcp/auth_callback in Ihrem OIDC-Client registriert ist

• Ihr Server /.well-known/oauth-protected-resource mit dem korrekten authorization_servers-Wert bereitstellt

Verbindung mit ChatGPT

Registrieren Sie die MCP-URL als GPT-Aktion. Fügen Sie https://chatgpt.com/aip/g-*/oauth/callback zu den Redirect-URIs Ihres Clients hinzu.

Für eine vollständige Schritt-für-Schritt-Anleitung mit Keycloak — einschließlich Token-Beschaffung, Claude-Einrichtung, Smoke-Tests und Fehlerbehebung — siehe docs/keycloak-example.md.

Sie verwenden kein Keycloak? Siehe docs/oidc-alternatives.md für Schnellstartanleitungen mit Authentik, Zitadel und Zitadel Cloud.

Fehlerbehebung

Tools schlagen mit Missing Authorization header fehl Der MCP-Client sendet das OAuth-Token nicht. Überprüfen Sie, ob der Autorisierungs-Flow erfolgreich abgeschlossen wurde.

Invalid access token Überprüfen Sie, ob OIDC_ISSUER und OIDC_JWKS_URI exakt mit Ihrem Identitätsanbieter übereinstimmen. Aktivieren Sie vorübergehend AUTH_DEBUG=true, um Details zur Token-Validierung in den Protokollen zu sehen.

Missing required scope Das Token enthält nicht den für dieses Tool erforderlichen Scope. Fügen Sie den Scope Ihrer OIDC-Client-Konfiguration hinzu und autorisieren Sie erneut.

ping funktioniert, aber alle anderen Tools schlagen fehl Normalerweise ein Authentifizierungsproblem. ping ist öffentlich; jedes andere Tool erfordert ein gültiges Token mit dem richtigen Scope.

MCP startet, kann aber SentinelX Core nicht erreichen Überprüfen Sie, ob SENTINELX_URL auf eine laufende Core-Instanz zeigt und SENTINELX_TOKEN mit dem SENTINEL_TOKEN des Cores übereinstimmt.

Sicherheitshinweise

• Betreiben Sie den MCP-Dienst hinter HTTPS und einem Reverse Proxy

• Verwenden Sie einen dedizierten OIDC-Client mit nur den benötigten Scopes

• Rotieren Sie SENTINELX_TOKEN und OIDC-Client-Anmeldedaten regelmäßig

• Überprüfen Sie regelmäßig das Exec-Audit-Protokoll (/var/log/sentinelx/exec.log)

• AUTH_DEBUG=true protokolliert Token-Claims — in der Produktion deaktivieren

Verwandtes

• sentinelx-core — Der zugrunde liegende HTTP-Agent: Befehlsausführung, strukturierte Bearbeitung, Uploads und Dienstverwaltung.

Lizenz

MIT