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.

42 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)

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: SF-MCP

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

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.

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

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?"

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).