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

Node.js/JavaScript MCP integration layer for the existing iGrid-Prometheus REST APIs. The iGrid backend and the existing eight-tool split are unchanged; this version adds SAP BTP XSUAA role-based authorization at the MCP tool level.

Authorization model

The project now defines three XSUAA scopes, three role templates, and three predefined role collections:

Role collection	Role template	Scopes	Allowed MCP operations
iGrid-MCP-Read	Read	$XSAPPNAME.read	GET/read tools only
iGrid-MCP-Write	Write	$XSAPPNAME.write	POST/write tools only
iGrid-MCP-Admin	Admin	$XSAPPNAME.read, $XSAPPNAME.write, $XSAPPNAME.admin	All eight tools

Authorization is checked inside the common MCP toolHandler before any downstream iGrid API request. A user without the required scope receives a Forbidden: MCP tool error.

Exactly 8 MCP tools

Bearer group — 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

x-api-key group — 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 is intentionally classified as Write because the requested authorization rule is based on the actual HTTP operation and this tool uses POST.

No igrid_health MCP tool is exposed. /healthz remains only the application health endpoint.

Existing downstream iGrid behavior is unchanged

• Six tools continue to use the iGrid Bearer/service session.
• igrid_ingest_csv and igrid_export_csv continue to use the iGrid x-api-key channel.
• No Destination or Connectivity service is introduced.
• No credentials or secrets are hard-coded.

Important files

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

Environment

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=

For Bearer tools, a pre-issued IGRID_BEARER_TOKEN is preferred. If absent, the existing token manager can use the approved iGrid login/MFA contract when the required MFA configuration is supplied.

Build

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

BTP deployment

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

Set iGrid secrets after deployment:

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

Or, when using the approved service login/MFA flow:

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

XSUAA role assignment

Deployment creates/updates the XSUAA service instance igrid-sce-mcp-tool-xsuaa from xs-security.json.

After deployment, in the SAP BTP subaccount:

1. Open Security → Role Collections.
2. Confirm the predefined collections iGrid-MCP-Read, iGrid-MCP-Write, and iGrid-MCP-Admin exist.
3. Assign iGrid-MCP-Read to read-only users.
4. Assign iGrid-MCP-Write to write-only users.
5. Assign iGrid-MCP-Admin only to users who need both GET and POST MCP tools.
6. Re-authenticate the MCP client so its new token contains the assigned scopes.

If the user has only Read, POST tools fail at the MCP layer. If the user has only Write, GET tools fail. Admin can invoke all eight tools.

OAuth / Claude remote MCP

Use the deployed endpoint:

https://<BTP_ROUTE>/mcp

The OAuth discovery metadata now advertises the XSUAA read, write, and admin scopes. For user-specific role enforcement, use an OAuth flow that produces a user token, normally authorization code, so the user's BTP role collections are represented in the token.

A service key can still provide XSUAA OAuth client credentials, but a client_credentials token is a technical-client identity and should not be treated as if it inherited a human user's role collection.

Local stdio

Local stdio does not have a BTP user JWT, so role behavior is simulated with MCP_LOCAL_ROLE. Default is Admin to preserve the previous local behavior.

Read-only local test:

MCP_LOCAL_ROLE=Read npm run start:stdio

Write-only local test:

MCP_LOCAL_ROLE=Write npm run start:stdio

Full local test:

MCP_LOCAL_ROLE=Admin npm run start:stdio

Claude Desktop/Code example:

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

Role acceptance test

Use three users (or three user-role assignments) and obtain a fresh token after each assignment.

Read user

Expected success:

igrid_list_domains
igrid_get_template
igrid_metrics
igrid_export_csv

Expected Forbidden::

igrid_run_agent
igrid_propose_action
igrid_decide_action
igrid_ingest_csv

Write user

Expected success:

igrid_run_agent
igrid_propose_action
igrid_decide_action
igrid_ingest_csv

Expected Forbidden::

igrid_list_domains
igrid_get_template
igrid_metrics
igrid_export_csv

Admin user

All eight tools should pass the MCP role check. Downstream iGrid authentication/authorization and request validation still apply.

Security notes

• The permission check happens before the iGrid API invocation.
• XSUAA controls inbound MCP permissions; iGrid remains authoritative for downstream credentials and business authorization.
• Never put the iGrid API key, iGrid password, Bearer token, XSUAA client secret, or service key in source control.
• See README-SECURITY.md for the concise security model.