SAP CPI MCP Server

A Model Context Protocol server that lets an MCP client (Claude Desktop, Claude Code, etc.) monitor and manage SAP Cloud Integration (CPI / Integration Suite) through its OData v1 APIs — the same surface documented as the "Cloud Integration" package on the SAP Business Accelerator Hub.

It runs locally over stdio or as an HTTP service you can deploy to SAP BTP Cloud Foundry. One server instance can talk to a single CPI tenant or many — see Multi-tenant support below.

46 tools: curated tools for the common workflows, plus generic escape-hatch tools (cpi_query, cpi_get_entity, cpi_invoke_function, cpi_write) that reach any of the ~130 entity sets and 35 operations the API exposes.

What it can do (tools)

Tenant discovery

Monitoring — Message Processing Logs (MPL)

Design-time content

Runtime & deployment

Admin (security material, config, queues, B2B, logs)

Generic — full API coverage

⚠️ = write/destructive tool — requires ALLOW_WRITE=true (see below).

Related MCP server: ABAP-ADT-API MCP-Server

Write safety

Read tools always work. Write / deploy / delete tools only run when ALLOW_WRITE=true is set in your .env. In addition, every write action requires an explicit confirm=true: calling a write tool without it returns an "Are you sure you want to …?" prompt and makes no changes. Re-run the same tool with confirm=true to proceed. This gives a two-step confirmation for all create/update/delete/deploy operations.

ALLOW_WRITE=false   # default — read-only
ALLOW_WRITE=true    # enable the ⚠️ tools

Multi-tenant support

One running server can reach one CPI tenant (the default) or several, decided purely by what's in .env — no code change either way.

Single tenant (default)

The plain vars — CPI_BASE_URL / CPI_TOKEN_URL / CPI_CLIENT_ID / CPI_CLIENT_SECRET — work exactly as before. No tool gains an extra argument; nothing else in this section applies.

Multiple tenants

Add a numbered group of the same four vars per tenant — CPI_BASE_URL1, CPI_BASE_URL2, CPI_BASE_URL3, ... — and the server discovers however many it finds at startup:

CPI_BASE_URL1=https://dev-tenant.it-cpiXXX.cfapps.eu10.hana.ondemand.com/api/v1
CPI_TOKEN_URL1=https://dev-subdomain.authentication.eu10.hana.ondemand.com/oauth/token
CPI_CLIENT_ID1=dev-client-id
CPI_CLIENT_SECRET1=dev-client-secret
TENANT_NAME1=Dev

CPI_BASE_URL2=https://qa-tenant.it-cpiXXX.cfapps.eu10.hana.ondemand.com/api/v1
CPI_TOKEN_URL2=https://qa-subdomain.authentication.eu10.hana.ondemand.com/oauth/token
CPI_CLIENT_ID2=qa-client-id
CPI_CLIENT_SECRET2=qa-client-secret
TENANT_NAME2=QA

Once 2 or more tenants are configured:

• Every tool gains a required tenant argument — a fixed enum of the exact TENANT_NAME<N> values found (case-insensitive match, but the MCP client sees these exact names). The client (Claude) has to ask which tenant to use rather than guessing.

• Call list_cpi_tenants any time to see the current list — it's the one tool that never needs a tenant itself.

• TENANT_NAME<N> defaults to tenant<N> if omitted, but naming it is strongly recommended — that name is what shows up in every tool's schema and in Claude's prompts.

Adding a 3rd, 4th, ... Nth tenant later is just adding another numbered block — no code change, no redeploy of anything but the env file itself. Restart the MCP server connection after editing .env (or cf set-env + cf restage for the HTTP deployment) so it re-reads it.

Per-tenant overrides

Two flags can be scoped to one tenant instead of the whole server:

# Allow writes on Dev only, even if the global ALLOW_WRITE below is false:
ALLOW_WRITE1=true

# Take a tenant out of rotation without deleting its credentials — it disappears from
# list_cpi_tenants, the `tenant` enum, and multi-tenant mode entirely (falls back to
# single-tenant behavior if only one enabled tenant remains):
STATUS2=disable   # "disable"/"disabled" to turn off; unset or "enable" = on (default)

Isolation guarantees

• Each tenant gets its own OAuth access-token cache and CSRF/session-cookie cache — a busy Dev tenant's token can never be reused for a Prod call, even under load.

• Error messages and results are host-masked per tenant, so one tenant's real hostname never leaks through a call made against another.

• ALLOW_WRITE<N> and STATUS<N> are independent per tenant; nothing else (RBAC scopes, auth mode) is tenant-aware — those still apply server-wide.

Role-based access control (RBAC)

Three roles, layered on top of ALLOW_WRITE/confirm=true rather than replacing them:

The generic escape-hatch tools (cpi_write, cpi_invoke_function) are pinned to mcp.delete regardless of the HTTP method or function called — they can reach operations (arbitrary DELETE, or destructive function imports like DeleteValMaps) that the curated tools don't expose, so they're Architect-only rather than Developer-only.

This only applies to the HTTP transport with an XSUAA binding. The static-token and open modes grant full access to everyone (no per-user identity to hang a role off), and the stdio transport is unaffected — it's a local subprocess with no role boundary, same as before.

Setting it up in BTP

1. xs-security.json already defines the scopes and role templates (Support, Developer, Architect — plus the legacy CpiMcpUser/Use scope, kept so anyone already assigned it keeps working, treated as read-only). Push the updated descriptor:

   cf update-service sap-cpi-mcp-xsuaa -c xs-security.json
   cf restage sap-cpi-mcp-server

2. In BTP Cockpit → your subaccount → Security → Role Collections, create three collections — Architect, Developer, Support — each pulling in the matching role template from the sap-cpi-mcp app.

3. Assign your team: either manually per user (Role Collection → Edit → add by email), or — if you already trust an IdP like Entra ID — map IdP groups to these Role Collections under Security → Trust Configuration → your IdP → Role Collection Mappings, so membership in an Entra group like MCP-Architect grants the collection automatically at login.

4. A user's token then carries whichever scopes their Role Collection grants; src/auth.js reads them off the verified JWT and src/domains/helpers.js enforces them per tool call.

Testing a role change — watch for token caching

After moving a user between Role Collections, the change will not show up until they get a genuinely new access token — MCP clients (including Claude.ai) cache the tool list and will silently reuse a still-valid token via refresh rather than re-authenticating. token-validity in xs-security.json is 3600s (1 hour), so a client can hold a stale scope set for up to an hour after a role change.

To force a real re-check: fully remove/delete the connector in the client (not just "Disconnect" — that alone may not clear the cached token) and re-add it from scratch, so it goes through a brand-new OAuth login. Look for a "tools list refreshed"-style confirmation after reconnecting, and check the tool count actually changed, before concluding a role assignment didn't take effect.

Securing the HTTP endpoint with OAuth 2.0 (XSUAA)

For the hosted (Cloud Foundry) endpoint, authentication is handled by src/auth.js:

1. OAuth 2.0 (recommended) — bind an XSUAA instance and the server requires a valid JWT:

   cf create-service xsuaa application sap-cpi-mcp-xsuaa -c xs-security.json
   cf bind-service sap-cpi-mcp-server sap-cpi-mcp-xsuaa
   cf restage sap-cpi-mcp-server
   cf create-service-key sap-cpi-mcp-xsuaa claude-connector   # -> clientid/secret/url for the client

   The server verifies the JWT signature against XSUAA's JWKS (<uaa>/token_keys) and checks the audience. A client obtains a token via client_credentials (or authorization_code) from <uaa>/oauth/token and calls /mcp with Authorization: Bearer <jwt>.

2. Static token (dev/fallback) — if no XSUAA is bound but MCP_AUTH_TOKEN is set, that static bearer token is required instead.

3. Open — if neither is configured, the endpoint is unauthenticated (local/PoC only).

Auth mode is auto-detected: XSUAA binding → OAuth; else MCP_AUTH_TOKEN → static; else open. The local stdio transport is unaffected by all of this.

OAuth discovery / authorize / token proxy (remote MCP clients)

Remote MCP OAuth clients (e.g. a Claude custom connector) resolve the authorization server either via RFC 8414 discovery at this origin, or — if that's absent — by assuming /authorize and /token live on the MCP server's own host. XSUAA's real endpoints live on a different host (the UAA tenant), so without help the client gets a 404 hitting <this-origin>/authorize directly.

When an XSUAA binding is present, the server exposes:

If no XSUAA binding is found, these routes are not mounted and a warning is logged at startup. This is purely a discovery/proxy convenience for OAuth clients — it does not replace the JWT verification in authMiddleware(), which still gates every request to /mcp.

1. Get CPI API credentials (one-time)

The OData API is served by the Process Integration Runtime service.

1. In your BTP subaccount → Instances and Subscriptions → create an instance of Process Integration Runtime with plan api.

2. Under Roles, grant the roles you need, e.g.:

   • MessageProcessingLogRead (read MPLs)

   • IntegrationContentRead (read packages / design artifacts / deployed artifacts)

   • MonitoringDataRead

   • For the ⚠️ write tools (deploy/undeploy/create/delete): add the write/deploy roles too, e.g. WorkspacePackagesEdit, WorkspaceArtifactsDeploy, MessageProcessingLogCustomHeaderRead, and the relevant security-material roles.

3. Create a Service Key on that instance. From the key you get:

   • url → your CPI_BASE_URL is <url>/api/v1

   • tokenurl → your CPI_TOKEN_URL (it already ends in /oauth/token)

   • clientid → CPI_CLIENT_ID

   • clientsecret → CPI_CLIENT_SECRET

2. Run locally (stdio) with Claude Desktop / Claude Code

npm install
cp .env.example .env      # then edit .env with your service-key values

For more than one tenant, use the numbered vars (CPI_BASE_URL1, CPI_BASE_URL2, ...) instead — see Multi-tenant support above. .env.example documents both forms.

Add to your MCP client config (Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "sap-cpi": {
      "command": "node",
      "args": ["C:/path/to/sap-cpi-mcp-server/src/index.js"],
      "env": {
        "CPI_BASE_URL": "https://your-tenant.it-cpiXXX.cfapps.eu10.hana.ondemand.com/api/v1",
        "CPI_TOKEN_URL": "https://your-subdomain.authentication.eu10.hana.ondemand.com/oauth/token",
        "CPI_CLIENT_ID": "your-client-id",
        "CPI_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

For Claude Code:

claude mcp add sap-cpi -- node C:/path/to/sap-cpi-mcp-server/src/index.js

3. Deploy to SAP BTP Cloud Foundry (HTTP)

cf login -a https://api.cf.<region>.hana.ondemand.com
cf target -o <org> -s <space>

# Edit manifest.yml OR set secrets as environment variables:
cf push --no-start

cf set-env sap-cpi-mcp-server CPI_BASE_URL    "https://.../api/v1"
cf set-env sap-cpi-mcp-server CPI_TOKEN_URL   "https://.../oauth/token"
cf set-env sap-cpi-mcp-server CPI_CLIENT_ID   "..."
cf set-env sap-cpi-mcp-server CPI_CLIENT_SECRET "..."
cf set-env sap-cpi-mcp-server MCP_AUTH_TOKEN  "a-long-random-secret"   # optional gate

cf start sap-cpi-mcp-server

The MCP endpoint will be:

https://sap-cpi-mcp-server.cfapps.<region>.hana.ondemand.com/mcp

Connect an HTTP-capable MCP client:

{
  "mcpServers": {
    "sap-cpi": {
      "type": "http",
      "url": "https://sap-cpi-mcp-server.cfapps.<region>.hana.ondemand.com/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Security note: MCP_AUTH_TOKEN is a simple shared-secret gate for getting started. For production, front the app with the SAP Application Router + XSUAA for proper OAuth2/JWT protection, and bind credentials via a service instance rather than plain env vars.

4. Example prompts once connected

• "Show me all failed messages in the last 4 hours."

• "Give me a failure summary for the last 24 hours grouped by integration flow."

• "Get the error details for MessageGuid AGh...."

• "List integration flows in package MyIntegrationPackage and tell me which are deployed."

• "Is the OrderReplication flow deployed and started? If not, why?"

• "Which CPI tenants are configured?" (multi-tenant setups — calls list_cpi_tenants)

• "Show failed messages in the last 24 hours on the QA tenant." (multi-tenant — Claude fills in tenant=QA)

Notes on the CPI OData API

• Collection base: .../api/v1

• MPLs: /MessageProcessingLogs — filter with $filter, sort with $orderby=LogEnd desc.

• Error text: /MessageProcessingLogs('<guid>')/ErrorInformation/$value (plain text).

• Packages: /IntegrationPackages, flows: /IntegrationDesigntimeArtifacts.

• Deployed: /IntegrationRuntimeArtifacts.

• Time filters use OData datetime literals: LogEnd gt datetime'2024-01-01T00:00:00'.

Requires Node.js 18+ (uses the built-in fetch).