SentinelX Core MCP

Servidor MCP que redirige llamadas a herramientas a una instancia de SentinelX Core en ejecución.

Este repositorio es la capa puente portátil de MCP/OAuth. Está diseñado para permanecer separado de sentinelx-core, que proporciona el agente HTTP subyacente.

Qué hace

• expone herramientas MCP respaldadas por SentinelX Core

• valida tokens de portador (bearer tokens) a través de OIDC/JWKS

• reenvía llamadas a herramientas a la API de SentinelX Core ascendente

• añade un límite de producto independiente para integraciones MCP

Dependencia de SentinelX Core

Este proyecto requiere una instancia de SentinelX Core en ejecución.

Emparejamiento típico para desarrollo local:

• SentinelX Core: http://127.0.0.1:8092

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

Ejemplos típicos de emparejamiento instalado:

• SentinelX Core: http://127.0.0.1:8091

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

Estos son valores predeterminados de ejemplo, no puertos garantizados como libres. Compruebe siempre los valores reales configurados en /etc/sentinelx/sentinelx.env y /etc/sentinelx-core-mcp/sentinelx-core-mcp.env.

Inicio rápido

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

Luego edite:

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

Establezca al menos:

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

Reinicie y verifique:

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

Desarrollo local

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

Valores predeterminados para desarrollo local:

• Puerto MCP: 8099

• URL de SentinelX Core ascendente: http://127.0.0.1:8092

Prueba de humo manual de MCP

El punto final MCP no es un punto final REST simple. Una prueba manual mínima con curl requiere:

1. inicializar una sesión

2. enviar notifications/initialized

3. llamar a tools/list o a una herramienta pública como ping

1. Inicializar una sesión

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

Esto debería devolver 200 OK y una cabecera de respuesta como:

mcp-session-id: ...

2. Notificar inicialización

Reemplace TU_SESSION_ID con el valor real devuelto por el servidor:

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

Esto debería devolver 202 Accepted.

3. Listar herramientas

Debido a que la respuesta se entrega como SSE (event: message + data: ...), elimine el prefijo data: antes de pasarla a 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. Llamar a la herramienta pública 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

Qué valida esto

Estas pruebas manuales validan que:

• el servidor MCP está escuchando

• la inicialización de la sesión MCP funciona

• el marco del protocolo es correcto

• el servidor expone las herramientas correctamente

• al menos una llamada a una herramienta pública funciona de extremo a extremo

Nota importante sobre autenticación

Las herramientas MCP protegidas aún requieren un token de acceso OAuth/OIDC real aceptado por la capa MCP.

El token interno de SentinelX Core no es el mismo que el token de acceso MCP externo.

Rutas instaladas

• código: /opt/sentinelx-core-mcp

• archivo de entorno: /etc/sentinelx-core-mcp/sentinelx-core-mcp.env

• registros: /var/log/sentinelx-mcp

• servicio: sentinelx-core-mcp.service

Configuración

Ejemplo de archivo de entorno instalado:

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

Notas sobre autenticación

• las herramientas protegidas requieren tokens de portador (bearer tokens)

• los tokens se validan contra el punto final JWKS configurado

• el SentinelX Core ascendente sigue aplicando su propio token de portador interno y listas de permitidos

• Keycloak es una opción recomendada y probada, pero no es la única opción válida

• cualquier proveedor OIDC compatible debería funcionar si expone un emisor y un punto final JWKS válidos

Modelo de autenticación

SentinelX Core MCP está diseñado para tokens de portador OIDC/OAuth en la capa MCP.

Esto significa que hay dos capas de autenticación diferentes en una implementación típica:

1. Autenticación MCP externa

   • validada por sentinelx-core-mcp

   • basada en OIDC_ISSUER, OIDC_JWKS_URI y opcionalmente OIDC_EXPECTED_AUDIENCE

   • destinada a clientes MCP como ChatGPT u otro consumidor MCP

2. Autenticación interna de SentinelX Core

   • validada por sentinelx-core

   • basada en SENTINELX_TOKEN

   • utilizada solo por el puente MCP cuando reenvía solicitudes al nivel superior

Recomendación

Para implementaciones de tipo producción, utilice un proveedor OIDC real.

Keycloak es una buena implementación de referencia porque es bien conocida y fue la referencia original utilizada para este proyecto. Sin embargo, el repositorio debe seguir siendo portátil, por lo que la documentación trata a Keycloak como un ejemplo, no como una dependencia estricta.

Por dónde empezar

• para una visión general genérica, utilice este README

• para un tutorial concreto de Keycloak, consulte docs/keycloak-example.md

Solución de problemas

MCP inicia pero las herramientas fallan

Compruebe:

• SENTINELX_URL apunta a un SentinelX Core en ejecución

• SENTINELX_TOKEN coincide con el núcleo ascendente

• el emisor OIDC y el URI JWKS son correctos

• el token tiene los alcances (scopes) esperados por la capa MCP

Compruebe el núcleo ascendente directamente

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

Notas de seguridad

• mantenga el servicio MCP vinculado adecuadamente para su implementación

• prefiera el enlace solo local con una capa frontal explícita cuando sea posible

• utilice un cliente OIDC dedicado y alcances mínimos

• rote las credenciales y revise los registros regularmente