@mcp-abap-adt/proxy 4.1.1 → 5.0.0

package/CHANGELOG.md

@@ -7,6 +7,106 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.0] - 2026-09-26
+
+**The proxy moves onto the new auth family, and its tree holds one copy of each
+contract package.** `npm ls` shows exactly one version each of
+`interfaces-auth` (2.1.0), `interfaces-auth-sap` (1.0.1), `interfaces-network`
+(2.0.0), `auth-providers` (4.2.0) and `auth-stores` (1.2.3).
+
+### Changed
+
+- **BREAKING: Node.js 22 or 24** — `engines: "^22 || ^24"` (was `>=18.2.0`).
+  `@mcp-abap-adt/auth-providers` 3.0.0 requires it, following the versions SAP
+  BTP's Cloud Foundry Node.js buildpack offers.
+
+  **Migrating:** run the proxy on Node 22 or 24. Nothing in its configuration
+  or CLI changed.
+- **`@mcp-abap-adt/auth-broker` `^3.0.0`** (was `^2.2.0`, a major).
+  `BtpProxy` builds its brokers the new way —
+  `new AuthBroker({ serviceKeyStore, sessionStore, provider }, logger)` — with
+  a provider *factory*, so the broker seeds each destination's
+  `AuthorizationCodeProvider` with the refresh token and the access token the
+  session stored. The login is still a browser callback on `browserAuthPort`
+  (default 3333) with a five-minute window; `--browser none` / `headless` still
+  prints the URL instead of opening a browser.
+- **`@mcp-abap-adt/auth-providers` `^4.2.0`** (was `^2.2.2`). The SAML changes
+  of 3.x and 4.x do not reach this package, which builds only
+  `AuthorizationCodeProvider`. A failed browser login is now
+  `BrowserAuthError` (a plain `Error` before).
+- `@mcp-abap-adt/interfaces-auth` `^2.1.0` (was `^1.2.0`),
+  `@mcp-abap-adt/interfaces-auth-sap` `^1.0.1`, `@mcp-abap-adt/auth-stores`
+  `^1.2.3`, `@mcp-abap-adt/header-validator` `^0.3.1`,
+  `@mcp-abap-adt/connection` `^9.3.0` — the releases that accept
+  `interfaces-auth` 2, so none of them carries a private copy of it. None
+  changes an API this package uses.
+- **With `--unsafe`, the session file no longer holds the client secret.**
+  auth-broker 3 writes the token and the refresh token only, and the proxy no
+  longer writes UAA credentials into the session either: with a `targetUrl`
+  it used to put the service key's client ID and secret there — or
+  `placeholder` credentials when it could not find them — through a private
+  broker method. The secret stays in the service key.
+- **With `--unsafe`, the session file keeps its own URL.** The proxy also used
+  to write its `targetUrl` into the destination's session before building the
+  broker, so the broker could resolve a `serviceUrl` an XSUAA service key does
+  not carry. That session is the file `mcp-auth` writes too
+  (`~/.config/mcp-abap-adt/sessions/<destination>.env`), and its `SAP_URL`
+  was replaced by the MCP server's URL. The broker now reads the target URL
+  through `TargetUrlSessionStore`, a wrapper around the session store: reads
+  answer the target URL, writes keep the URL the session already holds, and
+  only a session that does not exist yet is created with the target URL.
+  Measured on the real `AbapSessionStore`: after a token write the file's
+  `SAP_URL` is unchanged.
+- **Auth failures reach the log as the provider raised them.** auth-broker 3
+  no longer rewraps them into `Token provider … error for <destination>`. The
+  reason the standalone proxy prints before exiting is now chosen by error
+  class and `code` through the whole `cause` chain (`ServiceKeyNotFoundError`
+  and `ValidationError` → service key, `ECONNREFUSED` and kin → network), and
+  by message only where nothing typed says more (a login timeout, a UAA
+  refusal).
+
+### Fixed
+
+- **An unreadable service key is reported as what it is.** The stores answer a
+  missing file with `null` and throw only when the file is there and wrong —
+  not valid JSON, not readable. The proxy answered every such throw as "service
+  key not found", with advice to create a file that already existed. The
+  store's error now reaches the caller as raised, naming the file; only `null`
+  means missing. Found in review.
+- **`getAuthorizationHeader` passes the failure on as the same object.** It
+  wrapped it in a new `Error` with the same message, so `instanceof` on the
+  caller's side saw a plain `Error`, whatever the provider or store raised.
+
+- **A missing service key is reported as one again.** The proxy recognised it
+  by the `.env` / `mcp.env` wording of auth-broker 2's message, which 3.0 no
+  longer produces — it would have said only that the session lacks a
+  `serviceUrl`. The proxy now checks the stores itself before building a
+  broker and raises its own `ServiceKeyNotFoundError`, with the same
+  "Service key file not found for destination … Please create service key
+  file: <destination>.json" message as before. It is still not retried.
+- **`npm run test-destination` works.** It imported `XsuaaTokenProvider` and
+  `BtpTokenProvider`, removed from auth-providers long ago, and printed the
+  first 50 characters of the token. It now goes through `BtpProxy` itself and
+  prints the header's length only:
+  `npm run test-destination -- <destination> [--target-url <url>]`.
+
+## [4.2.0] - 2026-09-24
+
+### Added
+
+- **`host` on `proxy_start`**, and the config's `httpHost` is honoured. The
+  default when neither says anything is still `127.0.0.1`.
+
+  It was ignored, on the reasoning that a proxy a model started should not be
+  network-reachable. That reasoning does not hold: loopback is a default, not a
+  boundary — anything with a shell can forward a port, so refusing to bind
+  elsewhere stopped only the honest case. What the default still does is keep a
+  proxy nobody asked to publish from becoming reachable without someone saying
+  so, which is worth a default and not worth a restriction.
+
+  Precedence, most specific first: the `host` argument, the config's `httpHost`,
+  then `127.0.0.1`.
+
 ## [4.1.1] - 2026-09-24
 
 ### Changed

package/README.md

@@ -283,7 +283,7 @@ Create `mcp-proxy-config.json`:
 
 **Session Storage:**
 - `unsafe: false` (default) - Session data stored in-memory (secure, lost on restart)
-- `unsafe: true` - Session data persisted to disk (tokens saved under the session store path)
+- `unsafe: true` - Session data persisted to disk (tokens saved under the session store path): the service URL, the token and the refresh token. The client secret is not copied there; it stays in the service key
 
 See [Configuration Guide](./docs/CONFIGURATION.md) for complete options.
 
@@ -296,7 +296,7 @@ See [Configuration Guide](./docs/CONFIGURATION.md) for complete options.
 
 ## Requirements
 
-- Node.js >= 18.0.0
+- Node.js 22 or 24 (`engines: "^22 || ^24"`, required by `@mcp-abap-adt/auth-providers`)
 - npm >= 9.0.0
 
 ## Testing Tools
@@ -304,7 +304,7 @@ See [Configuration Guide](./docs/CONFIGURATION.md) for complete options.
 Verify a BTP destination's service key and token retrieval:
 
 ```bash
-npm run test-destination
+npm run test-destination -- <destination>
 ```
 
 See [tools/README.md](./tools/README.md) for the available scripts.

package/bin/mcp-abap-adt-proxy-mcp.js

@@ -41,7 +41,8 @@ Tools offered to the client:
                  List the environments — one SAP system's credentials each,
                  from sessions/. Variable NAMES only, never values.
   proxy_start    Start a proxy from a config plus, when the config needs one,
-                 an environment. The config supplies
+                 an environment. Binds 127.0.0.1 unless the config's httpHost or
+                 a host argument says otherwise. The config supplies
                  the destination, target URL, default headers and timeouts;
                  the PORT does not come from it — a free one is bound, so
                  several proxies can run at once, and the URL returned is the

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAgElC;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,CAAW;IAE5B,OAAO,CAAC,iBAAiB,CAAC,CAA+C;IAEzE;;;;;;;OAOG;IACH,OAAO,KAAK,YAAY,GAevB;IACD,OAAO,CAAC,WAAW,CAAS;gBAEhB,eAAe,CAAC,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,MAAM;IAoDlE;;OAEG;IACH,OAAO,CAAC,aAAa;IAMrB;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA2E1B;;OAEG;YACW,eAAe;IAiE7B;;OAEG;YACW,cAAc;IAiV5B;;;;;OAKG;YACW,gBAAgB;IAiC9B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBhC;AAGD,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAqBlC;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,CAAW;IAE5B,OAAO,CAAC,iBAAiB,CAAC,CAA+C;IAEzE;;;;;;;OAOG;IACH,OAAO,KAAK,YAAY,GAevB;IACD,OAAO,CAAC,WAAW,CAAS;gBAEhB,eAAe,CAAC,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,MAAM;IAoDlE;;OAEG;IACH,OAAO,CAAC,aAAa;IAMrB;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA2E1B;;OAEG;YACW,eAAe;IAiE7B;;OAEG;YACW,cAAc;IAiV5B;;;;;OAKG;YACW,gBAAgB;IAiC9B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBhC;AAGD,eAAe,qBAAqB,CAAC"}

package/dist/index.js

@@ -18,6 +18,7 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const requestHandler_js_1 = require("./proxy/requestHandler.js");
 const reverseProxy_js_1 = require("./proxy/reverseProxy.js");
 const config_js_1 = require("./lib/config.js");
+const authFailure_js_1 = require("./lib/authFailure.js");
 const logger_js_1 = require("./lib/logger.js");
 const stores_js_1 = require("./lib/stores.js");
 const transportConfig_js_1 = require("./lib/transportConfig.js");
@@ -33,38 +34,6 @@ function getBodyId(body) {
     }
     return null;
 }
-/**
- * Classify an authentication failure into a human-readable reason so the proxy
- * can report *why* it is exiting (timeout vs bad credentials vs network ...).
- */
-function classifyAuthFailure(error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    if (/timeout/i.test(msg)) {
-        return {
-            category: 'timeout',
-            reason: 'the login URL was not completed in time',
-        };
-    }
-    if (/service key|missing required fields/i.test(msg)) {
-        return {
-            category: 'service-key',
-            reason: 'service key missing or incomplete',
-        };
-    }
-    if (/invalid_client|unauthorized|\b401\b|invalid credentials/i.test(msg)) {
-        return {
-            category: 'credentials',
-            reason: 'invalid credentials — UAA rejected the client',
-        };
-    }
-    if (/ENOTFOUND|ECONNREFUSED|ETIMEDOUT|network|ENETUNREACH/i.test(msg)) {
-        return {
-            category: 'network',
-            reason: 'network error reaching the authentication server',
-        };
-    }
-    return { category: 'other', reason: msg };
-}
 /**
  * MCP ABAP ADT Proxy Server
  */
@@ -564,7 +533,7 @@ Authorization source: ${authSourceObj}`;
         if (this.authExiting)
             return;
         this.authExiting = true;
-        const { category, reason } = classifyAuthFailure(error);
+        const { category, reason } = (0, authFailure_js_1.classifyAuthFailure)(error);
         const detail = error instanceof Error ? error.message : String(error);
         logger_js_1.logger?.error('Authentication not completed — exiting', {
             type: 'AUTH_FATAL_EXIT',

package/dist/lib/authFailure.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Authentication failures: the one the proxy raises itself, and how any of
+ * them is told apart for the message printed before the standalone proxy
+ * exits.
+ */
+/**
+ * No UAA credentials for a destination in either store.
+ *
+ * The proxy's own error, thrown before the broker is asked: auth-broker 3
+ * hands a provider's failure back unchanged and reports a missing service key
+ * only as a missing `serviceUrl`, so matching its message for this case — as
+ * the proxy used to — finds nothing any more. Not retried: a key that is not
+ * there now will not be there in a second.
+ */
+export declare class ServiceKeyNotFoundError extends Error {
+    readonly destination: string;
+    readonly searched: string;
+    readonly code = "SERVICE_KEY_NOT_FOUND";
+    constructor(destination: string, searched?: string);
+}
+export type AuthFailureCategory = 'timeout' | 'credentials' | 'service-key' | 'network' | 'other';
+/**
+ * Classify an authentication failure into a human-readable reason so the proxy
+ * can report *why* it is exiting (timeout vs bad credentials vs network ...).
+ *
+ * By type and `code` first, through the whole `cause` chain: auth-broker 3
+ * passes provider errors on unchanged, so their classes and codes arrive
+ * intact. The message is read only where nothing typed says more — a browser
+ * login's timeout and a UAA refusal are both a plain message inside their
+ * error.
+ */
+export declare function classifyAuthFailure(error: unknown): {
+    category: AuthFailureCategory;
+    reason: string;
+};
+//# sourceMappingURL=authFailure.d.ts.map

package/dist/lib/authFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authFailure.d.ts","sourceRoot":"","sources":["../../src/lib/authFailure.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAI9C,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAJ3B,QAAQ,CAAC,IAAI,2BAA2B;gBAG7B,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,MAA4C;CAYlE;AAED,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,aAAa,GACb,aAAa,GACb,SAAS,GACT,OAAO,CAAC;AA8BZ;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG;IACnD,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB,CA8CA"}

package/dist/lib/authFailure.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Authentication failures: the one the proxy raises itself, and how any of
+ * them is told apart for the message printed before the standalone proxy
+ * exits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceKeyNotFoundError = void 0;
+exports.classifyAuthFailure = classifyAuthFailure;
+const auth_providers_1 = require("@mcp-abap-adt/auth-providers");
+const stores_js_1 = require("./stores.js");
+/**
+ * No UAA credentials for a destination in either store.
+ *
+ * The proxy's own error, thrown before the broker is asked: auth-broker 3
+ * hands a provider's failure back unchanged and reports a missing service key
+ * only as a missing `serviceUrl`, so matching its message for this case — as
+ * the proxy used to — finds nothing any more. Not retried: a key that is not
+ * there now will not be there in a second.
+ */
+class ServiceKeyNotFoundError extends Error {
+    destination;
+    searched;
+    code = 'SERVICE_KEY_NOT_FOUND';
+    constructor(destination, searched = (0, stores_js_1.getPlatformPaths)('service-keys')[0]) {
+        super([
+            `Service key file not found for destination "${destination}".`,
+            `Please create service key file: ${destination}.json`,
+            'Searched in:',
+            `  - ${searched}`,
+        ].join('\n'));
+        this.destination = destination;
+        this.searched = searched;
+        this.name = 'ServiceKeyNotFoundError';
+    }
+}
+exports.ServiceKeyNotFoundError = ServiceKeyNotFoundError;
+const NETWORK_CODES = new Set([
+    'ENOTFOUND',
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ENETUNREACH',
+    'EAI_AGAIN',
+]);
+/** The error and every `cause` behind it, nearest first. */
+function causeChain(error) {
+    const chain = [];
+    let current = error;
+    while (current !== undefined && current !== null && chain.length < 10) {
+        chain.push(current);
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return chain;
+}
+function codeOf(error) {
+    if (error !== null && typeof error === 'object' && 'code' in error) {
+        const { code } = error;
+        return typeof code === 'string' ? code : undefined;
+    }
+    return undefined;
+}
+/**
+ * Classify an authentication failure into a human-readable reason so the proxy
+ * can report *why* it is exiting (timeout vs bad credentials vs network ...).
+ *
+ * By type and `code` first, through the whole `cause` chain: auth-broker 3
+ * passes provider errors on unchanged, so their classes and codes arrive
+ * intact. The message is read only where nothing typed says more — a browser
+ * login's timeout and a UAA refusal are both a plain message inside their
+ * error.
+ */
+function classifyAuthFailure(error) {
+    const chain = causeChain(error);
+    if (chain.some((e) => e instanceof ServiceKeyNotFoundError || e instanceof auth_providers_1.ValidationError)) {
+        return {
+            category: 'service-key',
+            reason: 'service key missing or incomplete',
+        };
+    }
+    if (chain.some((e) => NETWORK_CODES.has(codeOf(e) ?? ''))) {
+        return {
+            category: 'network',
+            reason: 'network error reaching the authentication server',
+        };
+    }
+    const msg = error instanceof Error ? error.message : String(error);
+    if (/timeout|timed out/i.test(msg)) {
+        return {
+            category: 'timeout',
+            reason: 'the login URL was not completed in time',
+        };
+    }
+    if (/service key|missing required fields/i.test(msg)) {
+        return {
+            category: 'service-key',
+            reason: 'service key missing or incomplete',
+        };
+    }
+    if (/invalid_client|unauthorized|\b401\b|invalid credentials/i.test(msg)) {
+        return {
+            category: 'credentials',
+            reason: 'invalid credentials — UAA rejected the client',
+        };
+    }
+    if (/ENOTFOUND|ECONNREFUSED|ETIMEDOUT|network|ENETUNREACH/i.test(msg)) {
+        return {
+            category: 'network',
+            reason: 'network error reaching the authentication server',
+        };
+    }
+    return { category: 'other', reason: msg };
+}

package/dist/mcp/supervisor.d.ts

@@ -35,6 +35,15 @@ export interface StartOptions {
     idleTimeoutMs?: number;
     /** How long a stop waits for requests in flight. See DEFAULT_STOP_GRACE_MS. */
     stopGraceMs?: number;
+    /**
+     * What to bind, ahead of the config's `httpHost` and the loopback default.
+     *
+     * Loopback is a default, not a boundary: anything with a shell can forward a
+     * port, so refusing to bind elsewhere stopped only the honest case. What the
+     * default still does is keep a proxy nobody asked to publish from becoming
+     * reachable without someone saying so.
+     */
+    host?: string;
 }
 export interface StartedInstance {
     instanceId: string;

package/dist/mcp/supervisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/mcp/supervisor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAY,KAAK,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEhF,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,QAAiB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAoBD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAKd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAED,OAAO,EAAE,iBAAiB;IAKjD,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAwG5D,yDAAyD;IACnD,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAiD3D,oCAAoC;IACpC,IAAI,IAAI,eAAe,EAAE;IAIzB;;;;;;;;OAQG;IACH,MAAM,IAAI,cAAc,EAAE;IAI1B;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAkBf;;;;;;;OAOG;YACW,aAAa;IA4B3B,OAAO,CAAC,QAAQ;IAahB;;;OAGG;IACH,OAAO,CAAC,OAAO;IAsBf;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAUtB,wDAAwD;IACxD,OAAO,CAAC,eAAe;CAQxB"}
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/mcp/supervisor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAY,KAAK,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEhF,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,QAAiB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAoBD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAKd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAED,OAAO,EAAE,iBAAiB;IAKjD,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IA2G5D,yDAAyD;IACnD,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAiD3D,oCAAoC;IACpC,IAAI,IAAI,eAAe,EAAE;IAIzB;;;;;;;;OAQG;IACH,MAAM,IAAI,cAAc,EAAE;IAI1B;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAkBf;;;;;;;OAOG;YACW,aAAa;IA4B3B,OAAO,CAAC,QAAQ;IAahB;;;OAGG;IACH,OAAO,CAAC,OAAO;IAsBf;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAUtB,wDAAwD;IACxD,OAAO,CAAC,eAAe;CAQxB"}

package/dist/mcp/supervisor.js

@@ -98,9 +98,11 @@ class ProxySupervisor {
         // filesystem used to reject `start()` while leaving the listener bound, the
         // credential held, the instance in `owned` and no idle timer to ever reach
         // it — a proxy running that nobody had been told about.
+        // Most specific first: this call, then the config, then the default.
+        const host = options.host ?? options.config.httpHost ?? this.host;
         let port;
         try {
-            port = await (0, ports_js_1.listenOnFreePort)(server, this.host);
+            port = await (0, ports_js_1.listenOnFreePort)(server, host);
         }
         catch (error) {
             this.release(facade, server, 'listen failed');
@@ -110,7 +112,7 @@ class ProxySupervisor {
             instanceId,
             name: options.name,
             port,
-            url: `http://${this.host}:${port}`,
+            url: `http://${host}:${port}`,
             destination: options.config.btpDestination ?? '(none)',
             startedAt: new Date().toISOString(),
             server,

package/dist/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEhF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,QAGc,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACjE;AAMD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,eAAe,EAC3B,SAAS,GAAE,MAAyB,EACpC,MAAM,GAAE,MAAyB,GAChC,SAAS,EAAE,CAmMb"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEhF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,QAGc,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACjE;AAMD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,eAAe,EAC3B,SAAS,GAAE,MAAyB,EACpC,MAAM,GAAE,MAAyB,GAChC,SAAS,EAAE,CA0Mb"}

package/dist/mcp/tools.js

@@ -93,6 +93,10 @@ function createProxyTools(supervisor, configDir = (0, configs_js_1.proxyConfigDi
                     .string()
                     .optional()
                     .describe('Name of an environment, as proxy_environments lists it (for example "e19"). Supplies the ${VAR} values the config references. Needed when the config names no envFile of its own — proxy_configs marks those.'),
+                host: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('What to bind. Defaults to 127.0.0.1, or the config\u2019s httpHost when it names one. Use "0.0.0.0" to make the proxy reachable from other machines — say so deliberately, since a started proxy is otherwise local only.'),
                 idleTimeoutMs: zod_1.z
                     .number()
                     .optional()
@@ -108,6 +112,7 @@ function createProxyTools(supervisor, configDir = (0, configs_js_1.proxyConfigDi
                 const started = await supervisor.start({
                     name,
                     config: (0, config_js_1.loadConfig)(file, envFile),
+                    host: args.host,
                     idleTimeoutMs: args.idleTimeoutMs,
                 });
                 return text([

package/dist/proxy/btpProxy.d.ts

@@ -4,8 +4,18 @@
  * For requests with x-sap-destination, proxies to target MCP server
  * with JWT token from auth-broker (XSUAA/BTP)
  */
-import { AuthBroker } from '@mcp-abap-adt/auth-broker';
+import { AuthBroker, type TokenProviderFactory } from '@mcp-abap-adt/auth-broker';
 import { type ProxyConfig } from '../lib/config.js';
+/**
+ * The provider auth-broker builds per destination: an
+ * `AuthorizationCodeProvider` seeded with what the stores hold — the UAA
+ * credentials with the stored refresh token, and the stored access token — so
+ * a session that is still valid, or can be refreshed, needs no browser.
+ *
+ * How the login is conducted is the provider's authorization strategy; the
+ * broker has no say in it any more (its `browser` argument is gone).
+ */
+export declare function authorizationCodeProviderFactory(config: Partial<ProxyConfig>): TokenProviderFactory;
 /**
  * Check if error messages should be written to stderr
  * Only output in verbose mode and not in test environment
@@ -32,10 +42,6 @@ export declare class BtpProxy {
      * If broker doesn't exist in map, creates new one and stores it
      */
     private getOrCreateBtpAuthBroker;
-    /**
-     * Helper to ensure valid serviceUrl in session if override provided
-     */
-    private ensureSessionServiceUrl;
     /**
      * The `Authorization` header value for a destination, or `null` when this
      * credential is not a header at all.
@@ -54,15 +60,6 @@ export declare class BtpProxy {
      * them, so it fails on the first attempt instead of three times slower.
      */
     getAuthorizationHeader(destination: string): Promise<string | null>;
-    /**
-     * Turn the broker's failure into one that names what this proxy needs.
-     *
-     * The broker speaks of `.env` and `mcp.env` because it can be fed either way.
-     * This proxy only ever reads service keys, so passing that message through
-     * told the most common failure — a missing key — to go and create a file that
-     * would be ignored.
-     */
-    private explainAuthFailure;
     dispose(): void;
     /**
      * Get the target service URL for a destination.

package/dist/proxy/btpProxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"btpProxy.d.ts","sourceRoot":"","sources":["../../src/proxy/btpProxy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAgB,MAAM,2BAA2B,CAAC;AAOrE,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA+DhE;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAU3C;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAU;gBAEZ,oBAAoB,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAsC3E;;;OAGG;IACU,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB3D;;;;OAIG;YACW,wBAAwB;IAiGtC;;OAEG;YACW,uBAAuB;IAyFrC;;;;;;;;;;;;;;;;OAgBG;IACG,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA+BzE;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAuBnB,OAAO,IAAI,IAAI;IAKtB;;;OAGG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAexD;;OAEG;WACiB,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;CAuC7E;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAEnB"}
+{"version":3,"file":"btpProxy.d.ts","sourceRoot":"","sources":["../../src/proxy/btpProxy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,UAAU,EAIV,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA8EhE;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAC3B,oBAAoB,CAuBtB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAU3C;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAU;gBAEZ,oBAAoB,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAsC3E;;;OAGG;IACU,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB3D;;;;OAIG;YACW,wBAAwB;IAmDtC;;;;;;;;;;;;;;;;OAgBG;IACG,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkClE,OAAO,IAAI,IAAI;IAKtB;;;OAGG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAexD;;OAEG;WACiB,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;CAkB7E;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAEnB"}

package/dist/proxy/btpProxy.js

@@ -7,10 +7,12 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BtpProxy = void 0;
+exports.authorizationCodeProviderFactory = authorizationCodeProviderFactory;
 exports.shouldWriteStderr = shouldWriteStderr;
 exports.createBtpProxy = createBtpProxy;
 const auth_broker_1 = require("@mcp-abap-adt/auth-broker");
 const auth_providers_1 = require("@mcp-abap-adt/auth-providers");
+const authFailure_js_1 = require("../lib/authFailure.js");
 const config_js_1 = require("../lib/config.js");
 const logger_js_1 = require("../lib/logger.js");
 const stores_js_1 = require("../lib/stores.js");
@@ -49,6 +51,52 @@ const loggerAdapter = {
         : undefined),
 };
 const errorHandler_js_1 = require("../lib/errorHandler.js");
+const targetUrlSessionStore_js_1 = require("./targetUrlSessionStore.js");
+async function requireCredentials(destination, serviceKeyStore, sessionStore) {
+    // A store answers a missing file with null. Anything it throws — a key
+    // that is not valid JSON, a file it may not read — is a different problem
+    // with a different fix, and reaches the caller as the store raised it,
+    // naming the file; answering it as "not found" sent users to create a file
+    // that was already there.
+    const found = (await serviceKeyStore.getAuthorizationConfig(destination)) ??
+        (await sessionStore.getAuthorizationConfig(destination));
+    if (!found) {
+        throw new authFailure_js_1.ServiceKeyNotFoundError(destination);
+    }
+}
+/**
+ * The provider auth-broker builds per destination: an
+ * `AuthorizationCodeProvider` seeded with what the stores hold — the UAA
+ * credentials with the stored refresh token, and the stored access token — so
+ * a session that is still valid, or can be refreshed, needs no browser.
+ *
+ * How the login is conducted is the provider's authorization strategy; the
+ * broker has no say in it any more (its `browser` argument is gone).
+ */
+function authorizationCodeProviderFactory(config) {
+    return (destination, authConfig, connConfig) => {
+        if (!authConfig) {
+            throw new authFailure_js_1.ServiceKeyNotFoundError(destination);
+        }
+        return new auth_providers_1.AuthorizationCodeProvider({
+            authorization: (0, auth_providers_1.browserCallbackStrategy)({
+                browser: config.browser,
+                port: config.browserAuthPort || DEFAULT_BROWSER_AUTH_PORT,
+                timeoutMs: INTERACTIVE_LOGIN_TIMEOUT_MS,
+            }),
+            // Pass a logger so the callback strategy can surface the "Open this
+            // URL" prompt in 'none'/'headless' mode. Without it, the callback
+            // server gets a null logger and silently drops the authorization URL.
+            logger: loggerAdapter,
+            uaaUrl: authConfig.uaaUrl,
+            clientId: authConfig.uaaClientId,
+            clientSecret: authConfig.uaaClientSecret,
+            refreshToken: authConfig.refreshToken,
+            // An empty string is how a session seeded without a token says "none".
+            accessToken: connConfig.authorizationToken || undefined,
+        });
+    };
+}
 /**
  * Check if error messages should be written to stderr
  * Only output in verbose mode and not in test environment
@@ -134,15 +182,15 @@ class BtpProxy {
      * If destination is not provided, returns default broker
      * If broker doesn't exist in map, creates new one and stores it
      */
-    async getOrCreateBtpAuthBroker(destination, targetUrl) {
+    async getOrCreateBtpAuthBroker(destination) {
         // If no destination, use default broker
         if (!destination) {
             return this.defaultBtpAuthBroker;
         }
         // Check if broker exists in map
-        let broker = this.btpAuthBrokers.get(destination);
-        if (broker) {
-            return broker;
+        const existing = this.btpAuthBrokers.get(destination);
+        if (existing) {
+            return existing;
         }
         // Create new broker for this destination
         logger_js_1.logger?.info('Creating new BTP auth broker for destination', {
@@ -150,146 +198,24 @@ class BtpProxy {
             destination,
         });
         const { serviceKeyStore, sessionStore } = await (0, stores_js_1.getPlatformStores)(this.unsafe);
-        // We must manually load the credentials because AuthorizationCodeProvider validates them in constructor
-        let authConfig = null;
-        try {
-            // Try service key store first
-            if (serviceKeyStore) {
-                authConfig = await serviceKeyStore.getAuthorizationConfig(destination);
-            }
-            // If not found, try session store (though less likely for initial setup)
-            if (!authConfig) {
-                authConfig = await sessionStore.getAuthorizationConfig(destination);
-            }
-        }
-        catch (error) {
-            logger_js_1.logger?.warn('Failed to load auth config for provider initialization', {
-                error: error instanceof Error ? error.message : String(error),
-                destination,
-            });
-        }
-        if (!authConfig) {
-            const serviceKeyDir = (0, stores_js_1.getPlatformPaths)('service-keys')[0];
-            logger_js_1.logger?.error('Service key not found for destination', {
-                destination,
-                hint: `Ensure service key file "${destination}.json" exists in ${serviceKeyDir} (override the base dir with AUTH_BROKER_PATH)`,
-            });
-            // We cannot proceed without config, but we'll let it fail with a clear message
-            // Or we could throw here.
-            // If we don't provide config, provider will throw "Missing required fields".
-        }
-        // Always use AuthorizationCodeProvider (enforced)
-        // Map IAuthorizationConfig (uaaClientId) to ProviderConfig (clientId)
-        // How the login is conducted is now a strategy the provider config
-        // carries under `authorization`; the callback port lives inside it.
-        //
-        // uaaUrl/clientId/clientSecret fall back to '' rather than being omitted
-        // when authConfig is missing: AuthorizationCodeProviderConfig declares
-        // them required, and the provider's own constructor already treats an
-        // empty string the same as absent, throwing its "Missing required
-        // fields" ValidationError — which is the clear failure this was always
-        // meant to produce.
-        const providerConfig = {
-            authorization: (0, auth_providers_1.browserCallbackStrategy)({
-                browser: this.config.browser,
-                port: this.config.browserAuthPort || DEFAULT_BROWSER_AUTH_PORT,
-                timeoutMs: INTERACTIVE_LOGIN_TIMEOUT_MS,
-            }),
-            // Pass a logger so the callback strategy can surface the "Open this
-            // URL" prompt in 'none'/'headless' mode. Without it, the callback
-            // server gets a null logger and silently drops the authorization URL.
-            logger: loggerAdapter,
-            uaaUrl: authConfig?.uaaUrl ?? '',
-            clientId: authConfig?.uaaClientId ?? '',
-            clientSecret: authConfig?.uaaClientSecret ?? '',
-        };
-        const tokenProvider = new auth_providers_1.AuthorizationCodeProvider(providerConfig);
-        broker = new auth_broker_1.AuthBroker({
+        // auth-broker reports a missing service key only as a missing
+        // `serviceUrl` — and not at all once a targetUrl is seeded below — so the
+        // proxy asks the stores itself, before anything is written, and fails
+        // with its own error naming the file to create.
+        await requireCredentials(destination, serviceKeyStore, sessionStore);
+        // The broker is told the target URL through the store it reads, not by
+        // writing it into the session: that session may be the file mcp-auth
+        // writes, whose own URL must stay.
+        const targetUrl = this.config.targetUrl;
+        const brokerSessionStore = targetUrl
+            ? new targetUrlSessionStore_js_1.TargetUrlSessionStore(sessionStore, targetUrl)
+            : sessionStore;
+        const broker = new auth_broker_1.AuthBroker({
             serviceKeyStore,
-            sessionStore,
-            tokenProvider,
-        }, this.config.browser, // Pass configured browser (default: 'system')
-        logger_js_1.logger);
+            sessionStore: brokerSessionStore,
+            provider: authorizationCodeProviderFactory(this.config),
+        }, loggerAdapter);
         this.btpAuthBrokers.set(destination, broker);
-        return this.ensureSessionServiceUrl(broker, destination, targetUrl);
-    }
-    /**
-     * Helper to ensure valid serviceUrl in session if override provided
-     */
-    async ensureSessionServiceUrl(broker, destination, targetUrl) {
-        const activeTargetUrl = targetUrl || this.config.targetUrl;
-        if (!activeTargetUrl) {
-            return broker;
-        }
-        try {
-            // Check if current connection config exists
-            const currentConn = await broker.getConnectionConfig(destination);
-            // We need to ensure we have a valid session with BOTH serviceUrl AND auth config.
-            // Even if serviceUrl matches, the auth config might be missing from the session
-            // (which causes ClientCredentialsProvider to fail if initialized with empty config).
-            // Cast to any to access potentially private methods if interface restricted
-            // biome-ignore lint/suspicious/noExplicitAny: Accessing internal methods for safe injection
-            const brokerAny = broker;
-            let authConfig = await broker.getAuthorizationConfig(destination);
-            if (!authConfig) {
-                try {
-                    if (typeof brokerAny.getAuthorizationConfigFromServiceKey === 'function') {
-                        authConfig =
-                            await brokerAny.getAuthorizationConfigFromServiceKey(destination);
-                    }
-                }
-                catch (e) {
-                    logger_js_1.logger?.debug('Could not find auth config for session update', {
-                        error: String(e),
-                    });
-                }
-            }
-            if (!authConfig) {
-                authConfig = {
-                    uaaUrl: 'https://placeholder.authentication.sap.hana.ondemand.com',
-                    uaaClientId: 'placeholder',
-                    uaaClientSecret: 'placeholder',
-                };
-                logger_js_1.logger?.info('Using placeholder auth config for session injection', {
-                    type: 'BTP_SESSION_PLACEHOLDER',
-                    destination,
-                    targetUrl: activeTargetUrl,
-                });
-            }
-            if (authConfig) {
-                const newConn = {
-                    ...(currentConn || {}),
-                    serviceUrl: activeTargetUrl,
-                    authType: 'jwt',
-                    // Map XSUAA keys to ClientCredentialsProvider keys
-                    clientId: authConfig.uaaClientId,
-                    clientSecret: authConfig.uaaClientSecret,
-                    uaaUrl: authConfig.uaaUrl,
-                };
-                if (typeof brokerAny.saveTokenToSession === 'function') {
-                    await brokerAny.saveTokenToSession(destination, newConn, authConfig);
-                    logger_js_1.logger?.info('Injected targetUrl and auth config into BTP session', {
-                        type: 'BTP_SESSION_INJECTION',
-                        destination,
-                        url: activeTargetUrl,
-                        hasClientId: !!newConn.clientId,
-                    });
-                }
-                else {
-                    logger_js_1.logger?.error('saveTokenToSession is not a function on broker', {
-                        type: 'BTP_SESSION_METHOD_MISSING',
-                        keys: Object.keys(brokerAny),
-                    });
-                }
-            }
-        }
-        catch (error) {
-            logger_js_1.logger?.error('Failed to inject targetUrl into session', {
-                type: 'BTP_SESSION_INJECTION_ERROR',
-                destination,
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
         return broker;
     }
     /**
@@ -326,7 +252,10 @@ class BtpProxy {
             }, retryOptions);
         }
         catch (error) {
-            const message = this.explainAuthFailure(error, destination);
+            // Passed on as it stands: auth-broker 3 no longer rewords a provider's
+            // failure, and a missing service key is already this proxy's own
+            // ServiceKeyNotFoundError, which names the file to create.
+            const message = error instanceof Error ? error.message : String(error);
             logger_js_1.logger?.error('Failed to get an authorization header', {
                 type: 'CREDENTIAL_HEADER_ERROR',
                 destination,
@@ -335,36 +264,8 @@ class BtpProxy {
             if (shouldWriteStderr()) {
                 process.stderr.write(`[MCP Proxy] ✗ ${message}\n`);
             }
-            throw new Error(message);
-        }
-    }
-    /**
-     * Turn the broker's failure into one that names what this proxy needs.
-     *
-     * The broker speaks of `.env` and `mcp.env` because it can be fed either way.
-     * This proxy only ever reads service keys, so passing that message through
-     * told the most common failure — a missing key — to go and create a file that
-     * would be ignored.
-     */
-    explainAuthFailure(error, destination) {
-        const original = error instanceof Error ? error.message : String(error);
-        if (!original.includes('.env') && !original.includes('mcp.env')) {
-            return original;
+            throw error;
         }
-        const searched = original.match(/Searched in:\s*([\s\S]*?)(?:\n\n|$)/);
-        const paths = searched
-            ? searched[1]
-                .trim()
-                .split('\n')
-                .map((p) => p.trim().replace(/^-\s*/, ''))
-                .filter(Boolean)
-            : [(0, stores_js_1.storeDir)('service-keys')];
-        return [
-            `Service key file not found for destination "${destination}".`,
-            `Please create service key file: ${destination}.json`,
-            'Searched in:',
-            ...paths.map((p) => `  - ${p}`),
-        ].join('\n');
     }
     dispose() {
         this.credentials.clear();
@@ -396,28 +297,8 @@ class BtpProxy {
         const defaultBtpAuthBroker = new auth_broker_1.AuthBroker({
             serviceKeyStore,
             sessionStore,
-            tokenProvider: new auth_providers_1.AuthorizationCodeProvider({
-                uaaUrl: 'https://placeholder.authentication.sap.hana.ondemand.com',
-                clientId: 'placeholder',
-                clientSecret: 'placeholder',
-                authorization: (0, auth_providers_1.browserCallbackStrategy)({
-                    browser: loadedConfig.browser,
-                    // This call site never had its own fallback: it passed
-                    // `redirectPort` straight through and relied on
-                    // auth-providers@1.2.0 defaulting an omitted value to 3001
-                    // internally — which is this proxy's own default `httpPort`
-                    // (src/lib/config.ts). An omitted `browserAuthPort` therefore
-                    // told the callback server to bind the port the proxy already
-                    // listens on, failing every such login with "Port 3001 is
-                    // already in use". Both call sites now share the one documented
-                    // default instead of leaving this one to an invisible, colliding
-                    // number.
-                    port: loadedConfig.browserAuthPort || DEFAULT_BROWSER_AUTH_PORT,
-                    timeoutMs: INTERACTIVE_LOGIN_TIMEOUT_MS,
-                }),
-                logger: loggerAdapter,
-            }),
-        }, 'none', loggerAdapter);
+            provider: authorizationCodeProviderFactory(loadedConfig),
+        }, loggerAdapter);
         return new BtpProxy(defaultBtpAuthBroker, loadedConfig);
     }
 }

package/dist/proxy/targetUrlSessionStore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A session store that tells the broker the proxy's `targetUrl` without
+ * writing it over the destination's own URL.
+ *
+ * auth-broker 3 refuses a destination whose session and service key both lack
+ * a `serviceUrl`, and an XSUAA service key for a BTP-hosted MCP server usually
+ * carries none: the target URL is what the proxy is told instead. The proxy
+ * used to write it into the session before building the broker — and, with
+ * `unsafe`, that session is the file `mcp-auth` writes too, so its `SAP_URL`
+ * was replaced by the MCP server's URL.
+ *
+ * Reads answer the target URL as the `serviceUrl`. Writes keep the URL the
+ * session already holds; only a session that does not exist yet is created
+ * with the target URL, since a store cannot create one without a URL.
+ * Everything else passes through to the store it wraps.
+ */
+import type { IAuthorizationConfig, IConfig, IConnectionConfig, ISessionStore } from '@mcp-abap-adt/interfaces-auth-sap';
+export declare class TargetUrlSessionStore implements ISessionStore {
+    private readonly inner;
+    private readonly targetUrl;
+    constructor(inner: ISessionStore, targetUrl: string);
+    loadSession(destination: string): Promise<IConfig | null>;
+    getConnectionConfig(destination: string): Promise<IConnectionConfig | null>;
+    getAuthorizationConfig(destination: string): Promise<IAuthorizationConfig | null>;
+    setAuthorizationConfig(destination: string, config: IAuthorizationConfig): Promise<void>;
+    setConnectionConfig(destination: string, config: IConnectionConfig): Promise<void>;
+    saveSession(destination: string, config: IConfig | unknown): Promise<void>;
+    deleteSession(destination: string): Promise<void>;
+    /** The URL the session holds, or the target URL for a session not yet written. */
+    private ownServiceUrl;
+}
+//# sourceMappingURL=targetUrlSessionStore.d.ts.map

package/dist/proxy/targetUrlSessionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targetUrlSessionStore.d.ts","sourceRoot":"","sources":["../../src/proxy/targetUrlSessionStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,OAAO,EACP,iBAAiB,EACjB,aAAa,EACd,MAAM,mCAAmC,CAAC;AAE3C,qBAAa,qBAAsB,YAAW,aAAa;IAEvD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM;IAG9B,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAKzD,mBAAmB,CACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAKpC,sBAAsB,CACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAIvC,sBAAsB,CACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAIV,mBAAmB,CACvB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,IAAI,CAAC;IAOV,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,GAAG,OAAO,GACxB,OAAO,CAAC,IAAI,CAAC;IAOV,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,kFAAkF;YACpE,aAAa;CAI5B"}

package/dist/proxy/targetUrlSessionStore.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * A session store that tells the broker the proxy's `targetUrl` without
+ * writing it over the destination's own URL.
+ *
+ * auth-broker 3 refuses a destination whose session and service key both lack
+ * a `serviceUrl`, and an XSUAA service key for a BTP-hosted MCP server usually
+ * carries none: the target URL is what the proxy is told instead. The proxy
+ * used to write it into the session before building the broker — and, with
+ * `unsafe`, that session is the file `mcp-auth` writes too, so its `SAP_URL`
+ * was replaced by the MCP server's URL.
+ *
+ * Reads answer the target URL as the `serviceUrl`. Writes keep the URL the
+ * session already holds; only a session that does not exist yet is created
+ * with the target URL, since a store cannot create one without a URL.
+ * Everything else passes through to the store it wraps.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TargetUrlSessionStore = void 0;
+class TargetUrlSessionStore {
+    inner;
+    targetUrl;
+    constructor(inner, targetUrl) {
+        this.inner = inner;
+        this.targetUrl = targetUrl;
+    }
+    async loadSession(destination) {
+        const session = await this.inner.loadSession(destination);
+        return session ? { ...session, serviceUrl: this.targetUrl } : null;
+    }
+    async getConnectionConfig(destination) {
+        const connection = await this.inner.getConnectionConfig(destination);
+        return { ...(connection ?? {}), serviceUrl: this.targetUrl };
+    }
+    getAuthorizationConfig(destination) {
+        return this.inner.getAuthorizationConfig(destination);
+    }
+    setAuthorizationConfig(destination, config) {
+        return this.inner.setAuthorizationConfig(destination, config);
+    }
+    async setConnectionConfig(destination, config) {
+        await this.inner.setConnectionConfig(destination, {
+            ...config,
+            serviceUrl: await this.ownServiceUrl(destination),
+        });
+    }
+    async saveSession(destination, config) {
+        await this.inner.saveSession(destination, {
+            ...config,
+            serviceUrl: await this.ownServiceUrl(destination),
+        });
+    }
+    async deleteSession(destination) {
+        await this.inner.deleteSession?.(destination);
+    }
+    /** The URL the session holds, or the target URL for a session not yet written. */
+    async ownServiceUrl(destination) {
+        const stored = await this.inner.getConnectionConfig(destination);
+        return stored?.serviceUrl ?? this.targetUrl;
+    }
+}
+exports.TargetUrlSessionStore = TargetUrlSessionStore;

package/docs/CONFIGURATION.md

@@ -226,7 +226,13 @@ 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`.
+- **`httpHost` is honoured**, and `proxy_start` takes a `host` of its own that
+  wins over it. The default when neither says anything is `127.0.0.1`.
+
+  That default is a default, not a boundary: anything with a shell can forward a
+  port, so refusing to bind elsewhere only stopped the honest case. What it still
+  does is keep a proxy nobody asked to publish from becoming reachable without
+  someone saying so.
 
 Everything else — destination, `targetUrl`, `defaultHeaders`, `browser`,
 `browserAuthPort`, timeouts, `envFile` interpolation — comes from the config as

package/docs/TROUBLESHOOTING.md

@@ -171,16 +171,30 @@ ping cloud-llm-hub.example.com
    better; each attempt logs `RETRY_ATTEMPT`, and the final failure logs
    `CREDENTIAL_HEADER_ERROR` with the reason.
 
-#### Error: "Failed to get JWT token from auth-broker"
+#### Error: "Service key file not found for destination …" (or another token failure)
 
 **Symptoms:**
-- Proxy requests fail
-- Error about JWT token
+- Proxy requests fail, or the standalone proxy exits at startup
+- `CREDENTIAL_HEADER_ERROR` in the log
 
 **Causes:**
-- Service key not found
-- Invalid service key
-- AuthBroker configuration issue
+- Service key not found. The proxy checks for it itself before asking the
+  auth-broker, and says so in these words:
+  ```
+  Service key file not found for destination "sk".
+  Please create service key file: sk.json
+  Searched in:
+    - /home/you/.config/mcp-abap-adt/service-keys
+  ```
+- Invalid or incomplete service key — auth-providers' `ValidationError`, naming
+  the missing fields
+- A browser login that did not complete — auth-providers' `BrowserAuthError`
+  (timeout, the identity provider's refusal, a busy callback port, a browser
+  that would not open)
+
+Since the move to auth-broker 3, the provider's own error reaches the log as
+it was raised; the broker no longer rewraps it into
+`Token provider … error for <destination>`.
 
 **Solutions:**
 
@@ -215,9 +229,9 @@ export AUTH_BROKER_PATH="/custom/path"
 # Sessions will be resolved from /custom/path/sessions
 ```
 
-4. **Test authentication manually:**
+4. **Test authentication manually** — through the proxy's own path:
 ```bash
-npx sap-abap-auth auth -k sk.json
+npm run test-destination -- sk
 ```
 
 ### 3. Routing Issues
@@ -359,16 +373,16 @@ export LOG_LEVEL=debug
 
 **Solutions:**
 
-1. **Token refresh is automatic:**
-   - Proxy detects token expiration
-   - Automatically refreshes token
-   - Retries request with new token
+1. **Token renewal is the credential's, not the proxy's:**
+   - The proxy keeps no token cache; it asks the destination's credential for
+     a header on every request
+   - The auth-broker's provider renews an expired token with the refresh token,
+     or runs the browser login when there is none or it is refused
+   - A 401 from the target is passed back to the client; the proxy does not
+     retry the request
 
-2. **Check token cache:**
-```bash
-# Tokens are cached for 30 minutes
-# On 401/403 the proxy automatically clears the cache and retries with a fresh token
-```
+2. **With `--unsafe`**, the session file holds the service URL, the token and
+   the refresh token — not the client secret, which stays in the service key.
 
 3. **Verify service key:**
 ```bash
@@ -438,8 +452,8 @@ Look for logs like:
 
 Look for logs like:
 ```
-[DEBUG] Retrieved JWT token from auth-broker
-[DEBUG] Using cached JWT token
+[DEBUG] Asking the credential for a header
+[INFO] [AuthBroker] Token saved for sk
 ```
 
 ## Getting Help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/proxy",
-  "version": "4.1.1",
+  "version": "5.0.0",
   "description": "MCP proxy server for SAP ABAP ADT - proxies local requests to cloud-llm-hub with JWT authentication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -63,13 +63,13 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@mcp-abap-adt/auth-broker": "^2.2.0",
-    "@mcp-abap-adt/auth-providers": "^2.2.2",
-    "@mcp-abap-adt/auth-stores": "^1.2.0",
-    "@mcp-abap-adt/connection": "^9.2.1",
-    "@mcp-abap-adt/header-validator": "^0.3.0",
-    "@mcp-abap-adt/interfaces-auth": "^1.2.0",
-    "@mcp-abap-adt/interfaces-auth-sap": "^1.0.0",
+    "@mcp-abap-adt/auth-broker": "^3.0.0",
+    "@mcp-abap-adt/auth-providers": "^4.2.0",
+    "@mcp-abap-adt/auth-stores": "^1.2.3",
+    "@mcp-abap-adt/connection": "^9.3.0",
+    "@mcp-abap-adt/header-validator": "^0.3.1",
+    "@mcp-abap-adt/interfaces-auth": "^2.1.0",
+    "@mcp-abap-adt/interfaces-auth-sap": "^1.0.1",
     "@mcp-abap-adt/interfaces-network": "^2.0.0",
     "@mcp-abap-adt/logger": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
@@ -79,7 +79,7 @@
     "zod": "^4.3.6"
   },
   "engines": {
-    "node": ">=18.2.0",
+    "node": "^22 || ^24",
     "npm": ">=9.0.0"
   },
   "files": [