arc-mcp-hub

A thin, deterministic MCP hub for SAP BTP. It puts multiple ARC-1 instances — one per SAP system (DEV / QA / PROD) — behind one front door with one login, while keeping each system fully isolated and preserving per-user SAP identity.

                        one login
  MCP client  ───────────────────────────►  arc-mcp-hub  (one BTP app)
  (VS Code / Claude / Cursor)                  │  /dev/mcp  ─► ARC-1 (DEV)   ─► SAP DEV
                                               │  /qa/mcp   ─► ARC-1 (QA)    ─► SAP QA
                                               │  /prod/mcp ─► ARC-1 (PROD)  ─► SAP PROD

You connect your MCP client to https://<hub>/dev/mcp (or /qa/mcp, /prod/mcp). The hub validates your login, propagates your identity to that system's ARC-1 (so SAP sees the real you), and transparently relays the connection. Each system's tools come through unchanged.

When to use it

• You run ARC-1 against several SAP systems and want one endpoint host + one login instead of N independently-configured servers.

• You want per-user SAP identity preserved end-to-end (principal propagation), per system.

• All those ARC-1 instances live in one BTP subaccount.

• You want to front other SAP MCP servers too, not only ARC-1 — any XSUAA-protected, Streamable-HTTP MCP server qualifies (how).

Related MCP server: Multi-MCP Hub

When NOT to use it

• One SAP system only → just point your client at that ARC-1 directly. The hub adds nothing.

• You want a natural-language assistant that reasons across systems → that's a different, LLM-in-the-middle product. This hub is deterministic routing only — no server-side LLM (the optional /all endpoint merges tool lists, but never reasons or calls a model).

• Backends in different subaccounts → not supported in v1 (the token exchange only maps within one subaccount). See roadmap.

• You want the model to pick the system at call time → off by default (the path-scoped routes bind the system to which endpoint you connect to, so an agent can't accidentally write to PROD from a DEV conversation). If you do want it, enable the opt-in /all endpoint — but keep PROD read-only at the backend, because that structural guard (not the tool surface) is what makes a misroute harmless.

How it works (one paragraph)

The hub is an OAuth 2.1 resource server (one shared authorization server → one login). Each /<env>/mcp advertises its own resource (per RFC 9728) so standards-compliant clients connect cleanly. On each request the hub takes your validated token, exchanges it via a BTP destination (OAuth2JWTBearer) for a per-user token scoped to that backend, and bridges the MCP Streamable-HTTP session to it. The backend (ARC-1) does its own principal propagation to SAP, so SAP enforces your real authorizations — a user without PROD access simply can't do anything on PROD, even if they connect to /prod/mcp.

There is no shared service account and no LLM in the path. See docs/architecture.md.

Optional: one endpoint for every system

By default you point a client at one system (/dev/mcp). If instead you want all systems through a single connection, enable the aggregated endpoint:

cf set-env arc-mcp-hub HUB_ALL_ENDPOINT true && cf restart arc-mcp-hub

Then connect a client to https://<hub>/all/mcp. It exposes every backend's tools once, each with a required system parameter naming which SAP system to act on (dev, s4-2025, …). Add an optional description per backend so the model sees what each system is:

[{ "name": "dev", "destination": "arc1-dev", "description": "S/4HANA 2023 (758)" },
 { "name": "s4-2025", "destination": "arc1-2025", "description": "ABAP Platform 2025 (816)" }]

• Cost ≈ one tool set. The backends are the same server (ARC-1) against different SAP targets, so a shared tool set + a system param doesn't duplicate descriptions — /all costs about the same as a single per-system endpoint, not N×.

• Trade-off — no structural isolation. The model picks the system per call, so /all does not have the per-connection safety of the path-scoped routes. Make a misroute harmless instead: a PROD backend must run SAP_ALLOW_WRITES=false + a read-only SAP user. The system enum, server instructions, and a required-no-default param are disambiguation aids — not controls.

• Sessions are principal-bound + idle-reaped. Each /all session is tied to the user who created it (a different principal is rejected — the session id is not a credential) and is closed after an idle timeout together with its backend connections. A backend whose own tools already declare a system parameter is unsupported by /all (it fails loud at list time) — use that backend's per-system route.

• Prefer the per-system routes for routine single-system work; use /all for cross-system tasks.

Quick start

1. Deploy the hub into the same BTP subaccount as your ARC-1 instances:

   npm ci && npm run build
   cf push                 # uses manifest.yml  (or: mbt build && cf deploy *.mtar  for MTA)

2. Wire each backend (a one-time per-system setup) — full steps in docs/operator-setup.md: create a destination, grant the hub a scope on the backend, assign developers the role collection.

3. Configure backends — set HUB_BACKENDS:

   [{ "name": "dev", "destination": "arc1-dev" }, { "name": "prod", "destination": "arc1-prod" }]

   Adding a system later = create a destination + add one entry here. No code change.

4. Connect a client to one system, e.g. in VS Code .vscode/mcp.json:

   { "servers": { "sap-dev": { "type": "http", "url": "https://<hub>/dev/mcp" } } }

   First use → one browser login → the system's ARC-1 tools appear.

Configuration

Safety model

• Connection-scoped systems. A session on /dev/mcp can only ever see DEV's tools. There is no runtime system selector to get wrong.

• PROD is read-only at the backend. Set SAP_ALLOW_WRITES=false and a read-only SAP user on the PROD ARC-1 instance. Even if someone connects to /prod/mcp, writes are refused at the strongest boundary (SAP).

• Per-user identity. Every call runs as the logged-in user via principal propagation — no shared service account. Each MCP session is bound to the principal that created it (a different user is rejected — the session id is a routing token, not a credential) and is idle-reaped along with its backend connections.

• The hub has no local authorization gate — by design. Inbound auth verifies a valid hub-audience token (one login); it does not require a hub-specific scope. Access is gated downstream: the OAuth2JWTBearer exchange only succeeds if the user holds the backend's foreign scope (via their role collection), and SAP then enforces the real user's authorizations — so a user who authenticates but lacks the role collection can reach the hub yet do nothing. To also stop an authenticated user from driving exchanges they can't use, enforce the hub use scope or rate-limit MCP calls (trust proxy is already set for accurate per-IP limiting).

Limits (v1)

• Same subaccount for hub + backends (cross-subaccount → roadmap).

• Single instance (in-memory session map). Scaling >1 needs sticky sessions or a shared store.

• No server-side LLM — by design.

Roadmap

Full deferred/open-items list: docs/roadmap.md. Highlights:

• Cross-subaccount backends (OAuth2SAMLBearerAssertion / shared IAS).

• Horizontal scale (shared session store).

• Read-only-aware tool surface (omit write tools when every backend is read-only).

• Hub-local authorization gate / MCP rate-limiting.

• A local (stdio) edition for non-BTP arc-1 setups.

Development

npm ci
npm test          # unit + local integration (proxy ↔ in-process MCP backend)
npm run typecheck
npm run lint
npm run build

Docs

• architecture.md — request flow, modules, invariants.

• operator-setup.md — step-by-step BTP wiring per backend.

• integrating-an-mcp-server.md — requirements + what to change to put any MCP server behind the hub, with primary-source BTP/XSUAA references.

License

MIT