---

name: sap-datasphere-plugin description: > SAP Datasphere plugin for Codex Co-Work (MarioDeFelipe/sap-datasphere-plugin-for-Codex-cowork). Reference for Datasphere spaces, views, and data federation — the MCP/plugin usage layer: connecting via datasphere-mcp, @sap/datasphere-cli operations, consuming views via OData/Open SQL, and monitoring task chains. trigger: keywords: [datasphere plugin, datasphere mcp, datasphere cli, dsphere, spaces list, dbusers, view consumption, odata consumption, task chain, hana cloud federation] intent: Operating SAP Datasphere from Codex via the datasphere-mcp server or @sap/datasphere-cli — listing spaces, querying exposed views, managing database users, and running/monitoring task chains prerequisites:

• SAP Datasphere tenant URL (e.g. https://.us10.hcs.cloud.sap)
• OAuth client created in Datasphere → System → App Integration (Purpose "Interactive Usage")
• DSPHERE_HOST / DSPHERE_USER / DSPHERE_PASSWORD set in .env (consumed by datasphere-mcp)
• Technical user assigned as member of each target space (DW Integrator/Viewer role)
• Node.js 18+ for @sap/datasphere-cli and the MCP server

---

SAP Datasphere Plugin (MCP + CLI Usage Layer)

Operational layer for driving SAP Datasphere from Codex: the datasphere-mcp server (MarioDeFelipe/sap-datasphere-mcp) plus @sap/datasphere-cli. For data-modeling concepts (Data Builder, analytical models, replication flows) use the sibling sap-datasphere skill.

1. Plugin / MCP setup

The repo ships a datasphere-mcp entry in .mcp.json (stdio, node dist/index.js) reading:

# .env — required by datasphere-mcp
DSPHERE_HOST=https://<tenant>.us10.hcs.cloud.sap
DSPHERE_USER=<technical-user-or-oauth-client-id>
DSPHERE_PASSWORD=<password-or-oauth-client-secret>

# Verify the MCP is reachable (probes all 53 MCPs incl. datasphere-mcp)
npm run hc

OAuth prerequisite (one-time, in the Datasphere tenant):

1. System → Administration → App Integration → Add a New OAuth Client
2. Purpose: Interactive Usage (CLI login) — Authorization Grant: Authorization Code
3. Note the Client ID, Client Secret, Authorization URL, Token URL

2. CLI login and space discovery

# Install CLI
npm install -g @sap/datasphere-cli

# Point CLI at the tenant, then login via OAuth client (opens browser consent)
datasphere config host set "https://<tenant>.us10.hcs.cloud.sap"
datasphere login --client-id "<CLIENT_ID>" --client-secret "<CLIENT_SECRET>"

# List all spaces visible to the user
datasphere spaces list

# Read one space definition (members, objects) to a file
datasphere spaces read --space SALES --output sales_space.json

# List database users (Open SQL schema users) of a space
datasphere dbusers list --space SALES

3. Consume a view — OData

The view must have Expose for Consumption = ON in Data Builder (see Pitfall 4).

# Relational consumption endpoint (entity data as OData v4)
curl -H "Authorization: Bearer $TOKEN" \
  "https://<tenant>.us10.hcs.cloud.sap/api/v1/dwc/consumption/relational/SALES/V_SALES_KPI/V_SALES_KPI?\$top=10"

# Analytical consumption (aggregated, for analytical models)
curl -H "Authorization: Bearer $TOKEN" \
  "https://<tenant>.us10.hcs.cloud.sap/api/v1/dwc/consumption/analytical/SALES/AM_SALES/AM_SALES?\$select=Revenue"

4. Consume a view — SQL (Open SQL schema)

Database users unlock direct SQL access on HANA Cloud port 443.

# Create/list the space's database user first (schema name = SPACE#USER)
datasphere dbusers list --space SALES

# Connect with hdbsql (HANA client) and query the exposed view
hdbsql -n "<tenant-hana-host>:443" -e -u "SALES#TECH_USER" -p "<password>" \
  'SELECT TOP 10 * FROM "SALES"."V_SALES_KPI";'

5. Data federation basics

Federation = remote tables over a connection (S/4HANA via ODP/CDS, HANA Cloud via SDA, Azure SQL, BW/4HANA). Queries execute at the source — no copy, always fresh.

Connection (S4HANA_PRD) → Remote Table (federated, default) → View → Expose → OData/SQL
                                    └─ optional: switch to Replicated (snapshot/real-time)

• Check state: Data Integration Monitor → Remote Tables → Federation vs Replicated
• Heavy analytical reads on S/4? Switch the remote table to replicated (see Pitfall 3)
• Model federation details (virtual tables, VDM layers) live in the sap-datasphere skill

6. Task chains — run and monitor

# List task chains / tasks of a space
datasphere tasks list --space SALES

# Run a task chain and watch its status
datasphere tasks chains run --space SALES --object TC_DAILY_LOAD
datasphere tasks list --space SALES --status RUNNING

# UI equivalent: Data Integration Monitor → Task Chains → last run = COMPLETED

Pitfalls

• CLI login fails with invalid_client → Cause: OAuth client created without Purpose "Interactive Usage" (e.g. API Access only). Solution: recreate the OAuth client in App Integration with Purpose = Interactive Usage, Authorization Grant = Authorization Code.
• spaces list returns empty / 403 on space objects → Cause: technical user authenticated but not a member of the space. Solution: Space Management → SPACE_ID → Members → add user with DW Viewer (read) or DW Integrator (run tasks).
• "Fresh" data is stale or source is overloaded → Cause: remote table replication vs federation confusion — replicated tables serve snapshots; federated tables push every query to the source. Solution: check Data Integration Monitor → Remote Tables; use federation for freshness, replication to offload heavy reads from S/4HANA.
• View returns 404 on the consumption API → Cause: view not exposed — "Expose for Consumption" toggle is OFF. Solution: Data Builder → open view → toggle Expose for Consumption ON → deploy, then retry the OData/SQL query.
• hdbsql connection refused → Cause: client IP not in the Datasphere IP allowlist. Solution: System → Configuration → IP Allowlist → add the client's public IP.

Verification

# 1. MCP healthy + env vars present
npm run hc                          # datasphere-mcp must report OK; no missing DSPHERE_* vars

# 2. CLI authenticated and space visible
datasphere spaces list              # target space appears

# 3. View consumable end-to-end
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://<tenant>.us10.hcs.cloud.sap/api/v1/dwc/consumption/relational/SALES/V_SALES_KPI/V_SALES_KPI?\$top=1"
# → returns one row of JSON, not 404/403

# 4. Task chain green
datasphere tasks list --space SALES   # last run status = COMPLETED

Related

• sap-datasphere skill — modeling layer: spaces, Data Builder, analytical models, replication flows, VDM
• datasphere-mcp in .mcp.json — MarioDeFelipe/sap-datasphere-mcp (DSPHERE_HOST/USER/PASSWORD)
• sap-hana-cli skill — hdbsql and HANA Cloud client tooling for Open SQL schema access
• sap-sac-* skills — SAC consumes exposed Datasphere analytical models