igrid-sce-mcp-tool v4 — Read / Write / Admin

Capa de integración MCP en Node.js/JavaScript para las API REST existentes de iGrid-Prometheus. El backend de iGrid y la división existente de ocho herramientas no cambian; esta versión añade autorización basada en roles de SAP BTP XSUAA a nivel de herramienta MCP.

Modelo de autorización

El proyecto ahora define tres ámbitos de XSUAA, tres plantillas de roles y tres colecciones de roles predefinidas:

La autorización se verifica dentro del toolHandler común de MCP antes de cualquier solicitud a la API de iGrid descendente. Un usuario sin el ámbito requerido recibe un error de herramienta MCP Forbidden:.

Related MCP server: agent-sudo-mcp

Exactamente 8 herramientas MCP

Grupo Bearer — src/tools/bearer-tools.js

1. igrid_list_domains → GET /api/hub/datasets → Read/Admin

2. igrid_get_template → GET /api/hub/template/:domain → Read/Admin

3. igrid_run_agent → POST /api/ai/run → Write/Admin

4. igrid_propose_action → POST /api/ai/action/propose → Write/Admin

5. igrid_decide_action → POST /api/ai/action/decide → Write/Admin

6. igrid_metrics → GET /api/ai/metrics → Read/Admin

Grupo x-api-key — src/tools/api-key-tools.js

7. igrid_ingest_csv → POST /api/ingest/:domain → Write/Admin

8. igrid_export_csv → GET /api/export/:domain → Read/Admin

igrid_propose_action está clasificada intencionalmente como Write porque la regla de autorización solicitada se basa en la operación HTTP real y esta herramienta utiliza POST.

No se expone ninguna herramienta MCP igrid_health. /healthz sigue siendo solo el endpoint de salud de la aplicación.

El comportamiento existente de iGrid descendente no cambia

• Seis herramientas continúan usando la sesión Bearer/servicio de iGrid.

• igrid_ingest_csv y igrid_export_csv continúan usando el canal x-api-key de iGrid.

• No se introduce ningún servicio Destination o Connectivity.

• No se codifican credenciales ni secretos.

Archivos importantes

xs-security.json                 XSUAA scopes, role templates, role collections
src/auth/xsuaa.js               XSUAA authentication + OAuth metadata
src/auth/authorization.js       Read/Write/Admin authorization checks
src/context/auth-context.js     Per-request auth context propagation
src/tools/response.js           Common MCP tool-level enforcement
src/tools/bearer-tools.js       6 Bearer tools and permission mapping
src/tools/api-key-tools.js      2 x-api-key tools and permission mapping

Entorno

IGRID_BASE_URL=https://igrid-prometheus.azurewebsites.net
IGRID_API_KEY=<IGRID_API_KEY>
IGRID_BEARER_TOKEN=<optional pre-issued iGrid Bearer>
IGRID_SERVICE_EMAIL=<optional approved iGrid service email>
IGRID_SERVICE_PASSWORD=<optional approved iGrid service password>
IGRID_MFA_CODE=<optional MFA code>
IGRID_MFA_BODY_JSON=<approved MFA JSON body using {{code}}>
IGRID_REQUEST_TIMEOUT_MS=30000

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080
MCP_PATH=/mcp

# Local stdio / local HTTP test authorization only.
# Ignored for a hosted request authenticated through XSUAA.
MCP_LOCAL_ROLE=Admin
MCP_HTTP_AUTH_TOKEN=

Para las herramientas Bearer, se prefiere un IGRID_BEARER_TOKEN emitido previamente. Si no está presente, el gestor de tokens existente puede usar el contrato de inicio de sesión/MFA de iGrid aprobado cuando se proporcione la configuración MFA requerida.

Compilación

npm install
npm run check
npm run security:check
npm test
npx mbt build -t mta_archives

Despliegue en BTP

cf login
cf target -o <ORG> -s <SPACE>
cf deploy mta_archives/igrid-sce-mcp-tool_4.0.0.mtar -f

Establecer los secretos de iGrid después del despliegue:

cf set-env igrid-sce-mcp-tool IGRID_API_KEY '<IGRID_API_KEY>'
cf set-env igrid-sce-mcp-tool IGRID_BEARER_TOKEN '<IGRID_BEARER_TOKEN>'
cf restart igrid-sce-mcp-tool

O, al usar el flujo de inicio de sesión/MFA de servicio aprobado:

cf set-env igrid-sce-mcp-tool IGRID_SERVICE_EMAIL '<SERVICE_EMAIL>'
cf set-env igrid-sce-mcp-tool IGRID_SERVICE_PASSWORD '<SERVICE_PASSWORD>'
cf set-env igrid-sce-mcp-tool IGRID_MFA_BODY_JSON '<APPROVED_JSON_WITH_{{code}}>'
cf restart igrid-sce-mcp-tool

Asignación de roles XSUAA

El despliegue crea/actualiza la instancia de servicio XSUAA igrid-sce-mcp-tool-xsuaa a partir de xs-security.json.

Después del despliegue, en la subcuenta de SAP BTP:

1. Abra Seguridad → Colecciones de roles.

2. Confirme que existen las colecciones predefinidas iGrid-MCP-Read, iGrid-MCP-Write y iGrid-MCP-Admin.

3. Asigne iGrid-MCP-Read a usuarios de solo lectura.

4. Asigne iGrid-MCP-Write a usuarios de solo escritura.

5. Asigne iGrid-MCP-Admin solo a usuarios que necesiten tanto herramientas MCP GET como POST.

6. Vuelva a autenticar el cliente MCP para que su nuevo token contenga los ámbitos asignados.

Si el usuario solo tiene Read, las herramientas POST fallan en la capa MCP. Si el usuario solo tiene Write, las herramientas GET fallan. Admin puede invocar las ocho herramientas.

OAuth / MCP remoto de Claude

Use el endpoint desplegado:

https://<BTP_ROUTE>/mcp

Los metadatos de descubrimiento OAuth ahora anuncian los ámbitos XSUAA read, write y admin. Para la aplicación de roles específicos de usuario, use un flujo OAuth que produzca un token de usuario, normalmente código de autorización, para que las colecciones de roles BTP del usuario estén representadas en el token.

Una clave de servicio aún puede proporcionar credenciales de cliente OAuth XSUAA, pero un token client_credentials es una identidad de cliente técnico y no debe tratarse como si hubiera heredado la colección de roles de un usuario humano.

stdio local

El stdio local no tiene un JWT de usuario de BTP, por lo que el comportamiento de roles se simula con MCP_LOCAL_ROLE. El valor predeterminado es Admin para preservar el comportamiento local anterior.

Prueba local de solo lectura:

MCP_LOCAL_ROLE=Read npm run start:stdio

Prueba local de solo escritura:

MCP_LOCAL_ROLE=Write npm run start:stdio

Prueba local completa:

MCP_LOCAL_ROLE=Admin npm run start:stdio

Ejemplo de Claude Desktop/Code:

{
  "mcpServers": {
    "igrid-sce-mcp-tool": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/igrid-sce-mcp-tool/src/server.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MCP_LOCAL_ROLE": "Read",
        "IGRID_BASE_URL": "https://igrid-prometheus.azurewebsites.net",
        "IGRID_API_KEY": "<IGRID_API_KEY>",
        "IGRID_BEARER_TOKEN": "<IGRID_BEARER_TOKEN>"
      }
    }
  }
}

Prueba de aceptación de roles

Use tres usuarios (o tres asignaciones de usuario-rol) y obtenga un token nuevo después de cada asignación.

Usuario Read

Éxito esperado:

igrid_list_domains
igrid_get_template
igrid_metrics
igrid_export_csv

Se espera Forbidden::

igrid_run_agent
igrid_propose_action
igrid_decide_action
igrid_ingest_csv

Usuario Write

Éxito esperado:

igrid_run_agent
igrid_propose_action
igrid_decide_action
igrid_ingest_csv

Se espera Forbidden::

igrid_list_domains
igrid_get_template
igrid_metrics
igrid_export_csv

Usuario Admin

Las ocho herramientas deberían pasar la verificación de roles MCP. La autenticación/autorización de iGrid descendente y la validación de solicitudes aún se aplican.

Notas de seguridad

• La verificación de permisos ocurre antes de la invocación de la API de iGrid.

• XSUAA controla los permisos MCP entrantes; iGrid sigue siendo la autoridad para las credenciales descendentes y la autorización empresarial.

• Nunca coloque la clave API de iGrid, la contraseña de iGrid, el token Bearer, el secreto de cliente XSUAA o la clave de servicio en el control de código fuente.

• Consulte README-SECURITY.md para conocer el modelo de seguridad conciso.