@mcp-abap-adt/proxy 1.6.4 → 4.0.0

package/docs/CLIENT_SETUP.md

@@ -0,0 +1,413 @@
+# Client Setup Guide
+
+This guide provides step-by-step instructions for configuring Cline and GitHub Copilot to connect to MCP servers through the proxy.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Cline Configuration](#cline-configuration)
+- [GitHub Copilot Configuration](#github-copilot-configuration)
+- [Configuration Scenarios](#configuration-scenarios)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+1. **Install the proxy**:
+   ```bash
+   npm install -g @mcp-abap-adt/proxy
+   ```
+
+2. **Set up service keys** (for BTP destination-based authentication):
+   - Place service key files in platform-specific directories:
+     - **Unix/Linux/macOS**: `~/.config/mcp-abap-adt/service-keys/`
+     - **Windows**: `%USERPROFILE%\Documents\mcp-abap-adt\service-keys\`
+   - Service key files should be named after the destination (e.g., `btp-cloud.json`)
+
+3. **Start the proxy server** (see scenarios below for specific commands)
+
+## Cline Configuration
+
+Cline uses the `streamableHttp` transport type and requires HTTP endpoint configuration.
+
+### Basic Configuration File
+
+Cline configuration is typically stored in:
+- **macOS**: `~/Library/Application Support/Cline/cline.json`
+- **Windows**: `%APPDATA%\Cline\cline.json`
+- **Linux**: `~/.config/Cline/cline.json`
+
+### Scenario 1: BTP Auth with Target URL Override
+
+**Use Case**: Authenticate with a BTP destination's service key, but forward requests
+to a different URL (e.g. direct OData testing or a non-standard MCP path).
+
+**1. Start the proxy**:
+```bash
+mcp-abap-adt-proxy --btp=btp-cloud \
+  --target-url=https://your-service.cfapps.eu10.hana.ondemand.com
+```
+
+**2. Configure Cline** (`cline.json`):
+```json
+{
+  "mcpServers": {
+    "mcp-abap-adt-proxy": {
+      "disabled": false,
+      "timeout": 60,
+      "type": "streamableHttp",
+      "url": "http://localhost:3001/mcp/stream/http",
+      "headers": {
+        "x-sap-destination": "btp-cloud",
+        "x-target-url": "https://your-service.cfapps.eu10.hana.ondemand.com"
+      }
+    }
+  }
+}
+```
+
+**What happens**:
+- Proxy obtains a BTP token from the `btp-cloud` service key
+- Forwards requests to `x-target-url` instead of the key's `abap.url`, with `Authorization: Bearer <token>`
+
+### Scenario 2: BTP MCP Server with BTP Authentication
+
+**Use Case**: Connect to an MCP server deployed on SAP BTP that requires BTP authentication.
+
+**1. Set up BTP service key**:
+   - Create service key file: `~/.config/mcp-abap-adt/service-keys/btp-cloud.json`
+   ```json
+   {
+     "uaa": {
+       "url": "https://your-uaa-url.authentication.eu10.hana.ondemand.com",
+       "clientid": "your-client-id",
+       "clientsecret": "your-client-secret"
+     },
+     "abap": {
+       "url": "https://mcp-server.cfapps.eu10.hana.ondemand.com"
+     }
+   }
+   ```
+
+**2. Start the proxy**:
+```bash
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+**3. Configure Cline** (`cline.json`):
+```json
+{
+  "mcpServers": {
+    "mcp-abap-adt-proxy": {
+      "disabled": false,
+      "timeout": 60,
+      "type": "streamableHttp",
+      "url": "http://localhost:3001/mcp/stream/http",
+      "headers": {
+        "x-sap-destination": "btp-cloud"
+      }
+    }
+  }
+}
+```
+
+**Alternative: Use command-line override** (simpler, no headers needed):
+```bash
+# Start proxy with command-line overrides
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+```json
+{
+  "mcpServers": {
+    "mcp-abap-adt-proxy": {
+      "disabled": false,
+      "timeout": 60,
+      "type": "streamableHttp",
+      "url": "http://localhost:3001/mcp/stream/http"
+    }
+  }
+}
+```
+
+**What happens**:
+- Proxy gets BTP token from `btp-cloud` destination
+- Adds `Authorization: Bearer <token>` header
+- Gets MCP server URL from service key (`abap.url`)
+- Forwards request to MCP server on BTP
+
+## GitHub Copilot Configuration
+
+GitHub Copilot supports multiple transport types. The configuration depends on your setup.
+
+### Configuration File Location
+
+GitHub Copilot configuration is typically stored in:
+- **macOS**: `~/Library/Application Support/GitHub Copilot/settings.json`
+- **Windows**: `%APPDATA%\GitHub Copilot\settings.json`
+- **Linux**: `~/.config/GitHub Copilot/settings.json`
+
+### Scenario 1: HTTP Transport (Recommended)
+
+**1. Start the proxy** (same as Cline scenarios above):
+```bash
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+**2. Configure GitHub Copilot** (`settings.json`):
+```json
+{
+  "mcpServers": {
+    "mcp-abap-adt-proxy": {
+      "disabled": false,
+      "timeout": 60,
+      "type": "streamableHttp",
+      "url": "http://localhost:3001/mcp/stream/http",
+      "headers": {
+        "x-sap-destination": "btp-cloud"
+      }
+    }
+  }
+}
+```
+
+### Scenario 2: SSE Transport
+
+**1. Start the proxy with SSE transport**:
+```bash
+mcp-abap-adt-proxy --transport=sse --btp=btp-cloud
+```
+
+**2. Configure GitHub Copilot** (`settings.json`):
+```json
+{
+  "mcpServers": {
+    "mcp-abap-adt-proxy": {
+      "disabled": false,
+      "timeout": 60,
+      "type": "sse",
+      "url": "http://localhost:3002",
+      "headers": {
+        "x-sap-destination": "btp-cloud"
+      }
+    }
+  }
+}
+```
+
+**Note**: SSE transport uses port 3002 by default (HTTP uses 3001).
+
+### Scenario 3: Stdio Transport
+
+**1. Start the proxy with stdio transport**:
+```bash
+mcp-abap-adt-proxy --transport=stdio --btp=btp-cloud
+```
+
+**2. Configure GitHub Copilot** (`settings.json`):
+```json
+{
+  "mcpServers": {
+    "mcp-abap-adt-proxy": {
+      "disabled": false,
+      "timeout": 60,
+      "type": "stdio",
+      "command": "mcp-abap-adt-proxy",
+      "args": [
+        "--transport=stdio",
+        "--btp=btp-cloud"
+      ]
+    }
+  }
+}
+```
+
+**Note**: For stdio transport, the destination must be provided via command-line arguments (`--btp`, `--target-url`), not headers.
+
+## The management mode
+
+A second command, `mcp-abap-adt-proxy-mcp`, speaks MCP over stdio and its tools
+start and stop proxies. Use it when the client should decide which proxy runs and
+when; use `mcp-abap-adt-proxy` when you want to be proxied.
+
+```json
+{
+  "mcpServers": {
+    "abap-proxy": { "command": "mcp-abap-adt-proxy-mcp" }
+  }
+}
+```
+
+It works from the configs in `~/.config/mcp-abap-adt/proxy/` — the same files
+`--config` takes — so starting a proxy is choosing a name:
+
+| Tool | |
+|---|---|
+| `proxy_configs` | the names available; call it first, they cannot be guessed |
+| `proxy_start` | starts one on a **free port** and returns the URL bound |
+| `proxy_stop` | frees the port and releases the credential; never touches another session's proxy |
+| `proxy_status` | this session's proxies and everyone else's, dead records pruned on read |
+
+Two things worth knowing before you rely on it:
+
+- **The proxies live in the management process.** Closing the session — or
+  `SIGINT`, or `SIGTERM` — stops all of them. A stop cuts requests still in
+  flight after a short grace, because a streamed response never ends on its own
+  and the port has to come back.
+- **`proxy_start` proves the credential before reporting success**, so an
+  interactive login happens where you asked for it rather than inside whatever
+  tool call happens to make the first request.
+
+See [Configuration](./CONFIGURATION.md#the-management-mode) for `idleTimeoutMs`
+and what the mode deliberately ignores from a config.
+
+## Configuration Scenarios Summary
+
+| Scenario | BTP Auth | Proxy Command | Headers Required |
+|----------|----------|---------------|------------------|
+| BTP MCP | Yes | `--btp=<dest>` | `x-sap-destination` |
+| BTP MCP + explicit URL | Yes | `--btp=<dest> --target-url=<url>` | `x-sap-destination`, `x-target-url` |
+
+## Advanced Configuration
+
+### Using Environment Variables
+
+You can configure the proxy using environment variables:
+
+```bash
+export MCP_HTTP_PORT=8080
+export LOG_LEVEL=debug
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+### Using Configuration File
+
+Create `mcp-proxy-config.json`:
+
+```json
+{
+  "httpPort": 3001,
+  "logLevel": "info",
+  "maxRetries": 3,
+  "requestTimeout": 60000
+}
+```
+
+Start proxy:
+```bash
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+### Session Storage
+
+By default, sessions are stored in-memory (secure, lost on restart). To persist sessions to disk:
+
+```bash
+mcp-abap-adt-proxy --unsafe --btp=btp-cloud
+```
+
+**Warning**: `--unsafe` mode persists tokens to disk. Use only in development environments.
+
+## Troubleshooting
+
+### Issue: Connection Refused
+
+**Symptoms**: Client cannot connect to proxy.
+
+**Solutions**:
+1. Verify proxy is running: `curl http://localhost:3001/mcp/stream/http`
+2. Check port number matches configuration (default: 3001 for HTTP, 3002 for SSE)
+3. Verify firewall settings allow connections to proxy port
+
+### Issue: Authentication Failed
+
+**Symptoms**: Proxy returns 401/403 errors.
+
+**Solutions**:
+1. Verify service key files exist in correct location
+2. Check service key format (must contain `uaa` section for BTP destinations)
+3. Verify destination names match between configuration and service key filenames
+4. Enable verbose logging: `LOG_LEVEL=debug mcp-abap-adt-proxy ...`
+
+### Issue: MCP Server Not Found
+
+**Symptoms**: Proxy cannot reach target MCP server.
+
+**Solutions**:
+1. Verify `abap.url` in the service key (or `x-target-url`/`--target-url` override) points to the MCP server
+2. Check network connectivity to MCP server
+3. Verify MCP server is running and accessible
+4. Verify the BTP destination (`--btp`/`x-sap-destination`) matches an existing service key
+
+### Issue: Headers Not Passed Through
+
+**Symptoms**: MCP server doesn't receive expected headers.
+
+**Solutions**:
+1. Remember: Only `x-sap-destination` is validated by proxy
+2. All other headers are passed directly to MCP server
+3. Verify headers are correctly formatted in client configuration
+4. Check proxy logs for routing decisions
+
+### Debug Mode
+
+Enable verbose logging to troubleshoot issues:
+
+```bash
+# Environment variable
+LOG_LEVEL=debug mcp-abap-adt-proxy --btp=<dest>
+```
+
+This will output detailed information about:
+- Routing decisions
+- Token retrieval
+- Request forwarding
+- Error details
+
+## Quick Reference
+
+### Proxy Command-Line Options
+
+```bash
+# Basic usage
+mcp-abap-adt-proxy [options]
+
+# Transport options
+--transport=streamable-http  # HTTP transport (default, port 3001)
+--transport=sse              # SSE transport (port 3002)
+--transport=stdio            # Stdio transport
+
+# Destination overrides
+--btp=<destination>          # BTP destination name
+--target-url=<url>           # Override target URL (auth still from --btp)
+
+# Port configuration
+--http-port=<port>           # HTTP port (default: 3001)
+--sse-port=<port>            # SSE port (default: 3002)
+
+# Session storage
+--unsafe                     # Enable file-based session storage
+
+# Help
+--help                       # Show help message
+```
+
+### Client Configuration Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `x-sap-destination` | Required* | BTP destination name for authentication |
+| `x-target-url` | Optional | Override the target URL (auth still from the BTP destination) |
+
+\* `x-sap-destination` (or the `--btp` command-line parameter) must be provided.
+
+### Service Key Locations
+
+- **Unix/Linux/macOS**: `~/.config/mcp-abap-adt/service-keys/<destination>.json`
+- **Windows**: `%USERPROFILE%\Documents\mcp-abap-adt\service-keys\<destination>.json`
+
+## Additional Resources
+
+- [Configuration Guide](./CONFIGURATION.md) - Complete configuration reference
+- [Usage Examples](./USAGE.md) - More usage examples
+- [Routing Logic](./ROUTING_LOGIC.md) - Detailed routing logic
+- [Troubleshooting Guide](./TROUBLESHOOTING.md) - Common issues and solutions

package/docs/CONFIGURATION.md

@@ -0,0 +1,258 @@
+# Configuration Guide
+
+This guide explains how to configure the MCP ABAP ADT Proxy server.
+
+## The four folders
+
+Everything the toolchain keeps on disk lives under one base:
+
+```
+~/.config/mcp-abap-adt/                    (Windows: %USERPROFILE%\Documents\mcp-abap-adt\)
+├── service-keys/   BTP service keys, one JSON per destination
+├── sessions/       .env files holding credentials, referenced by a config's envFile
+├── proxy/          one ready proxy config per proxy — the files --config takes
+└── runtime/        one record per live proxy, so one session can see another's
+```
+
+`AUTH_BROKER_PATH` relocates the base, and all four move with it.
+
+`runtime/` is written by the management mode and is not configuration: a file
+per running proxy, holding its pid, port, URL, destination and config name. A
+record is a claim, not a fact — every read checks the process behind it and
+deletes the ones whose writer has died, so a crashed session cannot leave a
+ghost behind.
+
+## Configuration Methods
+
+The proxy can be configured from a YAML/JSON file, from CLI parameters, or from a combination of both.
+
+### Mode 1: Config file (`--config` / `-c`)
+
+```bash
+mcp-abap-adt-proxy --config=mcp-proxy-config.yaml
+```
+
+The file provides the baseline values. **CLI flags override values from the file** — handy for tweaking a single setting (port, browser mode, headers) on top of a stable config.
+
+```bash
+# YAML provides everything; CLI overrides browser mode and callback port:
+mcp-abap-adt-proxy --config=mcp-proxy-config.yaml \
+  --browser none --browser-auth-port 8888
+```
+
+When CLI values override the file, the proxy logs a `Note: CLI flags override values from <path>: ...` warning so the override is visible.
+
+`--header key=value` flags are merged with `defaultHeaders` from the file (CLI keys win on conflict). All other overrides replace the file value entirely.
+
+Config string values and `--header` values support `${VAR}` / `${VAR:-default}`
+interpolation, resolved from `process.env` then a `.env` (`envFile` in YAML or
+`--env-file`). `process.env` wins; an unresolved `${VAR}` without a default fails
+at startup. See [YAML Configuration Guide](./YAML_CONFIG.md) for details.
+
+See [YAML Configuration Guide](./YAML_CONFIG.md) for the file format.
+
+### Mode 2: CLI params + environment variables + defaults
+
+Without `--config`, values come from CLI parameters, environment variables, and
+built-in defaults. The config file is **not** consulted in this mode (and there is
+no auto-discovery).
+
+#### CLI parameters
+
+| Flag | Description |
+|------|-------------|
+| `--btp=<destination>` | BTP destination for Cloud authorization |
+| `--target-url=<url>` (alias `--url`) | Override target URL |
+| `--unsafe` | Persist tokens to disk (default: in-memory) |
+| `--header key=value` | Default header injected into every request (repeatable) |
+| `--env-file <path>` | Path to a `.env` file supplying variables for `${VAR}` interpolation in config/headers (overrides YAML `envFile`) |
+| `--browser=<type>` | OAuth2 login browser: `system`, `headless`, `chrome`, `edge`, `firefox`, `none` |
+| `--browser-auth-port=<port>` | Port for the local OAuth2 callback server |
+| `--transport`, `--http-port`, `--http-host`, `--sse-port`, `--sse-host` | Transport settings |
+
+Run `mcp-abap-adt-proxy --help` for the full list.
+
+### Headless login (`--browser none`)
+
+With `--browser none` (or `headless`) the proxy does **not** open a browser. It
+prints the authorization URL to the console and waits. Complete login in one of
+two ways — whichever happens first wins:
+
+- **Automatic callback** — open the URL on the **same machine** as the proxy;
+  the browser redirects to `http://localhost:<browser-auth-port>/callback`.
+- **Paste form** — if your browser is on a **different machine**, open
+  `http://<proxy-host>:<browser-auth-port>/` and paste the `code` from the
+  address bar (or the whole redirected URL).
+
+As of `@mcp-abap-adt/auth-providers` 2.0.0, pasting the code straight into the
+proxy's terminal is **no longer supported**. The callback strategy reads no
+stdin at all, deliberately: under an MCP stdio transport, stdin carries the
+protocol itself, so a provider that read from it there would corrupt the
+stream. If you relied on terminal paste, use the paste form above instead —
+it covers the same "my browser is somewhere else" case without touching
+stdin.
+
+You have **5 minutes** from when the URL is printed to complete the login;
+after that the callback server times out and the attempt fails. Run the same
+command again to retry.
+
+```bash
+mcp-abap-adt-proxy --btp <dest> --browser none --browser-auth-port 3333
+```
+
+#### How long the callback port is held
+
+The callback port is bound when the login window opens and released as soon as
+the authorization code arrives — **before** it is exchanged for a token, not
+after. The exchange is a round trip to the identity provider, and holding the
+socket across it would keep the port busy for reasons that have nothing to do
+with receiving the callback. The proxy keeps running without it: this is not a
+listening port of the running proxy, only of the login.
+
+The release is also unconditional. Since `auth-providers@1.2.0` the socket has
+one owner and one release point, and it is freed on whatever ends the login
+first — the code arriving, an explicit failure, the timeout, or cancellation —
+so a settled login always means the port is already free.
+
+Two consequences:
+
+- **Two proxies can share one `browserAuthPort`, as long as their logins do not
+  overlap.** Whichever opens its login window first holds the port; a second one
+  starting during that window fails with `Port <n> is already in use` and exits.
+  Give each config its own port if you start several proxies at once.
+- **A callback port that stays busy after a login means something else holds
+  it.** See [Troubleshooting](./TROUBLESHOOTING.md#error-port-n-is-already-in-use-naming-your-browserauthport).
+
+Choose a number that no other local service uses. The proxy's callback port and
+some other tool's main port colliding is the most common cause of this error.
+
+## Environment Variables
+
+#### Server Configuration
+- `MCP_HTTP_PORT` - HTTP server port (default: `3001`)
+- `MCP_SSE_PORT` - SSE server port (default: `3002`)
+- `MCP_HTTP_HOST` - HTTP server host (default: `127.0.0.1`)
+- `MCP_SSE_HOST` - SSE server host (default: `127.0.0.1`)
+
+> **Note:** The default is `127.0.0.1` (loopback only) — the proxy runs locally and holds
+> auth tokens, so it does not listen on all interfaces by default. Set `httpHost`/`sseHost`
+> (or `MCP_HTTP_HOST`/`MCP_SSE_HOST`) to `0.0.0.0` only if you deliberately need to expose
+> it. (SSE additionally rejects non-local connections regardless of host.)
+- `MCP_TRANSPORT` - Transport type: `stdio`, `http`, `streamable-http`, or `sse`
+
+#### Session Storage
+- `MCP_PROXY_UNSAFE` - Set to `"true"` to persist tokens to disk (default: in-memory)
+
+#### Error Handling & Resilience
+- `MCP_PROXY_MAX_RETRIES` - Maximum number of retry attempts (default: `3`)
+- `MCP_PROXY_RETRY_DELAY` - Delay between retries in milliseconds (default: `1000`)
+- `MCP_PROXY_REQUEST_TIMEOUT` - Request timeout in milliseconds (default: `60000`)
+- ~~`MCP_PROXY_CIRCUIT_BREAKER_THRESHOLD`~~, ~~`MCP_PROXY_CIRCUIT_BREAKER_TIMEOUT`~~ — **no effect since 4.0.0.** Still read, so existing setups load unchanged. The circuit breaker guarded the buffered forward that 4.0.0 removed; the forwarding path now streams and a breaker there would mean buffering the response again
+
+#### Logging
+- `LOG_LEVEL` - Logging level: `debug`, `info`, `warn`, `error` (default: `info`)
+
+> **Note:** `--config` is the **only** way to load a config file. The
+> `MCP_PROXY_CONFIG` environment variable is **not** honored.
+
+## Configuration File
+
+For the YAML/JSON config-file format and the full field reference, see the
+[YAML Configuration Guide](./YAML_CONFIG.md). The file is loaded only via
+`--config=<path>` (or `-c`).
+
+## Examples
+
+### Example 1: CLI parameters
+
+```bash
+mcp-abap-adt-proxy --transport=streamable-http --btp=btp \
+  --header x-sap-destination=S4HANA_E19
+```
+
+### Example 2: Environment variables
+
+```bash
+export MCP_HTTP_PORT=8080
+export LOG_LEVEL=debug
+mcp-abap-adt-proxy --btp=btp
+```
+
+### Example 3: Config file
+
+```bash
+mcp-abap-adt-proxy --config=mcp-proxy-config.yaml
+```
+
+### Example 4: Config file with CLI overrides
+
+```bash
+mcp-abap-adt-proxy --config=mcp-proxy-config.yaml \
+  --http-port=3003 --browser none --browser-auth-port=8888
+```
+
+YAML supplies the baseline; the four flags override `httpPort`, `browser`, and `browserAuthPort` from the file. See [YAML Configuration Guide](./YAML_CONFIG.md).
+
+## Validation
+
+The configuration is validated on server startup. Errors will prevent the server from starting, while warnings will be logged but won't stop the server.
+
+### Common Validation Errors
+
+- `MCP_HTTP_PORT must be between 1 and 65535` - Invalid port number
+- `MCP_SSE_PORT must be between 1 and 65535` - Invalid port number
+- `MCP_HTTP_PORT and MCP_SSE_PORT must be different` - Ports must be unique
+
+### Common Validation Warnings
+
+- `No BTP destination provided (--btp)` - Proxy won't work unless requests include an `x-sap-destination` header
+- `MCP_PROXY_MAX_RETRIES should be between 0 and 10` - Retry count out of recommended range
+- `MCP_PROXY_RETRY_DELAY should be between 0 and 60000ms` - Retry delay out of recommended range
+- `MCP_PROXY_REQUEST_TIMEOUT should be between 1000 and 300000ms` - Timeout out of recommended range
+
+## Best Practices
+
+1. **Use a config file for stable setups** - Keep per-subaccount settings in a YAML file loaded via `--config`
+2. **Use CLI params for quick overrides** - CLI flags override matching values from `--config` (handy for one-off tweaks like a different `--browser-auth-port`)
+3. **Validate configuration** - Check logs for validation warnings on startup
+4. **Set appropriate timeouts** - Adjust `requestTimeout` based on your network conditions
+5. **Give each proxy its own `browserAuthPort`** - the callback socket is bound only for the duration of a login, but two logins cannot overlap on one port
+
+## The management mode
+
+`mcp-abap-adt-proxy-mcp` starts proxies from the configs in `proxy/` and differs
+from `mcp-abap-adt-proxy` in exactly two ways, both deliberate:
+
+- **The port in the config is ignored.** A free one is bound instead and
+  `proxy_start` reports the URL it got. Four of eight configs in practice declare
+  `httpPort: 3001`, so honouring it is what made running two of them impossible.
+- **`httpHost` is ignored too**; the listener always binds `127.0.0.1`.
+
+Everything else — destination, `targetUrl`, `defaultHeaders`, `browser`,
+`browserAuthPort`, timeouts, `envFile` interpolation — comes from the config as
+written.
+
+One setting exists only here:
+
+| Setting | Default | What it does |
+|---|---|---|
+| `idleTimeoutMs` (a `proxy_start` argument) | `1800000` (30 min) | Stops a proxy after this long with **nothing in flight**. The countdown runs only while no request is being carried, so an open SSE connection — quiet or not — is never called idle. `0` disables it. A backstop for a client that finished and forgot, not a substitute for `proxy_stop` |
+
+## Troubleshooting
+
+### Server won't start
+
+- Check configuration validation errors in logs
+- Ensure port numbers are valid and not in use
+
+### Proxy requests failing
+
+- Verify the BTP destination (`--btp` or `btpDestination`) matches an existing service key
+- Check network connectivity to the target service
+- Check token expiration errors
+
+### High latency
+
+- Increase `requestTimeout` if requests are timing out
+- Adjust `retryDelay` for faster retries
+