# SAP Cloud Connector MCP

A local [Model Context Protocol](https://modelcontextprotocol.io/) server for SAP Cloud Connector configuration and monitoring. Inspect subaccounts, virtual-to-internal mappings, allowed resources, tunnel status, certificates and performance. Optional create/update/delete tools are disabled until explicitly enabled in server configuration.

Independent project. Not affiliated with, endorsed by, or supported by SAP. SAP and SAP Cloud Connector are trademarks of SAP SE. MIT licensed.

**Status:** initial implementation. Automated tests exercise HTTPS and the MCP stdio protocol using generated certificates and synthetic data. Compatibility with a specific Cloud Connector version, authentication setup and user role must be verified separately. No package or hosted service is required.

## Requirements

- Node.js 22.14 or later and npm.
- Network access to your Cloud Connector's administration HTTPS origin, usually port 8443. A local VPN may be required.
- An existing Cloud Connector account with permission to read the required APIs. Basic authentication is supported; client-certificate-only and interactive SSO authentication are not implemented.
- A certificate chain trusted by Node, or the issuing CA in `SCC_CA_FILE`.

Configuration reads generally accept Display (`sccdisplay`) and other roles listed by SAP. Monitoring datasets generally require Monitoring (`sccmonitoring`) or Administrator (`sccadmin`). With LDAP, assign only the roles needed; a Monitoring-only account may not read all configuration APIs. The default local user store provides only Administrator. Write APIs require an appropriate administration role in SAP and a master connector instance, in addition to explicit enablement in this server.

## Install from source

In a checkout of this repository:

```sh
npm ci
npm run build
npm test
```

The executable is `dist/index.js`. `node dist/index.js --version` works without credentials. `npm start` runs an MCP stdio process and waits for a client; it is not an interactive chat application. For MCP registration, invoke `node` directly so npm banners do not interfere with the protocol.

## Configure an MCP client

Set the following environment variables on the server process. Credentials are supplied at startup, never as tool arguments. No environment files are automatically loaded.

| Variable | Meaning |
| --- | --- |
| `SCC_BASE_URL` | Required HTTPS origin, e.g. `https://connector.example.com:8443`. No embedded credentials, path, query or fragment. |
| `SCC_USERNAME` | Required Cloud Connector username. |
| `SCC_PASSWORD` | Password injected by the host or a secret manager. Mutually exclusive with `SCC_PASSWORD_FILE`. |
| `SCC_PASSWORD_FILE` | Absolute path to a password-only UTF-8 file, as an alternative to `SCC_PASSWORD`. Restrict filesystem access yourself. One terminal newline is removed; spaces are preserved. |
| `SCC_CA_FILE` | Optional absolute path to a PEM bundle of trusted issuing CA certificates. Replaces the default CA trust for these requests. |
| `SCC_ENABLE_WRITES` | Optional, defaults to `false`. Only the exact string `true` exposes and enables create/update/delete tools. Restart the server after changing it. |
| `SCC_IGNORE_CERTIFICATE_ERRORS` | Optional, defaults to `false`. Set exactly `true` to ignore server certificate chain, expiry and hostname errors for this configured connector only. Restart after changing it. |
| `SCC_SUBACCOUNT_AUTH_FILE` | Optional absolute path to private JSON BTP onboarding credentials, required only to create a subaccount. See below. |
| `SCC_TIMEOUT_MS` | Absolute per-call deadline, including DNS/TLS/body reads. Default 15000, range 100–120000. |
| `SCC_MAX_RESPONSE_BYTES` | Maximum response size. Default 2097152 (2 MiB), range 1024–16777216. |

Generic stdio client configuration (adapt the configuration location to your host):

```json
{
  "mcpServers": {
    "sap-cloud-connector": {
      "command": "node",
      "args": ["/absolute/path/sap-cloud-connector-mcp/dist/index.js"],
      "env": {
        "SCC_BASE_URL": "https://connector.example.com:8443",
        "SCC_USERNAME": "monitoring-user",
        "SCC_PASSWORD_FILE": "/absolute/private/path/scc-password.txt",
        "SCC_CA_FILE": "/absolute/path/enterprise-ca.pem"
      }
    }
  }
}
```

On Windows, use forward slashes or JSON-escaped backslashes in absolute paths. Remove `SCC_CA_FILE` if Node already trusts the certificate. Use your MCP host's environment/secret forwarding settings for `SCC_PASSWORD` when available. Do not commit a populated client configuration or password file. A password file is plaintext, not a secret vault; the server does not manage its permissions or encryption. Environment variables also remain accessible to the user/processes with sufficient OS privileges.

For several connectors, create separate MCP entries with separate origins and credentials. Tools cannot change the configured origin or select credentials.

### Enter and store credentials on Windows

In PowerShell 7, run this from the repository directory:

```powershell
.\scripts\Save-Credentials.ps1
```

Enter the **Cloud Connector administration username and password** at the prompts. The password is masked and saved using Windows user-scoped DPAPI in `%LOCALAPPDATA%\SapCloudConnectorMcp\credentials\default.xml`. It can be decrypted only by the same Windows account on the same machine. The helper restricts its credential directory to the current user. It does not contact SAP or enable writes. Run with `-Profile another-name` for another saved credential; use `-Force` explicitly to replace a profile.

Configure your MCP host to use the credential launcher:

```json
{
  "mcpServers": {
    "sap-cloud-connector": {
      "command": "pwsh",
      "args": [
        "-NoProfile", "-NonInteractive", "-File",
        "C:/path/sap-cloud-connector-mcp/scripts/Start-Mcp.ps1",
        "-BaseUrl", "https://connector.example.com:8443",
        "-Profile", "default"
      ],
      "env": {
        "SCC_ENABLE_WRITES": "false"
      }
    }
  }
}
```

Use the absolute path to `pwsh.exe` if your host cannot find it. The host must preserve `LOCALAPPDATA` for the saved profile. The launcher resolves `node.exe` directly, avoiding npm shell shims; optionally pass `-NodePath C:/path/to/node.exe` to select a specific runtime. Add `SCC_CA_FILE` when a private issuing CA is needed. The launcher decrypts the password only for the child MCP process, keeps stdout reserved for the protocol and restores its credential environment on exit. Plaintext still necessarily exists in process memory. The generic Node configuration above remains available on Windows and other platforms.

## Tools

By default, the following 12 read tools are exposed, each backed by a fixed GET route. The client revalidates its arguments before issuing the request. With `SCC_ENABLE_WRITES=true`, 12 additional write tools are exposed as described below. There is no arbitrary URL/method/body tool, bulk delete, restart, backup, credential-change, certificate-import or test-message operation.

| Tool | Input | Purpose |
| --- | --- | --- |
| `scc_get_version` | none | Installed connector version; 2.14+. |
| `scc_get_connector` | none | Description and master/shadow role. |
| `scc_list_subaccounts` | none | Configured region hosts, subaccount IDs and location IDs. |
| `scc_get_subaccount` | `regionHost`, `subaccount` | Configuration for one exact subaccount. |
| `scc_list_system_mappings` | `regionHost`, `subaccount` | Virtual-to-internal system mappings. |
| `scc_get_system_mapping` | Above plus `virtualHost`, `virtualPort` | One exact mapping. |
| `scc_list_resources` | Same as mapping detail | Allowed HTTP/RFC resources and policies. |
| `scc_list_domain_mappings` | `regionHost`, `subaccount` | Domain mappings. |
| `scc_list_service_channels` | `regionHost`, `subaccount`, `channelType` | Configured channels of type `HANA`, `VirtualMachine`, `ABAPCloud`, `ABAPCloudSNC` or `K8S`. |
| `scc_get_monitoring` | `metric` | One of the monitoring datasets below. |
| `scc_ping` | none | HTTP service reachability only. |
| `scc_has_master_role` | none | Whether this instance currently has the master role; 2.15+. |

Monitoring metrics: `subaccounts`, `backend_connections`, `service_channel_connections`, `backend_performance`, `top_time_consumers`, `memory`, `disk`, `cpu`, `certificates`, `usage`, `alerts`.

Most monitoring datasets require a master instance. Service-channel connection monitoring and K8S configuration listing require 2.15+, memory/certificates/usage require 2.13+, CPU/disk require 2.17+, and alerts require 2.19+. Other fields and service-channel types vary by SAP version. A 404 may mean an unsupported API or a missing target; the server does not infer which or silently hide the failure.

Call `scc_list_subaccounts` first and pass the returned `regionHost` and `subaccount` exactly. Read system mappings before requesting a mapping's resources; named RFC ports and TCP port ranges are accepted. The first release accepts DNS-style/IPv4 virtual host names, not IPv6 literals or arbitrary host characters.

Tool results contain `operation`, `observedAt` (UTC) and `data`, available as text and structured content. Credential-like properties and exact configured authentication strings are redacted recursively. Other response data is retained; it can contain internal hosts, users, paths or operational information. Tool errors contain sanitized codes/messages, never raw SAP error bodies. `scc://api-catalog` is an offline resource listing currently exposed tools, write enablement and monitoring metrics.

Example prompts:

- “List the configured subaccounts and their current tunnel status.”
- “Show the mapping and allowed resources for this virtual host.”
- “Which connector certificates are expired or nearing expiry?”

A configured mapping is not proof of backend reachability. A connected tunnel or successful ping is not proof of a successful business transaction. The server does not probe backends or send business messages.

## Enable create, update and delete

Set `SCC_ENABLE_WRITES=true` in the **MCP server process configuration** and restart the server. Merely using an SAP administrator account does not enable writes. A tool argument cannot enable writes. With writes disabled, these tools are hidden from discovery and direct client execution is also blocked before any network request.

| Record | Create | Update | Delete |
| --- | --- | --- | --- |
| System mapping | `scc_create_system_mapping` | `scc_update_system_mapping` | `scc_delete_system_mapping` |
| Allowed resource | `scc_create_resource` | `scc_update_resource` | `scc_delete_resource` |
| Domain mapping | `scc_create_domain_mapping` | `scc_update_domain_mapping` | `scc_delete_domain_mapping` |
| Subaccount | `scc_create_subaccount` | `scc_update_subaccount` | `scc_delete_subaccount` |

Service-channel configuration is currently read-only. Write payloads use explicit schemas; arbitrary fields and passwords in tool arguments are rejected. Mapping and resource updates use SAP PUT replacement semantics; optional settings you want retained must be included. Mapping host/port, resource ID and internal-domain keys are retained on update; use a separately reviewed delete/create if a key must change. Deleting a mapping removes its resources, and deleting a subaccount removes its associated configuration. Creating a subaccount also connects it, as defined by SAP.

Every write follows this flow:

1. Call the tool with its exact target and payload. `dryRun` defaults to `true`. The server reads the target and returns the existing record, proposed request, effects and a random confirmation token. This issues GET requests only.
2. Show the complete preview to the user and obtain approval of the exact change.
3. Call the same tool with identical parameters, `dryRun: false` and the returned `confirmationToken`. The token is bound to the operation and arguments, expires after five minutes and can be consumed only once. It is lost on restart.
4. The server rereads the target, rejects changes since preview, checks the master role, submits one POST/PUT/DELETE, then reads back the target to check the requested configuration or deletion.

A token is a technical guard, not proof that a human approved the change. The MCP host/client remains responsible for obtaining user approval. Snapshot checks reduce stale writes but are not an atomic lock against another administrator changing SAP between the check and submission. Subaccount snapshots cover parent settings, not every child configuration.

Example resource creation arguments (synthetic values):

```json
{
  "regionHost": "cf.example.com",
  "subaccount": "sample-account",
  "virtualHost": "virtual.example.com",
  "virtualPort": "443",
  "resourceId": "/example/status",
  "payload": { "enabled": true, "exactMatchOnly": true },
  "dryRun": true
}
```

Execution results distinguish `submitted` from `verification.status` (`passed`, `failed`, or `unavailable`). Failed/unavailable verification is also an MCP tool error and must be inspected before another write. A timeout, interrupted response or server failure after submission may produce `WRITE_UNCERTAIN`; the server never retries automatically. Inspect the exact target before deciding what to do next. Verification covers configuration only, not tunnel connectivity or business outcomes.

### Additional credentials for subaccount creation

Your local Cloud Connector login is separate from the BTP credentials needed to onboard a subaccount. To enable `scc_create_subaccount`, point `SCC_SUBACCOUNT_AUTH_FILE` to a private UTF-8 JSON file outside the repository:

```json
{
  "regionHost": "cf.example.com",
  "subaccount": "sample-account",
  "cloudUser": "btp-user@example.com",
  "cloudPassword": "EXAMPLE_ONLY"
}
```

These BTP credentials are usable only for the exact configured region and subaccount. They are inserted internally into SAP's create request and redacted from previews/results. This optional file is plaintext; protect it using OS permissions or provision it through your secret manager. It is not needed for mapping/resource/domain writes or subaccount edits/deletion. Newer `authenticationData` onboarding and service-channel writes are not implemented.

## Authentication and CSRF

SAP documents two API modes: a retained session with a session cookie plus CSRF token, or stateless Basic requests with `Connection: close`. This server uses the latter on every GET. It does not import browser cookies, retain sessions, retrieve passwords from a browser, or require a CSRF token. This also avoids stale browser sessions and concurrent token refresh logic.

An HTTP 200 response with `text/html` is treated as authentication failure, not API success. Redirects are rejected rather than followed. TLS verification is enabled by default, including when a process-wide TLS environment variable attempts to disable it. Prefer a matching server certificate and trusted issuing CA.

For an explicitly trusted internal connector with certificate errors, set `SCC_IGNORE_CERTIFICATE_ERRORS=true` in that MCP entry's environment. The connection remains encrypted but the server's identity is not authenticated, so intercepted traffic could expose credentials or data. This setting applies only to this client's configured HTTPS origin; it does not modify the OS trust store or other clients. It does not enable writes. `scc://api-catalog` reports `tlsVerificationEnabled`, and live verification reports whether certificate verification was enabled or disabled.

## Optional live verification

Live verification is separate from automated tests and is never run in CI. It reads all supported monitoring datasets, plus configuration and HANA service channels for the first returned subaccount and the first system mapping if present. It does not test every subaccount, channel type, protocol or mapping. Unsupported endpoints and insufficient permissions are reported as failures, not silently skipped successes.

On Windows, enter credentials into a private PowerShell prompt:

```powershell
.\scripts\Test-Live.ps1 -BaseUrl https://connector.example.com:8443 -CaFile C:\private\enterprise-ca.pem
```

The script prompts for the username and masked password, passes the password through the child process environment, and restores the previous process environment afterward. It does not save the password. Omit `-CaFile` when Node already trusts the issuing CA. The password necessarily exists in process memory while the check runs.

On other platforms, inject the documented environment variables privately and run `npm run verify:live`. Do not put a real password in a command line or shell history.

The verifier starts the real MCP stdio server and calls it with the official MCP client. It explicitly forces writes off even if the parent environment enables them. It saves only outcomes, counts, and the connector version in `.local/live-verification.json`, which is ignored by Git and excluded from the package. Review that report before sharing it. It never persists raw API bodies, hostnames, subaccount IDs, certificates or passwords.

## Development and release

```sh
npm run check
```

This builds, runs tests against ephemeral local HTTPS fixtures, audits runtime dependencies and previews the npm package. Tests cover protocol communication, stateless auth, target validation, credential redaction, failed TLS, redirects, login pages, response limits and timeouts. GitHub Actions runs offline connector tests on Linux and Windows with Node 22 and 24; dependencies are downloaded from npm.

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md) and the [API reference](docs/api-reference.md). Publishing to GitHub or npm is a separate, explicit release step. No automatic publish workflow is included.

## Sources

Implemented against SAP's published API contracts and the official MCP TypeScript SDK:

- [SAP Cloud Connector REST APIs and authentication/session rules](https://github.com/SAP-docs/btp-connectivity/blob/main/docs/1-connectivity-documentation/rest-apis-ede0776.md)
- [Configuration API index](https://github.com/SAP-docs/btp-connectivity/blob/main/docs/1-connectivity-documentation/configuration-rest-apis-cfb9d57.md)
- [Monitoring API contracts, roles and version requirements](https://github.com/SAP-docs/btp-connectivity/blob/main/docs/1-connectivity-documentation/monitoring-apis-f6e7a7b.md)
- [MCP TypeScript SDK v2](https://github.com/modelcontextprotocol/typescript-sdk)