sap-integration-suite-mcp

Open-source MCP server for SAP Integration Suite monitoring, failed-message analysis, integration health and AI-assisted troubleshooting.

This is an independent open-source project and is not an official SAP product.

See validation status and release checklist for local verification results and remaining deployment checks. Local validation does not establish compatibility with every SAP tenant configuration.

Self-host the server in your environment and connect your MCP-compatible AI client. The server retrieves read-only monitoring metadata from your own SAP Integration Suite / SAP Cloud Integration tenant. Your chosen client performs inference; this server never calls an LLM.

Architecture

flowchart TD
  AI[AI client: Codex, VS Code, Claude Code, Cursor or another MCP host]
  AI --> MCP[MCP server: stdio or Streamable HTTP]
  MCP --> Security[Authentication, strict validation and sanitization]
  Security --> SAPClient[SAP API client: OAuth, timeouts, bounded pagination]
  SAPClient --> Tenant[Customer SAP Integration Suite tenant]

Related MCP server: SAP CPI MCP Server

Features

• Vendor-independent MCP SDK v2 server with stdio and stateless Streamable HTTP.

• OAuth 2.0 client credentials, in-memory token reuse and refresh.

• Normalized OData message metadata and sanitized diagnostic evidence.

• Deterministic error categories and health statistics without AI calls.

• Strict inputs, safe URL construction, bounded results and read-only SAP access.

• Mocked test suite, CI workflow and non-root Docker deployment.

Supported tools

Limits default to 100, maximum 500. Recent windows are 1–10080 minutes. Times must be ISO 8601 with timezone; time windows filter message start time. Health defaults to the past 24 hours and caps retrieval at 500 messages. Inspect truncated and scope: a bounded sample is not a tenant-wide total. Unknown statuses are counted as other; empty windows return zero percentages. Error categories are unavailable in bulk health because this adapter does not fetch per-message diagnostic text in that operation.

The classifier supports AUTHENTICATION, AUTHORIZATION, HTTP_4XX, HTTP_5XX, TIMEOUT, CONNECTIVITY, SFTP, CERTIFICATE, MAPPING, TRANSFORMATION, PAYLOAD_VALIDATION, RATE_LIMIT, OAUTH and UNKNOWN. Confidence is conservative and evidence contains deterministic indicators. Investigation suggestions are not proven root causes.

Version 1 does not deploy flows, change configuration, delete messages, restart processing or retry messages. Business payloads, attachments and custom message headers are not retrieved. Endpoint/adapter metadata is explicitly unavailable in analysis. Runtime status and error navigation depend on the tenant API and permissions.

Security and privacy

Credentials stay in your runtime environment. There is no external database, author-operated backend, telemetry upload or LLM call. The server does not send SAP monitoring data to the project author. The MCP client receives results and may transmit them according to its own data-handling rules.

SAP URLs come only from trusted server configuration, use HTTPS and reject redirects. MCP callers cannot choose hosts or request arbitrary URLs. Pagination is confined to the same message collection. Logs contain only operation metadata on stderr. Secrets, access tokens, authorization headers and SAP bodies are excluded from logs. Diagnostic text is redacted and capped; free-form business information can still remain, so treat outputs as sensitive.

HTTP checks exact Host and Origin allowlists and supports a separate bearer credential. Non-loopback binds require a token. Put production access behind an authenticated TLS gateway with rate limits and concurrency controls. See security design and reporting policy.

Prerequisites and SAP configuration

Use Node.js 24 LTS, npm, your SAP tenant's HTTPS management API URL, and a least-privilege OAuth technical client. Confirm API permissions and token endpoint with your SAP administrator. Exact role collections and scopes vary; see SAP setup, SAP monitoring API and official SAP documentation.

The built-in logger emits operation information at info/debug and suppresses it at warn/error/silent. Startup failures use a generic stderr error. Health reports process liveness, not credential validity or SAP connectivity.

Installation

From a checkout of this repository:

npm ci
npm run build

Supply environment variables through your secret manager or protected process environment. .env.example contains names only. To use a local .env file, copy the example, set your own values and restrict its permissions. Node's explicit --env-file flag can load it; the application does not load it automatically.

node --env-file=.env dist/index.js --stdio

No SAP credentials are required to run tests; SAP responses are mocked. The repository includes a committed dependency lockfile. Contributors and CI should use npm ci for reproducible installation.

Local stdio

Point any stdio-capable MCP host at:

{
  "command": "node",
  "args": ["/absolute/path/sap-integration-suite-mcp/dist/index.js", "--stdio"]
}

Forward SAP variables securely from the host's process environment. For a protected local file, use args: ["--env-file=/absolute/path/.env", "/absolute/path/dist/index.js", "--stdio"]. Do not embed secrets in shared configuration. Claude Code, Cursor and other stdio clients have different enclosing config formats. ChatGPT connectivity depends on the product's supported MCP/connector mechanism.

Streamable HTTP

node --env-file=.env dist/index.js --http

The endpoint is http://127.0.0.1:3000/mcp. POST/GET are delegated to the current SDK transport; stateless legacy clients receive 405 for GET/DELETE session operations. This is Streamable HTTP, not a separate deprecated HTTP+SSE endpoint. GET /health returns small JSON and uses the same access guards.

For remote access configure MCP_HOST, a high-entropy MCP_HTTP_TOKEN, exact allowed Host authorities and any browser Origin URLs. Serve https://your-host.example.com/mcp through your TLS gateway. Never send the SAP OAuth secret to the MCP client. The MCP access token is separate. No inbound OAuth authorization server is provided.

Codex

codex mcp add sapIntegrationSuite -- node /absolute/path/sap-integration-suite-mcp/dist/index.js --stdio
codex mcp add sapIntegrationSuite --url https://your-host.example.com/mcp

Use one transport for a given server name. Configure forwarded environment variables for stdio or bearer_token_env_var for remote access. See Codex setup and official OpenAI MCP documentation.

VS Code

Remote .vscode/mcp.json configuration uses a servers entry with type: "http", the /mcp URL and a securely prompted Authorization header. See the complete VS Code example.

Docker

docker compose up --build -d

Supply a protected .env containing your own SAP variables and a separate MCP_HTTP_TOKEN of at least 32 characters. Compose passes it at runtime; .dockerignore excludes all .env files from the image. For managed production deployments use your platform's secret injection rather than a checked-in file. Docker runs the HTTP server as the node user with a read-only filesystem. Compose publishes only loopback by default. Extend networking through your authenticated TLS gateway.

Example questions

• “Show failed SAP Integration Suite messages from the last hour.”

• “Show failures for SALESFORCE_TO_S4 today.”

• “Get details for message ID ABC123.”

• “Summarize Integration Suite health for the past 24 hours.”

• “Analyze the available diagnostic evidence for message ABC123.”

Use your intended timezone when asking about “today”; tools require explicit ISO times. ABC123 is a synthetic example.

Troubleshooting

API assumptions and required tenant checks are documented in SAP_SETUP.md. Do not post production logs or credentials when reporting issues.

Development and contributing

npm run dev:stdio
npm run dev:http
npm run format
npm run lint
npm run typecheck
npm test
npm run test:coverage
npm run build

See CONTRIBUTING.md, architecture and code of conduct. Release verification is documented in the validation checklist.

Roadmap

• Verify adapters against multiple real tenant configurations and supported SAP API revisions.

• Add tenant-validated error and runtime fixtures, broader health aggregation and optional policy enforcement.

• Add additional supported authentication providers and customer-controlled audit integrations.

• Keep Version 1 read-only; any future write capabilities require separate security design and explicit scope.

Recommended repository topics: sap, sap-integration-suite, sap-cloud-integration, sap-cpi, mcp, model-context-protocol, enterprise-integration, integration, ai, typescript, open-source, observability, monitoring.

License and author

Apache License 2.0 — see LICENSE. Cite the project using CITATION.cff.

Rameshkumar Varanganti