# 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

```text
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

```text
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

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

## BTP deployment

```bash
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:

```bash
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:

```bash
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:

```text
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:

```bash
MCP_LOCAL_ROLE=Read npm run start:stdio
```

Write-only local test:

```bash
MCP_LOCAL_ROLE=Write npm run start:stdio
```

Full local test:

```bash
MCP_LOCAL_ROLE=Admin npm run start:stdio
```

Claude Desktop/Code example:

```json
{
  "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:

```text
igrid_list_domains
igrid_get_template
igrid_metrics
igrid_export_csv
```

Expected `Forbidden:`:

```text
igrid_run_agent
igrid_propose_action
igrid_decide_action
igrid_ingest_csv
```

### Write user

Expected success:

```text
igrid_run_agent
igrid_propose_action
igrid_decide_action
igrid_ingest_csv
```

Expected `Forbidden:`:

```text
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.