SentinelX Core MCP

Puente MCP/OAuth para SentinelX Core. Expone tu agente de servidor como herramientas MCP con validación de tokens OIDC.

SentinelX Core MCP se sitúa entre los clientes MCP (Claude, ChatGPT, Cursor o cualquier agente compatible con MCP) y una instancia de SentinelX Core en ejecución. Valida los tokens OAuth Bearer entrantes contra un endpoint JWKS y luego reenvía las llamadas a las herramientas al agente upstream.

Arquitectura

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

Dos capas de autenticación separadas:

Related MCP server: mcp_sdk_eyra_accelerator_v19

Herramientas MCP expuestas

Requisitos

• Una instancia de SentinelX Core en ejecución

• Un proveedor de identidad compatible con OIDC (Keycloak, Auth0, Authentik, Zitadel o cualquier proveedor con un endpoint JWKS)

• Python 3.11+

Inicio rápido

Instalar en un servidor

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

Luego configura:

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

Mínimo requerido:

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

Reinicia y verifica:

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

Desarrollo local

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

Valores predeterminados locales:

• Puerto MCP: 8099

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

Rutas instaladas

Conectar un proxy inverso

El endpoint MCP en /mcp debe exponerse a través de HTTPS. Ejemplo de configuración de 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";
    }
}

Conectar a Claude

Añade el servidor MCP en la configuración de Claude:

https://sentinelx.example.com/mcp

Claude solicitará el inicio de sesión OAuth en el primer uso. Tras la autorización, tendrá acceso a todas las herramientas que permitan los alcances (scopes) de tu token.

Conectar a ChatGPT

Registra la URL del servidor MCP como una Acción GPT o en la configuración de tu conector de ChatGPT. El flujo OAuth funciona con cualquier proveedor OIDC que admita el flujo de Código de Autorización.

Prueba de humo MCP (curl)

El endpoint MCP utiliza JSON-RPC sobre HTTP. Una sesión mínima:

1. Inicializar

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. Notificar inicializado

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. Llamar a ping (público)

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. Llamar a una herramienta protegida

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

Configuración del proveedor de identidad

Cualquier proveedor compatible con OIDC funciona: Keycloak, Auth0, Authentik, Zitadel o el tuyo propio. Necesitas:

1. Un cliente configurado para el flujo de Código de Autorización (interactivo) o Credenciales de Cliente (máquina a máquina)

2. Alcances personalizados que coincidan con las herramientas que deseas exponer (sentinelx:exec, sentinelx:edit, etc.)

3. El URI JWKS de tu proveedor

4. Para Claude y ChatGPT: los URIs de redirección correctos registrados en el cliente

Configúralos en el archivo de entorno:

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

Acerca de OIDC_EXPECTED_AUDIENCE

• Configúralo con tu ID de cliente si tu proveedor lo incluye en la reclamación aud (común con clientes confidenciales)

• Déjalo vacío si no estás seguro: el servidor omitirá la validación de audiencia

• Si los tokens son rechazados, decodifica el token (echo $TOKEN | cut -d. -f2 | base64 -d | jq) y verifica la reclamación aud

Conectar Claude

Añade el servidor MCP en la configuración de Claude:

https://sentinelx.example.com/mcp

Claude redirigirá a tu proveedor de identidad en el primer uso. Asegúrate de que:

• El URI de redirección https://claude.ai/api/mcp/auth_callback esté registrado en tu cliente OIDC

• Tu servidor exponga /.well-known/oauth-protected-resource con el valor correcto de authorization_servers

Conectar ChatGPT

Registra la URL de MCP como una Acción GPT. Añade https://chatgpt.com/aip/g-*/oauth/callback a los URIs de redirección de tu cliente.

Para un tutorial completo de extremo a extremo con Keycloak —incluyendo la obtención de tokens, configuración de Claude, pruebas de humo y solución de problemas—, consulta docs/keycloak-example.md.

¿No usas Keycloak? Consulta docs/oidc-alternatives.md para guías de inicio rápido con Authentik, Zitadel y Zitadel Cloud.

Solución de problemas

Las herramientas fallan con Missing Authorization header El cliente MCP no está enviando el token OAuth. Verifica que el flujo de autorización se haya completado correctamente.

Invalid access token Verifica que OIDC_ISSUER y OIDC_JWKS_URI coincidan exactamente con tu proveedor de identidad. Habilita AUTH_DEBUG=true temporalmente para ver los detalles de validación del token en los registros.

Missing required scope El token no incluye el alcance requerido por esa herramienta. Añade el alcance a la configuración de tu cliente OIDC y vuelve a autorizar.

ping funciona pero todas las demás herramientas fallan Generalmente es un problema de autenticación. ping es público; cualquier otra herramienta requiere un token válido con el alcance correcto.

MCP inicia pero no puede alcanzar SentinelX Core Verifica que SENTINELX_URL apunte a una instancia de core en ejecución y que SENTINELX_TOKEN coincida con el SENTINEL_TOKEN del core.

Notas de seguridad

• Mantén el servicio MCP detrás de HTTPS y un proxy inverso

• Usa un cliente OIDC dedicado solo con los alcances que necesites

• Rota SENTINELX_TOKEN y las credenciales del cliente OIDC periódicamente

• Revisa el registro de auditoría de ejecución (/var/log/sentinelx/exec.log) regularmente

• AUTH_DEBUG=true registra las reclamaciones del token: desactívalo en producción

Relacionado

• sentinelx-core — El agente HTTP subyacente: ejecución de comandos, edición estructurada, subidas y gestión de servicios.

Licencia

MIT