sap-bdc-mcp

SAP Business Data Cloud MCP Server (sap-bdc-mcp)

An MCP (Model Context Protocol) server that exposes safe, well-scoped SAP Business Data Cloud (BDC) discovery + contract tooling for AI agents (Cursor, Claude Desktop, LibreChat, etc.) — with enterprise-first guardrails (redaction, policy gating, bounded outputs, and read-only defaults).

Latest release: v0.2.0 — Governed BDC Connect (Databricks-first execution, Snowflake readiness, audit + policy gates, npx distribution wrapper, subprocess plugin upstreams). See the v0.2.0 section at the end of this README and the CHANGELOG.

Previous release: v0.1.0 — contract-first open-core foundation: ORD discovery, CSN contract checks, share planning (non-executing). The v0.1 content below describes that initial baseline; v0.2 builds on it without breaking compatibility.

---

Why this exists

Modern enterprises increasingly want AI agents to act — not just chat. But real enterprise action requires:

• controlled access to systems of record,
• strict governance and auditability,
• safe defaults (no accidental writes),
• predictable, machine-readable tool contracts.

MCP provides the standard “tool bus” that lets external clients call tools safely. This project provides that tool bus specifically for SAP Business Data Cloud so agents can:

• discover data products and resources (ORD),
• validate and diff schema contracts (CSN),
• plan data sharing contracts before execution (share plans),
• operate safely (redaction + permissions + bounded outputs).

---

Where sap-bdc-mcp fits in the enterprise landscape

In most enterprise setups, you’ll have:

• AI clients (Cursor, Claude Desktop, LibreChat, internal copilots)
• MCP servers (tool providers) running inside a controlled network boundary
• SAP platforms (BDC, Datasphere, BW, etc.)
• Governance (identity, policies, approvals, logging, DLP)

SAPBDCMCP is intended to run inside your boundary (developer laptop, jump host, or a controlled runtime) and act as the policy-gated integration layer between agentic tooling and SAP BDC.

A typical flow:

1. User asks an AI client to find / validate / plan something.
2. The client calls MCP tools exposed by sap-bdc-mcp.
3. The server enforces:
   • output size limits,
   • redaction of secrets,
   • permission levels (READ/WRITE/ADMIN),
   • “no writes by default”.
4. Results are returned to the client in structured form.

Important: v0.1 focuses on read-only and contract-first operations. It does not execute shares or mutate BDC resources.

---

Architecture (plugin-based, safety-first)

Component view

MCP Client (Cursor / Claude / LibreChat)
            |
            | stdio (v0.1)
            v
+---------------------------+
|  FastMCP Server           |
|  (tool registry)          |
+------------+--------------+
             |
             v
+---------------------------+        +--------------------------+
| Policy + Redaction        |        | Connectors / Parsers     |
| - Permission gates        |------->| - ORD loader + search    |
| - Secret redaction        |        | - JSON Schema validation |
| - Output bounds           |        | - CSN validation + diff  |
+------------+--------------+        +--------------------------+
             |
             v
+---------------------------+
| Tool Packs (v0.1)         |
| - Core                    |
| - ORD                     |
| - CSN                     |
| - Share Plan              |
+---------------------------+

Design principles

• Safe defaults: write tools are off unless explicitly enabled.
• Contract-first: validate structures before “doing” anything.
• Composable: tools are grouped into “packs” that can evolve independently.
• Enterprise-friendly: minimal data retention, predictable behavior, and clear boundaries.

---

What’s included in v0.1

Core tooling (safe diagnostics)

• Health + wiring checks
• Configuration diagnostics (with redaction)
• Tenant/user “identity” introspection (mock-friendly)

ORD (Open Resource Discovery)

• Fetch ORD documents from URLs and local files
• Expand ORD Configuration documents (to resolve referenced documents)
• Search resources by type (data products, APIs, events, etc.)
• Validate documents against shipped JSON Schemas

CSN (Common Schema Notation / contract checks)

• Validate CSN structure for interoperability / tooling assumptions
• Diff CSNs to detect breaking vs non-breaking changes
• Render CSN → Markdown documentation (quick contract docs)

Share planning (non-executing)

• Build share plan objects with a stable contract shape
• Validate share plans against safety limits (asset limits, duplicates, required fields)
• No execution in v0.1 (planning + validation only)

---

Installation

Install from PyPI (recommended)

pip install sap-bdc-mcp

Install from source (development)

git clone https://github.com/rahulsethi/SAPBDCMCP.git
cd SAPBDCMCP
python -m venv .venv
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Prerequisites

• Python 3.11+
• pip

Install from source (recommended for v0.1)

git clone https://github.com/rahulsethi/SAPBDCMCP.git
cd SAPBDCMCP

python -m venv .venv

# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1

# macOS/Linux
# source .venv/bin/activate

pip install -e ".[dev]"

Environment file (optional)

cp .env.example .env

---

Configuration

The server is configured via environment variables (or a .env file).

Required (for v0.1)

Nothing is strictly required — mock mode supports local development without a BDC tenant.

Common settings

Variable	Default	Purpose
BDC_MODE	local	Runtime mode label (local/dev/prod)
BDC_MOCK_MODE	1	Use fixtures/local inputs instead of calling external endpoints
BDC_VERIFY_TLS	1	Verify TLS certificates for HTTPS fetches
BDC_MAX_DOC_KB	512	Max size for fetched ORD docs (prevents “LLM ate my RAM” moments)
BDC_ORD_SOURCES	(empty)	Comma-separated list of ORD sources (URLs or file paths)
BDC_PLUGINS	(empty)	Comma-separated plugin module paths to load
BDC_ENABLE_WRITE_TOOLS	0	Enables write tools (keep OFF in v0.1)

Optional tenant identity (informational in v0.1)

Variable	Purpose
BDC_TENANT_ID	Tenant identifier (redacted in outputs)
BDC_REGION	Region label
BDC_BASE_URL	Base URL label (redacted where appropriate)
BDC_USER	User label (redacted)
BDC_SERVICE_ACCOUNT	Service account label (redacted)

---

Running the server

Stdio mode (default)

sap-bdc-mcp

This starts the MCP server on stdio, suitable for:

• Cursor MCP integration
• Claude Desktop MCP servers
• LibreChat MCP connectors
• custom MCP clients

Alternative entry (useful for debugging)

python -m sap_bdc_mcp

---

Using from MCP clients

Cursor

This repo includes a Cursor MCP configuration file at .cursor/mcp.json.

Typical workflow:

1. Open the repository in Cursor
2. Ensure your venv is active and dependencies are installed
3. Cursor will detect MCP config and can start the server automatically

Claude Desktop

Add an MCP server entry (stdio) and point it to your environment’s sap-bdc-mcp executable.

LibreChat

Configure an MCP server as a stdio tool provider and run it inside the same host/container boundary as LibreChat.

Exact configuration formats differ by client; the important invariant is: this server speaks MCP over stdio in v0.1.

---

Tool catalog (v0.1)

This section is intentionally detailed so you can:

• understand expected inputs/outputs,
• write deterministic agent prompts,
• validate behavior without a BDC tenant.

Core tools

bdc_ping

Purpose: lightweight health check for server wiring and config surface.

Returns (example):

{
  "ok": true,
  "server": "sap-bdc-mcp",
  "version": "0.1.0",
  "mode": "local",
  "mock_mode": true,
  "write_enabled": false
}

Test prompts:

• “Call bdc_ping and tell me whether write tools are enabled.”
• “Check if the SAP BDC MCP server is alive and report version + mode.”

---

bdc_diagnostics

Purpose: structured readiness report (all sensitive values redacted).

Returns (high level):

• runtime mode, TLS settings, limits
• ORD source configuration
• plugin status
• redacted environment summary

Test prompts:

• “Run bdc_diagnostics and summarize what is configured vs missing.”
• “Show me current safety limits and plugin status.”

---

bdc_get_tenant_info

Purpose: returns configured tenant labels (redacted), useful for client sanity checks.

Returns (high level):

• tenant id, region, base url (if configured)
• mode + mock mode

Test prompts:

• “Use bdc_get_tenant_info and confirm whether a tenant is configured.”
• “Show tenant metadata (redacted) and current mode.”

---

bdc_whoami

Purpose: returns identity labels (mock identity in mock mode).

Returns (high level):

• user / service account identity (redacted)
• mock identity when BDC_MOCK_MODE=1

Test prompts:

• “Call bdc_whoami and tell me who this server thinks it is.”
• “Show identity info, but ensure secrets are not displayed.”

---

ORD tools (Open Resource Discovery)

bdc_ord_fetch_documents

Purpose: fetch ORD documents from sources (URLs or local files). Supports ORD Configuration expansion.

Parameters:

• sources (optional): list of URLs/file paths. If omitted, uses BDC_ORD_SOURCES.

Returns:

• document count
• full ORD documents (expanded if configuration docs are used)

Test prompts:

• “Fetch ORD docs from the configured sources, then summarize how many documents were loaded.”
• “Load the local ORD sample fixture and list the available resource types.”

---

bdc_ord_search

Purpose: search across loaded ORD documents.

Parameters:

• query (required): search query string
• resource_type (optional): default dataProduct
  (e.g., apiResource, eventResource, entityType, capability)
• sources (optional): override sources (defaults to config)
• limit (optional): default 25

Returns:

• query + resource_type
• count
• matching resources (ordId, title, description, metadata)

Test prompts:

• “Search ORD for data products matching ‘finance’ and show top 5.”
• “Search for ‘sales’ in apiResource and summarize results.”
• “Find entity types containing ‘Customer’ and list ordIds.”

---

bdc_ord_validate

Purpose: validate ORD documents against JSON Schema.

Parameters:

• sources (optional): list of sources to validate (defaults to config)

Returns:

• ok/not ok
• issues with paths + messages (capped per document)

Test prompts:

• “Validate the currently configured ORD sources and report any schema errors.”
• “Validate the ORD fixture and show me the first 10 issues (if any).”

---

CSN tools (Common Schema Notation)

bdc_csn_validate

Purpose: validate a CSN object for tooling compatibility.

Parameters:

• csn (required): CSN JSON object

Returns:

• ok/not ok
• issues with codes + messages

Test prompts:

• “Validate this CSN and explain what’s missing or malformed.”
• “Check whether this CSN is safe to publish as a contract.”

---

bdc_csn_diff

Purpose: compare two CSNs and classify changes.

Parameters:

• old_csn (required)
• new_csn (required)

Returns:

• breaking changes: removals, incompatible type changes, kind changes
• non-breaking changes: additive changes
• summary stats

Test prompts:

• “Diff these two CSNs and list breaking changes first, then non-breaking.”
• “Tell me if upgrading from old_csn to new_csn is backward compatible.”

---

bdc_csn_render_docs

Purpose: render CSN → Markdown documentation (contract docs).

Parameters:

• csn (required)

Returns:

• Markdown string describing entities, fields, types, constraints

Test prompts:

• “Generate Markdown docs for this CSN and include entity + field summaries.”
• “Create a compact schema reference for this CSN.”

---

Share planning tools (non-executing in v0.1)

bdc_share_plan

Purpose: create a share plan object (does not execute anything).

Parameters:

• share_name (required)
• assets (required): list of assets:
  • type: table | view | file
  • name: asset identifier
  • schema (optional): namespace/schema
  • comment (optional)
• description (optional)
• provider (optional): default sap-bdc

Returns:

• normalized, validated share plan object

Test prompts:

• “Create a share plan called ‘demo_share’ with 2 tables in schema ‘FIN’.”
• “Generate a share plan for these assets and return the resulting JSON.”

---

bdc_share_validate_contract

Purpose: validate a share plan contract and safety limits.

Parameters:

• plan (required): share plan JSON

Validations:

• required fields + structure
• max asset count (50)
• duplicate asset detection
• asset naming/shape checks

Returns:

• ok/not ok
• issues list (if any)

Test prompts:

• “Validate this share plan and tell me what I need to fix.”
• “Check whether this plan exceeds safety limits or contains duplicates.”

---

Testing & quality

Run tests

pytest

Run with coverage

pytest --cov=src/sap_bdc_mcp --cov-report=term-missing

Test coverage (v0.1): 100% statement coverage for src/sap_bdc_mcp is the quality bar for this repo (and should remain enforced as changes land).
If you ever see lower numbers, treat it as a regression and tighten tests before merging.

---

Safety, security, and governance notes

This project is designed to be safe by default, but enterprise safety is a system property, not a single feature. Recommended posture:

Safe defaults baked in

• Write tools disabled by default (BDC_ENABLE_WRITE_TOOLS=0)
• Automatic secret redaction across tool outputs
• Bounded outputs to prevent oversized data egress
• Mock mode to develop without connecting to production

Data handling expectations

• v0.1 tools focus on discovery + contract validation, not data movement.
• The server is intended to run within your controlled boundary.
• When future versions add live BDC operations, they should be deployed with:
  • least-privileged service accounts,
  • strict network controls,
  • centralized logging/monitoring,
  • approvals for write actions (where appropriate).

Redaction scope

The server automatically redacts common sensitive patterns including:

• API keys, secrets, passwords
• bearer tokens
• credentials embedded in URLs
• fields with sensitive key names

If you are deploying this inside an enterprise, treat this as one layer of defense-in-depth, not a substitute for DLP, IAM, and network security.

---

Contributing

Contributions are welcome. Please see CONTRIBUTING.md.

---

License

sap-bdc-mcp is licensed under the Business Source License 1.1 (BSL 1.1) from v0.2.0 onward — the same license as its sibling SAPDatasphereMCP. It converts automatically to Apache 2.0 on 2029-01-01. (v0.1.0 was MIT; that version remains MIT-licensed for code already in use.) See LICENSE for the full text.

• Free for noncommercial use — personal, evaluation, research, academic, and internal evaluation.
• Commercial / for-profit use requires a separate license. See docs_public/COMMERCIAL_LICENSING.md to inquire.
• A 2-for-1 family discount is available on commercial licenses covering both sap-bdc-mcp and SAPDatasphereMCP.

---

v0.2.0 — Governed BDC Connect (2026-05-27)

v0.2.0 turns sap-bdc-mcp from a contract-first discovery server (v0.1) into a governed-execution server. Three deltas land:

1. Provider-neutral execution layer — BDCConnectProvider ABC with DatabricksProvider (real provider) and SnowflakeProvider (readiness-only at v0.2; mutation deferred to v0.3 per ADR-002).
2. Policy + audit teeth — tool risk metadata, SAP API policy evidence, dry-run + approval-token gating, JSONL audit log.
3. Multi-runtime reach — BDC_PLUGINS now accepts npx: / uvx: / cmd: upstream MCP servers as subprocess plugins. sap-bdc-mcp itself can now be launched via npx -y sap-bdc-mcp@0.2.0 thanks to a Node bootstrap wrapper that bridges to uvx.

What's new — tool surface

13 new MCP tools land at v0.2 on top of the 12 from v0.1 (25 total):

Tool	Category	Mutability	Risk	Notes
bdc_tool_risk_catalog	governance	READ	low	All registered tools + their risk metadata
bdc_policy_explain	governance	READ	low	Which gates apply to a tool and would they pass now
bdc_api_policy_check	governance	READ	low	SAP API evidence summary per tool
bdc_audit_tail	governance	READ	low	Recent audit events (redacted, capped)
bdc_connect_list_providers	providers	READ	low	Configured providers + capabilities
bdc_connect_diagnostics	providers	READ	low	Provider configuration health
bdc_connect_preflight	providers	READ	low	Run a provider's preflight
bdc_databricks_preflight	databricks	READ	medium	Databricks share-readiness preflight
bdc_databricks_validate_share_readiness	databricks	READ	medium	Per-share readiness check
bdc_databricks_generate_csn_from_share	databricks	READ	low	CSN from a Databricks share (primitives only — see D-006)
bdc_snowflake_preflight	snowflake	READ	low	Snowflake readiness checks (no mutation at v0.2)
bdc_snowflake_explain_flow	snowflake	READ	low	Documented publish flow text
bdc_share_execute_plan	sharing	WRITE	high	Governed execution. Requires dry-run + approval token

All 12 v0.1 tools are still registered and identical in behavior — they now also produce audit events.

Two install routes

Python (recommended for production):

pip install sap-bdc-mcp==0.2.0
sap-bdc-mcp --help

Node / npx (no Python toolchain to manage):

npx -y sap-bdc-mcp@0.2.0 --help

The wrapper bootstraps Python via uv automatically. If uvx isn't on your PATH, the wrapper prints a one-screen install hint and exits.

Configure in your MCP client

claude_desktop_config.json (Python install):

{
  "mcpServers": {
    "sap-bdc-mcp": {
      "command": "sap-bdc-mcp",
      "env": { "BDC_MODE": "local", "BDC_MOCK_MODE": "1" }
    }
  }
}

claude_desktop_config.json (npx install):

{
  "mcpServers": {
    "sap-bdc-mcp": {
      "command": "npx",
      "args": ["-y", "sap-bdc-mcp@0.2.0"],
      "env": { "BDC_MODE": "local", "BDC_MOCK_MODE": "1" }
    }
  }
}

Safe defaults (unchanged spirit, more teeth)

• BDC_ENABLE_WRITE_TOOLS=0 and BDC_ENABLE_ADMIN_TOOLS=0 by default — every mutating tool is refused until you opt in.
• BDC_REQUIRE_DRY_RUN=1 — high-risk tools must dry-run first; the dry-run returns a correlation_id you replay on real execute.
• BDC_REQUIRE_APPROVAL_TOKEN=1 + BDC_APPROVAL_TOKEN=<your-secret> — every real execution must pass a constant-time-compare token (per D-003).
• BDC_API_POLICY_STRICT=1 — WRITE/ADMIN tools with api_surface=UNKNOWN are refused. This is what gates subprocess plugin proxies by default.
• BDC_AUDIT_ENABLED=1 — every tool call writes a JSONL audit event (sha256-hashed inputs after redaction). Tail via bdc_audit_tail.

Full env-var reference + troubleshooting + the upgrade path from v0.1 is in the CHANGELOG.

Subprocess plugin upstreams (npx / uvx / cmd)

BDC_PLUGINS="gh=npx:@modelcontextprotocol/server-github@latest,sentry=uvx:mcp-server-sentry"
BDC_PLUGIN_TRUST="gh:documented_sdk"          # operator-asserted trust
BDC_PLUGIN_ENV_PASSTHROUGH="GITHUB_TOKEN"     # secrets to forward

Child MCP server tools are proxied as plug_<alias>__<tool>, treated as WRITE / UNKNOWN-surface by default, gated through the same audit + policy chain. Trust is operator-asserted; sap-bdc-mcp never blindly trusts a child's metadata.

Publishing

PyPI + npm + GitHub Releases. Publishing is a deliberate, manual step performed by the maintainer. The artifacts to upload are:

• PyPI: dist/sap_bdc_mcp-0.2.0-py3-none-any.whl and dist/sap_bdc_mcp-0.2.0.tar.gz (produced by python -m build)
• npm: npx-wrapper/ (cd npx-wrapper && npm publish --access public)
• GitHub Release: tag v0.2.0 with the CHANGELOG v0.2.0 section as the body

Full changelog

See CHANGELOG.md — the canonical record of what's in v0.2.0.