sap-ai-dev-toolkit 0.4.2 → 0.5.0

package/README.md

@@ -456,9 +456,10 @@ Credentials, cookies, SAP usernames, passwords, and raw BAS destination payloads
 The configuration path is selected in this order:
 
 1. `SAP_AI_DEV_MCP_CONFIG`, when set.
-2. `BAS_VSP_MCP_CONFIG`, when set for compatibility with earlier releases.
-3. An existing MCP user configuration detected automatically.
-4. The default MCP user configuration location.
+2. `SAP_AI_DEV_TOOLKIT_MCP_CONFIG`, when set.
+3. `BAS_VSP_MCP_CONFIG`, when set for compatibility with earlier releases.
+4. An existing MCP user configuration detected automatically.
+5. The default MCP user configuration location.
 
 Set `SAP_AI_DEV_MCP_CONFIG` to use a specific configuration file:
 
@@ -538,7 +539,9 @@ For a transport report, include exactly one `GetTransport` check whose `transpor
 
 For an ABAP Cloud assessment, get object URIs from `SearchObject` and pass them to `PlanABAPCloudMigration`. It reports release evidence; it does not guess replacement APIs. Save the JSON from `GenerateRAPRegressionSuite` and pass it to `RunRAPRegressionSuite` after relevant service changes.
 
-`sap-ai-dev-toolkit --doctor` probes each discovered destination, starts VSP, calls `GetSystemInfo` when available, and lists MCP tools. `--doctor --json` prints redacted results and exits unsuccessfully when a required check fails.
+`sap-ai-dev --doctor` probes each discovered destination, checks that each managed MCP entry still matches its selected BAS destination, starts VSP, lists MCP tools, and preflights `/sap/bc/adt/datapreview/freestyle` through the runtime relay before calling `GetSystemInfo`. It repairs only tagged toolkit-owned BAS entries that can be verified against complete destination discovery; it does not add destinations, remove stale or third-party entries, or overwrite malformed configuration. `--doctor --json` reports redacted session diagnostics (HTTP status, cookie count, retry/fallback counters; never token or cookie values) and exits unsuccessfully when a required check fails.
+
+`tools/list` confirms what this MCP server exposes; it does not prove that VS Code attached the server to the active chat. Start the selected destination in **MCP: List Servers**, enable it in the Chat tools picker, and reload/reselect the agent if the host binding is stale. This add-on cannot inspect or repair another MCP server's registration or a host-wide tool budget.
 
 `sap-ai-dev-toolkit --demo` starts an isolated server with sample ABAP objects, test and ATC results, a sample transport, and synthetic OData metadata and rows. Source edits and transport creation stay in process memory and disappear on exit. The demo does not discover or contact BAS or SAP destinations.
 
@@ -727,29 +730,29 @@ The response contains a `tools` array. A `RunQuery` entry resembles this excerpt
 | `SAP_AI_DEV_TOOLKIT_MODE` | VSP child mode (`expert` by default; `focused` omits `ActivateMultiple`, `GetUserTransports`, and `GetTransportInfo`). The proxy exposes its curated tool subset and local workflow tools, including `LintABAP`. |
 | `SAP_ALLOW_TRANSPORTABLE_EDITS` | Generated MCP entries set this to `true` to permit source edits in transportable packages; VSP safety checks and SAP authorizations still apply. |
 | `SAP_AI_DEV_TOOLKIT_DISABLE_BAS_RELAY=true` | Disable the built-in BAS destination relay. By default the add-on self-heals `.dest` destinations through a local relay that keeps all access destination-based while handling ADT CSRF fetch/retry behavior before VSP calls SAP. |
-| `SAP_AI_DEV_TOOLKIT_HTTP_PROXY` | Egress proxy for relay and discovery traffic (falls back to `HTTP_PROXY`/`http_proxy`; unset means the default BAS proxy for `.dest` hosts, empty means direct except for OnPremise credential overrides, which require a BAS proxy tunnel). |
-| `SAP_AI_DEV_TOOLKIT_MAX_CSRF_RETRIES` | Bounded CSRF/session self-healing retries per unsafe request (default 3). |
+| `SAP_AI_DEV_TOOLKIT_HTTP_PROXY` | Egress proxy for relay and discovery traffic. Takes precedence over `HTTP_PROXY`/`http_proxy`; unset means the default BAS proxy for `.dest` hosts, empty means direct except for OnPremise credential overrides, which require a BAS proxy tunnel. |
+| `SAP_AI_DEV_TOOLKIT_MAX_CSRF_RETRIES` | Bounded retries after explicit CSRF-session rejection per unsafe request (default 3, maximum 10). Invalid values use the default. |
+| `SAP_AI_DEV_MCP_CONFIG` | Explicit MCP configuration path; highest precedence. |
+| `SAP_AI_DEV_TOOLKIT_MCP_CONFIG` | Branded compatibility alias for the MCP configuration path. |
+| `BAS_VSP_MCP_CONFIG` | Backward-compatible alias for the MCP configuration path. |
+| `BAS_VSP_BINARY` | Trusted prebuilt VSP executable; skips Go and binary provisioning. |
+| `BAS_VSP_BINARY_URL` | Alternate VSP binary download URL. |
+| `BAS_VSP_CACHE_DIR` | Binary cache directory. |
+| `GO_BINARY` | Explicit Go executable used for provisioning when automatic Go installation is unavailable. |
+| `SAP_AI_DEV_TOOLKIT_SKIP_PROBE=true` | Skip destination probes; useful for controlled diagnostics or fixtures. |
+| `HTTP_PROXY` / `HTTPS_PROXY` | BAS proxy settings used for destination-list requests, destination probing, and child processes. |
+| `NO_PROXY` | Proxy bypass list for BAS destination-list requests; `.dest` hosts remain routed through the BAS proxy. |
 
 #### Self-healing modes
 
 The relay between the VSP child and each BAS destination recovers from the failure modes that break ADT writes over `.dest` proxies:
 
-1. **CSRF session pairing** — every token is stored together with the `Set-Cookie` state SAP returned alongside it, and both are replayed on POST/PUT/PATCH/DELETE. This fixes `403 CSRF token validation failed` caused by token/session separation.
-2. **Session refresh** — when SAP rejects or rotates a session (401/403 after a token was already accepted), the cached session is dropped, a fresh token+cookie pair is fetched, and the request retried, bounded by the retry limit.
+1. **CSRF session pairing** — a scoped cookie jar retains session cookies received during safe reads and token fetches, applies updates and expirations, and replays the matching token/cookie pair on POST/PUT/PATCH/DELETE. If SAP returns a token without a usable session cookie, the relay fails closed and does not send the unsafe request.
+2. **Session refresh** — when SAP explicitly rejects a CSRF token, the cached session is dropped, a fresh token+cookie pair is fetched, and the request is retried within the configured bound. Generic authorization 401/403 responses are returned without being mislabeled or retried as CSRF failures.
 3. **Proxy tunnel fallback** — when the BAS proxy refuses absolute-form requests (502/504 or transport errors), the relay switches to a CONNECT tunnel through the same proxy and keeps going.
 4. **Child crash recovery** — a crashed VSP child is restarted transparently, re-initialized, tools re-registered, and the interrupted `tools/call` retried once before any error reaches the client.
 5. **Direct connect for Internet destinations** — the BAS `.dest` proxy strips SAP `Set-Cookie` headers, which makes CSRF token/session binding impossible for ADT writes (`403 CSRF token validation failed`). When you select an Internet destination with BasicAuthentication, setup asks whether to override its credentials. A Yes prompts for SAP user/password and stores them in `sap-ai-dev-toolkit-credentials.json` **next to** `mcp.json` (never inside it, permissions `0600`). The relay connects straight to the backend host so cookies survive and ADT writes can use the paired CSRF session.
 6. **Cloud Connector credential overrides** — setup also offers per-destination overrides for BasicAuthentication OnPremise destinations. BAS OnPremise credentials travel through an HTTP CONNECT tunnel to the BAS `.dest` endpoint, retaining its Cloud Connector mapping; setup saves the override only after a read-only probe returns both a CSRF token and a session cookie. If that route check fails, the override is not saved. Cloud Foundry OnPremise overrides replace only the SAP backend user/password; Connectivity service-key authentication and its proxy route remain unchanged. PrincipalPropagation is never overridden. Rerun `sap-ai-dev --setup` to change credentials or answer No to disable a stored override. Deselecting a destination (or selecting none) removes stale overrides.
-| `SAP_AI_DEV_MCP_CONFIG` | Explicit MCP user configuration path. |
-| `BAS_VSP_MCP_CONFIG` | Backward-compatible alias for the MCP user configuration path. |
-| `BAS_VSP_BINARY` | Trusted prebuilt VSP executable; skips Go and binary provisioning. |
-| `BAS_VSP_BINARY_URL` | Alternate VSP binary download URL. |
-| `BAS_VSP_CACHE_DIR` | Binary cache directory. |
-| `GO_BINARY` | Explicit Go executable used for provisioning when automatic Go installation is unavailable. |
-| `SAP_AI_DEV_TOOLKIT_SKIP_PROBE=true` | Skip destination probes; useful for controlled diagnostics or fixtures. |
-| `HTTP_PROXY` / `HTTPS_PROXY` | BAS proxy settings used for destination-list requests, destination probing, and child processes. |
-| `NO_PROXY` | Proxy bypass list for BAS destination-list requests; `.dest` hosts remain routed through the BAS proxy. |
-
 Existing installs that still set the previous `BAS_VSP_*` environment variables remain supported. The setup wizard writes new MCP entries with the `SAP_AI_DEV_TOOLKIT_*` names.
 
 <a id="troubleshooting"></a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",
@@ -12,6 +12,7 @@
     "@modelcontextprotocol/sdk": "1.30.1",
     "@sap/hana-client": "2.30.27",
     "terminal-kit": "^3.1.4",
+    "tough-cookie": "^5.1.2",
     "undici": "^6.21.3",
     "zod": "4.6.5"
   },

package/src/bas-destination-relay.mjs

@@ -1,5 +1,7 @@
 import http from 'node:http';
 import { fetch as undiciFetch, ProxyAgent } from 'undici';
+import { CookieJar } from 'tough-cookie';
+import { brandedEnvValue } from './branding.mjs';
 
 const DEFAULT_PROXY = 'http://127.0.0.1:8887';
 const MAX_BODY_BYTES = 64 * 1024 * 1024;
@@ -14,7 +16,8 @@ const UNSAFE = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 // request. Without this pairing SAP sees a token from a foreign session and
 // answers "CSRF token validation failed" with HTTP 403.
 const TOKEN_TTL_MS = 15 * 60 * 1000;
-const MAX_TOKEN_FAILURES = 3;
+const DEFAULT_MAX_TOKEN_FAILURES = 3;
+const MAX_CONFIGURED_TOKEN_FAILURES = 10;
 const MAX_TUNNEL_FALLBACKS = 2;
 // Carrying a POST's content-length on the token-fetch GET would make the
 // proxy wait for a body that never arrives, so the relay drops body headers.
@@ -63,23 +66,49 @@ function csrfFailure(status, headers, body) {
   );
 }
 
-function authFailure(status) {
-  return status === 401 || status === 403;
+function maxTokenFailures(env, log, destinationName) {
+  const configured = brandedEnvValue(env, 'MAX_CSRF_RETRIES');
+  if (configured === undefined || configured === '') return DEFAULT_MAX_TOKEN_FAILURES;
+  const parsed = Number(configured);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    log(`[${destinationName}] invalid CSRF retry setting; using the default of ${DEFAULT_MAX_TOKEN_FAILURES}`);
+    return DEFAULT_MAX_TOKEN_FAILURES;
+  }
+  return Math.min(parsed, MAX_CONFIGURED_TOKEN_FAILURES);
+}
+
+function copyCookieJar(jar) {
+  return CookieJar.deserializeSync(jar.serializeSync());
 }
 
-function cookieHeader(jar) {
-  return jar.size ? [...jar].map(([name, value]) => `${name}=${value}`).join('; ') : undefined;
+async function cookieHeader(jar, target) {
+  return await jar.getCookieString(target.href) || undefined;
 }
 
-function recordCookies(jar, headers) {
-  for (const value of headers.getSetCookie?.() || []) {
-    const [pair] = String(value).split(';');
+async function seedRequestCookies(jar, requestCookie, target) {
+  for (const pair of String(requestCookie || '').split(';')) {
     const separator = pair.indexOf('=');
     if (separator <= 0) continue;
     const name = pair.slice(0, separator).trim();
+    const value = pair.slice(separator + 1).trim();
     if (!name) continue;
-    if (/expires=thu, 01 jan 1970/i.test(String(value))) jar.delete(name);
-    else jar.set(name, pair.slice(separator + 1).trim());
+    try {
+      await jar.setCookie(`${name}=${value}; Path=/`, target.href, { ignoreError: true });
+    } catch {
+      // Invalid caller-provided cookie fragments are ignored; SAP response
+      // cookies remain authoritative for the destination session.
+    }
+  }
+}
+
+async function recordCookies(jar, headers, target, log, destinationName) {
+  const values = headers.getSetCookie?.() || (headers.get('set-cookie') ? [headers.get('set-cookie')] : []);
+  for (const value of values) {
+    try {
+      await jar.setCookie(String(value), target.href, { ignoreError: true });
+    } catch {
+      log(`[${destinationName}] BAS relay ignored an invalid Set-Cookie header`);
+    }
   }
 }
 
@@ -104,6 +133,16 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
   // must keep the BAS .dest route (and its Cloud Connector mapping), so they
   // use HTTP CONNECT through the BAS proxy instead of credentials.host.
   const directBase = directHost ? new URL(String(directHost)) : null;
+  const cookieBase = directBase || (destination.backendUrl
+    ? new URL(String(destination.backendUrl))
+    : (() => {
+        const target = new URL(base);
+        // BAS .dest URLs are local HTTP routing aliases for SAP backends that
+        // are commonly HTTPS. Use a secure cookie context when BAS metadata
+        // omits the backend URL so Secure session cookies are not discarded.
+        if (target.protocol === 'http:' && /\.dest$/i.test(target.hostname)) target.protocol = 'https:';
+        return target;
+      })());
   if (directBase) log(`[${destination.name}] BAS relay direct connect active (${directBase.origin}); BAS proxy cookie stripping bypassed`);
   if (tunnelMode) log(`[${destination.name}] BAS relay using a BAS proxy tunnel for the OnPremise destination`);
   // Proxy resolution: an explicitly configured proxy wins (an explicit empty
@@ -111,7 +150,8 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
   // imply the default BAS proxy; any other host (tests, direct URLs) is
   // reached directly so the relay never routes loopback traffic through a
   // foreign proxy.
-  const explicitProxy = env.HTTP_PROXY ?? env.http_proxy;
+  const brandedProxy = brandedEnvValue(env, 'HTTP_PROXY');
+  const explicitProxy = brandedProxy !== undefined ? brandedProxy : (env.HTTP_PROXY ?? env.http_proxy);
   const proxyUrl = directBase ? '' : (explicitProxy !== undefined ? String(explicitProxy) : (/\.dest$/i.test(base.hostname) ? DEFAULT_PROXY : ''));
   if (tunnelMode && !proxyUrl) throw new Error('OnPremise credential overrides require the BAS destination proxy to preserve the Cloud Connector route');
   const dispatcher = proxyUrl ? new ProxyAgent({ uri: proxyUrl, proxyTunnel: false }) : undefined;
@@ -121,15 +161,17 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
   const tunnelDispatcher = proxyUrl ? new ProxyAgent({ uri: proxyUrl, proxyTunnel: true }) : undefined;
   let tunneled = tunnelMode;
   // Observable self-healing counters, surfaced by --doctor and tests.
-  const stats = { requests: 0, csrfFetches: 0, csrfRetries: 0, tunnelFallbacks: 0, direct: Boolean(directBase), proxyTunnel: tunnelMode };
-  // Per-path CSRF sessions: { token, jar, fetchedAt } where jar holds the
-  // Set-Cookie state SAP returned together with the token.
+  const stats = { requests: 0, csrfFetches: 0, csrfRetries: 0, csrfSessionFailures: 0, tunnelFallbacks: 0, direct: Boolean(directBase), proxyTunnel: tunnelMode };
+  const maxFailures = maxTokenFailures(env, log, destination.name);
+  // The shared jar captures SAP cookies from safe reads as well as CSRF fetches.
+  // Each cached token gets its own snapshot so later responses cannot silently
+  // pair an old token with a different session.
+  const sharedCookieJar = new CookieJar();
   const tokenCache = new Map();
+  const tokenFetches = new Map();
 
-  function rememberSession(key, token, headers, httpStatus) {
-    const jar = new Map();
-    recordCookies(jar, headers);
-    tokenCache.set(key, { token, jar, fetchedAt: Date.now(), httpStatus });
+  function resolveCookieTarget(target) {
+    return new URL(`${target.pathname}${target.search}`, cookieBase);
   }
 
   async function send(target, method, headers, body) {
@@ -158,23 +200,48 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
     return send(target, method, headers, body);
   }
 
-  async function fetchToken(requestUrl, requestHeaders) {
+  async function fetchTokenFresh(requestUrl, requestHeaders) {
     const key = requestUrl.pathname;
-    const cached = tokenCache.get(key);
-    if (cached && Date.now() - cached.fetchedAt < TOKEN_TTL_MS) return cached;
     stats.csrfFetches += 1;
-    const response = await sendWithFallback(resolveTarget(requestUrl), 'GET', authHeaders(fetchHeaders(requestHeaders, {
+    const target = resolveTarget(requestUrl);
+    const cookieTarget = resolveCookieTarget(target);
+    const jar = copyCookieJar(sharedCookieJar);
+    await seedRequestCookies(jar, requestHeaders.cookie, cookieTarget);
+    const outgoingCookie = await cookieHeader(jar, cookieTarget);
+    const response = await sendWithFallback(target, 'GET', authHeaders(fetchHeaders(requestHeaders, {
       'x-csrf-token': 'Fetch',
       accept: requestHeaders.accept || 'application/xml,*/*',
-      ...(cached?.jar?.size ? { cookie: cookieHeader(cached.jar) } : {})
+      ...(outgoingCookie ? { cookie: outgoingCookie } : {})
     })));
     await response.arrayBuffer().catch(() => undefined);
     const token = response.headers.get('x-csrf-token');
-    if (token && token.toLowerCase() !== 'required') {
-      rememberSession(key, token, response.headers, response.status);
-      return tokenCache.get(key);
+    await recordCookies(jar, response.headers, cookieTarget, log, destination.name);
+    await recordCookies(sharedCookieJar, response.headers, cookieTarget, log, destination.name);
+    const cookies = await jar.getCookies(cookieTarget.href);
+    const session = {
+      token: response.ok && token && token.toLowerCase() !== 'required' ? token : null,
+      jar,
+      fetchedAt: Date.now(),
+      httpStatus: response.status,
+      cookieCount: cookies.length
+    };
+    if (session.token) tokenCache.set(key, session);
+    return session;
+  }
+
+  async function fetchToken(requestUrl, requestHeaders = {}) {
+    const key = requestUrl.pathname;
+    const cached = tokenCache.get(key);
+    if (cached && Date.now() - cached.fetchedAt < TOKEN_TTL_MS) return cached;
+    const pending = tokenFetches.get(key);
+    if (pending) return pending;
+    const fetching = fetchTokenFresh(requestUrl, requestHeaders);
+    tokenFetches.set(key, fetching);
+    try {
+      return await fetching;
+    } finally {
+      if (tokenFetches.get(key) === fetching) tokenFetches.delete(key);
     }
-    return null;
   }
 
   async function probeCsrfSession(path = '/sap/bc/adt/discovery') {
@@ -183,7 +250,8 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
     return {
       httpStatus: session?.httpStatus || 0,
       tokenReceived: Boolean(session?.token),
-      cookieCount: session?.jar?.size || 0
+      cookieCount: session?.cookieCount || 0,
+      sessionUsable: Boolean(session?.token && session.cookieCount > 0)
     };
   }
 
@@ -201,13 +269,19 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
   }
 
   async function forward(method, requestUrl, requestHeaders, body, session) {
+    const target = resolveTarget(requestUrl);
+    const cookieTarget = resolveCookieTarget(target);
+    const cookieJar = session?.jar || sharedCookieJar;
+    if (!session) await seedRequestCookies(cookieJar, requestHeaders.cookie, cookieTarget);
+    const sessionCookie = await cookieHeader(cookieJar, cookieTarget);
     const headers = authHeaders(headersFrom(requestHeaders, {
       ...(session?.token ? { 'x-csrf-token': session.token } : {}),
-      ...(session?.jar?.size ? { cookie: cookieHeader(session.jar) } : {})
+      ...(sessionCookie ? { cookie: sessionCookie } : {})
     }));
-    const response = await sendWithFallback(resolveTarget(requestUrl), method, headers, body);
+    const response = await sendWithFallback(target, method, headers, body);
     const responseBody = Buffer.from(await response.arrayBuffer());
-    if (session) recordCookies(session.jar, response.headers);
+    if (session) await recordCookies(session.jar, response.headers, cookieTarget, log, destination.name);
+    await recordCookies(sharedCookieJar, response.headers, cookieTarget, log, destination.name);
     return { response, body: responseBody };
   }
 
@@ -218,15 +292,28 @@ export function createBasDestinationRelay(destination, { env = process.env, fetc
   async function forwardWithRetry(method, requestUrl, requestHeaders, body, failures = 0) {
     const unsafe = UNSAFE.has(method);
     const session = unsafe ? await fetchToken(requestUrl, requestHeaders) : null;
-    if (unsafe && !session) log(`[${destination.name}] BAS relay could not obtain CSRF token for ${requestUrl.pathname}`);
+    if (unsafe && (!session?.token || !session.cookieCount)) {
+      stats.csrfSessionFailures += 1;
+      const detail = !session?.token
+        ? 'could not obtain a CSRF token'
+        : 'received a CSRF token without a session cookie';
+      const message = `BAS destination relay ${detail} for ${requestUrl.pathname}; no unsafe request was sent`;
+      log(`[${destination.name}] ${message}`);
+      const status = session?.httpStatus >= 400 ? session.httpStatus : 503;
+      const response = new Response(message, { status, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+      return { response, body: Buffer.from(message) };
+    }
     const { response, body: responseBody } = await forward(method, requestUrl, requestHeaders, body, session);
-    const rejected = csrfFailure(response.status, response.headers, responseBody) || (authFailure(response.status) && session);
-    if (unsafe && rejected && failures < MAX_TOKEN_FAILURES) {
-      log(`[${destination.name}] BAS relay CSRF session rejected for ${requestUrl.pathname}; re-establishing token and session (attempt ${failures + 1}/${MAX_TOKEN_FAILURES})`);
+    const rejected = csrfFailure(response.status, response.headers, responseBody);
+    if (unsafe && rejected && failures < maxFailures) {
+      log(`[${destination.name}] BAS relay CSRF session rejected for ${requestUrl.pathname}; re-establishing token and session (attempt ${failures + 1}/${maxFailures})`);
       stats.csrfRetries += 1;
       tokenCache.delete(requestUrl.pathname);
       return forwardWithRetry(method, requestUrl, requestHeaders, body, failures + 1);
     }
+    if (unsafe && rejected && failures >= maxFailures) {
+      log(`[${destination.name}] BAS relay stopped after ${maxFailures} CSRF session retries for ${requestUrl.pathname}`);
+    }
     return { response, body: responseBody };
   }
 

package/src/bas-discovery.mjs

@@ -120,8 +120,9 @@ function proxyBypasses(url, noProxy) {
 
 function proxyDispatcher(target, env) {
   const url = new URL(target);
-  const httpProxy = env.http_proxy ?? env.HTTP_PROXY ?? '';
-  const httpsProxy = env.https_proxy ?? env.HTTPS_PROXY ?? '';
+  const brandedProxy = brandedEnvValue(env, 'HTTP_PROXY');
+  const httpProxy = brandedProxy !== undefined ? String(brandedProxy) : (env.http_proxy ?? env.HTTP_PROXY ?? '');
+  const httpsProxy = brandedProxy !== undefined ? String(brandedProxy) : (env.https_proxy ?? env.HTTPS_PROXY ?? '');
   const proxy = url.protocol === 'https:' ? httpsProxy || httpProxy : httpProxy;
   const noProxy = env.no_proxy ?? env.NO_PROXY ?? '';
   if (!proxy || proxyBypasses(url, noProxy)) return undefined;
@@ -182,7 +183,7 @@ export async function probeADT(destination, options = {}) {
   const url = `${destinationUrl(destination.name)}/sap/bc/adt/discovery`;
   if (options.skipProbe) return { status: 'skipped', available: true, url };
   try {
-    const result = options.probeImpl ? await options.probeImpl(url, options) : await requestProbe(url, options.proxyUrl || DEFAULT_PROXY, options.timeoutMs || 5000);
+    const result = options.probeImpl ? await options.probeImpl(url, options) : await requestProbe(url, options.proxyUrl ?? DEFAULT_PROXY, options.timeoutMs || 5000);
     if ([401, 403].includes(result.status) || (result.status >= 200 && result.status < 300)) return { status: result.status === 401 || result.status === 403 ? 'auth-required' : 'available', available: true, httpStatus: result.status, url };
     if (result.status === 404) return { status: 'not-found', available: false, httpStatus: result.status, url };
     return { status: 'unavailable', available: false, httpStatus: result.status, url };
@@ -198,7 +199,9 @@ export async function discoverDestinations(options = {}) {
   if (!list) throw new Error(`Unrecognized BAS destination response shape; top-level keys: ${Object.keys(body || {}).map(String).join(', ') || '<none>'}`);
   const allow = text(brandedEnvValue(env, 'DESTINATION')).split(',').map(value => value.trim().toLowerCase()).filter(Boolean);
   const normalized = list.map(normalizeDestination).filter(item => item.name).filter(item => !allow.length || allow.includes(item.name.toLowerCase()));
-  const proxyUrl = env.HTTP_PROXY || env.http_proxy || DEFAULT_PROXY;
+  const brandedProxy = brandedEnvValue(env, 'HTTP_PROXY');
+  const configuredProxy = brandedProxy !== undefined ? String(brandedProxy) : (env.HTTP_PROXY ?? env.http_proxy);
+  const proxyUrl = configuredProxy !== undefined ? configuredProxy : DEFAULT_PROXY;
   const skipProbe = String(brandedEnvValue(env, 'SKIP_PROBE') || '').toLowerCase() === 'true' || options.skipProbe;
   const result = [];
   for (const destination of normalized.sort((a, b) => a.name.localeCompare(b.name))) {

package/src/launcher.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { discoverDestinations, remediation, statusRows } from './bas-discovery.mjs';
 import { findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
-import { installMcpConfig } from './mcp-config.mjs';
+import { installMcpConfig, repairManagedMcpConfig } from './mcp-config.mjs';
 import { runSetup } from './setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
 import { withBrandedEnvironment } from './branding.mjs';
@@ -30,7 +30,7 @@ function usage() {
     '  --list-destinations      List discovered BAS destinations',
     '  --list-destinations --json  Print redacted JSON status',
     '  --check                  Probe destination availability',
-    '  --doctor                 Check destination, VSP, SAP, and MCP connectivity',
+    '  --doctor                 Check SAP/MCP connectivity and repair safe toolkit config drift',
     '  --doctor --json          Print redacted JSON diagnostics',
     '  --demo                   Start an isolated, offline SAP MCP playground',
     '  --help, -h               Show this help and exit',
@@ -58,6 +58,20 @@ async function runDoctor(destinations) {
   try { binary = await binaryOrError(); }
   catch (error) { binaryError = error.message; }
 
+
+  try {
+    const repair = await repairManagedMcpConfig(destinations, {
+      env: runtimeEnv,
+      discoveryComplete: true,
+      packageVersion: pkg.version
+    });
+    const detail = repair.skipped
+      ? repair.skipped
+      : `${repair.repaired} managed BAS entr${repair.repaired === 1 ? 'y' : 'ies'} repaired; ${repair.managedEntries || 0} managed BAS entries recognized`;
+    checks.push(doctorRow('-', 'MCP config repair', 'passed', detail));
+  } catch (error) {
+    checks.push(doctorRow('-', 'MCP config repair', 'failed', redactText(error.message || error).slice(0, 300)));
+  }
   for (const destination of destinations) {
     const probe = destination.probe;
     const probeStatus = !probe || probe.status === 'skipped' ? 'skipped' : (probe.available === true ? 'passed' : 'failed');
@@ -78,7 +92,7 @@ async function runDoctor(destinations) {
       checks.push(doctorRow(destination.name, 'VSP MCP startup', 'passed', 'initialized'));
       const relayedDestination = proxy.children[0]?.destination;
       if (relayedDestination?.relay) {
-        checks.push(doctorRow(destination.name, 'BAS destination relay', 'passed', `enabled (${relayedDestination.url}); CSRF token/session pairing active`));
+        checks.push(doctorRow(destination.name, 'BAS destination relay', 'passed', `enabled (${relayedDestination.url}); runtime session preflight pending`));
       } else if (destination.source === 'cloud-foundry') {
         checks.push(doctorRow(destination.name, 'BAS destination relay', 'skipped', 'Cloud Foundry destinations connect through the connectivity proxy directly.'));
       } else if (String(runtimeEnv.SAP_AI_DEV_TOOLKIT_DISABLE_BAS_RELAY || '').toLowerCase() === 'true') {
@@ -96,14 +110,37 @@ async function runDoctor(destinations) {
       const tools = listed.result?.tools || [];
       const localNames = new Set(['LintABAP', 'GetApplicationLog', 'PrepareABAPChangeSet', 'ApplyABAPChangeSet', 'CheckTransportReadiness', 'PlanABAPCloudMigration', 'GenerateRAPRegressionSuite', 'RunRAPRegressionSuite']);
       const upstreamCount = tools.filter(tool => !localNames.has(tool.name.slice(tool.name.indexOf('__') + 2))).length;
-      checks.push(doctorRow(destination.name, 'MCP tools/list', upstreamCount ? 'passed' : 'failed', `${upstreamCount} VSP tools available`));
+      checks.push(doctorRow(destination.name, 'MCP tools/list', upstreamCount ? 'passed' : 'failed', `${upstreamCount} VSP tools and ${tools.length} total MCP tools returned; chat-picker binding is host-managed`));
       const systemInfo = tools.find(tool => tool.name.endsWith('__GetSystemInfo'));
       if (!systemInfo) {
         checks.push(doctorRow(destination.name, 'SAP system check', 'skipped', 'GetSystemInfo is not exposed by this VSP mode.'));
       } else {
-        const inspected = await proxy.handle({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: systemInfo.name, arguments: {} } });
-        const failed = inspected?.error || inspected?.result?.isError;
-        checks.push(doctorRow(destination.name, 'SAP system check', failed ? 'failed' : 'passed', failed ? redactText(inspected?.error?.message || inspected?.result?.content?.[0]?.text || 'GetSystemInfo failed') : 'GetSystemInfo returned successfully'));
+        let sessionReady = true;
+        if (relayedDestination?.relay?.probeCsrfSession) {
+          let session;
+          let preflightError;
+          try {
+            session = await relayedDestination.relay.probeCsrfSession('/sap/bc/adt/datapreview/freestyle');
+          } catch (error) {
+            preflightError = redactText(error.message || error).slice(0, 250);
+          }
+          sessionReady = session?.sessionUsable === true;
+          const status = sessionReady ? 'passed' : 'failed';
+          const stats = relayedDestination.relay.stats || {};
+          const detail = preflightError
+            ? `preflight request failed: ${preflightError}`
+            : `HTTP ${session?.httpStatus || 0}; token=${session?.tokenReceived ? 'received' : 'missing'}; cookies=${session?.cookieCount || 0}; usableSession=${sessionReady}; csrfFetches=${stats.csrfFetches || 0}; csrfRetries=${stats.csrfRetries || 0}; sessionFailures=${stats.csrfSessionFailures || 0}; tunnelFallbacks=${stats.tunnelFallbacks || 0}`;
+          checks.push(doctorRow(destination.name, 'BAS relay CSRF preflight', status, detail));
+          if (!sessionReady) {
+            const remediation = 'GetSystemInfo was not called because the relay could not establish a paired CSRF token/session. For OnPremise BasicAuth, run sap-ai-dev --setup and use a validated BAS proxy tunnel credential override.';
+            checks.push(doctorRow(destination.name, 'SAP system check', 'skipped', preflightError ? `${remediation} Relay error: ${preflightError}` : remediation));
+          }
+        }
+        if (sessionReady) {
+          const inspected = await proxy.handle({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: systemInfo.name, arguments: {} } });
+          const failed = inspected?.error || inspected?.result?.isError;
+          checks.push(doctorRow(destination.name, 'SAP system check', failed ? 'failed' : 'passed', failed ? redactText(inspected?.error?.message || inspected?.result?.content?.[0]?.text || 'GetSystemInfo failed') : 'GetSystemInfo returned successfully'));
+        }
       }
     } catch (error) {
       const detail = redactText(error.message || error).slice(0, 300);

package/src/mcp-config.mjs

@@ -82,7 +82,8 @@ export async function resolveMcpServerCommand(env = process.env) {
 }
 
 export async function resolveMcpConfigPath(env = process.env) {
-  const configuredPath = brandedEnvValue(env, 'MCP_CONFIG');
+  const configuredPath = [env.SAP_AI_DEV_MCP_CONFIG, brandedEnvValue(env, 'MCP_CONFIG')]
+    .find(value => typeof value === 'string' && value.length > 0);
   if (configuredPath) return configuredPath;
   const home = env.HOME || homedir();
   const candidates = [
@@ -204,6 +205,22 @@ function destinationSource(env) {
   return env?.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE ?? env?.BAS_VSP_DESTINATION_SOURCE;
 }
 
+function isManagedBasDestinationEntry(entry) {
+  const currentCommands = new Set(['sap-ai-dev', 'sap-ai-dev-toolkit']);
+  const commandName = typeof entry?.command === 'string'
+    ? entry.command.slice(Math.max(entry.command.lastIndexOf('/'), entry.command.lastIndexOf('\\')) + 1).replace(/\.(?:cmd|exe)$/i, '')
+    : '';
+  const currentCommand = currentCommands.has(entry?.command) || currentCommands.has(commandName);
+  const currentNpxLauncher = entry?.command === 'npx'
+    && Array.isArray(entry.args)
+    && entry.args.some(argument => currentCommands.has(argument))
+    && entry.args.some(argument => typeof argument === 'string' && /^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/.test(argument));
+  return entry?.BAS_EXT === 'true'
+    && (currentCommand || currentNpxLauncher)
+    && typeof destinationValue(entry?.env) === 'string'
+    && destinationSource(entry.env) === undefined;
+}
+
 function collectCloudFoundryKeyReferences(config, managedOnly) {
   const refs = new Map();
   for (const entry of Object.values(config?.servers || {})) {
@@ -292,7 +309,7 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
       && typeof destinationValue(entry?.env) === 'string'
       && (destinationSource(entry.env) === 'cloud-foundry'
         ? typeof entry.env.BAS_CF_DESTINATION_KEY === 'string'
-        : entry.env.BAS_VSP_DESTINATION_SOURCE === undefined);
+        : destinationSource(entry.env) === undefined);
     if (!LEGACY_MCP_SERVER_PREFIXES.some(prefix => name.startsWith(prefix)) && !managed && !isCompanionServer(entry)) servers[name] = entry;
   }
   for (const name of Object.keys(generated)) {
@@ -305,6 +322,53 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
   return { path, servers: generated };
 }
 
+export async function repairManagedMcpConfig(discoveredDestinations, { env = process.env, path, discoveryComplete = false, packageVersion } = {}) {
+  const configPath = path || await resolveMcpConfigPath(env);
+  if (!discoveryComplete) {
+    return { path: configPath, changed: false, repaired: 0, skipped: 'Destination discovery was incomplete.' };
+  }
+  if (!Array.isArray(discoveredDestinations)) throw new Error('Destination discovery result must be an array');
+  const basDestinations = new Map(discoveredDestinations
+    .filter(destination => destination?.source !== 'cloud-foundry' && destination?.name)
+    .map(destination => [String(destination.name), destination]));
+  const config = await readConfig(configPath);
+  const managedEntries = Object.values(config.servers).filter(isManagedBasDestinationEntry).length;
+  if (!basDestinations.size) return { path: configPath, changed: false, repaired: 0, managedEntries };
+  const localCommand = await resolveMcpServerCommand(env);
+  let repaired = 0;
+  for (const [serverName, entry] of Object.entries(config.servers)) {
+    if (!isManagedBasDestinationEntry(entry)) continue;
+    const destinationName = destinationValue(entry.env);
+    if (generatedServerName(destinationName) !== serverName) continue;
+    const destination = basDestinations.get(destinationName);
+    if (!destination) continue;
+    const expected = buildMcpEntries([destination], env)[serverName];
+    const nextEnvironment = { ...entry.env, ...expected.env };
+    if (Object.hasOwn(entry.env, 'SAP_ALLOW_TRANSPORTABLE_EDITS')) {
+      nextEnvironment.SAP_ALLOW_TRANSPORTABLE_EDITS = entry.env.SAP_ALLOW_TRANSPORTABLE_EDITS;
+    }
+    delete nextEnvironment.BAS_VSP_DESTINATION;
+    delete nextEnvironment.BAS_VSP_DESTINATION_SOURCE;
+    const nextEntry = { ...entry, type: 'stdio', env: nextEnvironment, BAS_EXT: 'true' };
+    if (entry.command === 'npx') {
+      if (packageVersion && Array.isArray(entry.args)) {
+        nextEntry.args = entry.args.map(argument => typeof argument === 'string' && /^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/.test(argument)
+          ? `--package=sap-ai-dev-toolkit@${packageVersion}`
+          : argument);
+      }
+    } else {
+      nextEntry.command = localCommand;
+    }
+    if (JSON.stringify(nextEntry) === JSON.stringify(entry)) continue;
+    config.servers[serverName] = nextEntry;
+    repaired += 1;
+  }
+
+  if (!repaired) return { path: configPath, changed: false, repaired: 0, managedEntries };
+  await writeConfig(configPath, config);
+  return { path: configPath, changed: true, repaired, managedEntries };
+}
+
 export async function readMcpConfig(path) {
   return readConfig(path);
 }

package/src/mcp-proxy.mjs

@@ -302,7 +302,10 @@ export class MCPProxy {
             destination = {
               ...originalDestination,
               url: relayUrl,
-              relay: true,
+              relay: {
+                probeCsrfSession: relay.probeCsrfSession,
+                stats: relay.stats
+              },
               async close() {
                 await originalClose?.();
                 await relay.close();

package/test/bas-destination-relay.test.mjs

@@ -11,20 +11,48 @@ const UNSAFE_METHODS = ['POST', 'PUT', 'PATCH', 'DELETE'];
 // request carries BOTH the token and the session cookies that were set
 // together with it. This reproduces the 403 "CSRF token validation failed"
 // seen on the BAS .dest proxy path before the relay paired sessions.
-function sapLikeBackend({ neverAcceptUnsafe = false, rotateOnFetch = false } = {}) {
+function sapLikeBackend({
+  neverAcceptUnsafe = false,
+  rotateOnFetch = false,
+  genericForbidden = false,
+  partialRefreshCookies = false,
+  omitCookies = false,
+  setCookieOnSafeGet = false,
+  secureSessionCookie = false
+} = {}) {
   const state = { sessionCounter: 0, requests: [] };
   const server = http.createServer((req, res) => {
     state.requests.push({ method: req.method, path: req.url, headers: { ...req.headers } });
     if (req.method === 'GET' && req.headers['x-csrf-token'] === 'Fetch') {
       state.sessionCounter += 1;
-      res.writeHead(200, {
-        'x-csrf-token': `token-${state.sessionCounter}`,
-        'set-cookie': [`sap-session-${state.sessionCounter}=s${state.sessionCounter}; path=/`, 'sap-usercontext=sap-client=100; path=/']
-      });
+      const headers = { 'x-csrf-token': `token-${state.sessionCounter}` };
+      if (!omitCookies) {
+        headers['set-cookie'] = [`sap-session-${state.sessionCounter}=s${state.sessionCounter}; path=/`];
+        if (!partialRefreshCookies || state.sessionCounter === 1) {
+          headers['set-cookie'].push('sap-usercontext=sap-client=100; path=/');
+        }
+        if (partialRefreshCookies) {
+          headers['set-cookie'].push(state.sessionCounter === 1
+            ? 'sap-stale=delete-me; path=/'
+            : 'sap-stale=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/');
+        }
+        if (secureSessionCookie) headers['set-cookie'].push('sap-secure=secure-value; Secure; Path=/');
+      }
+      res.writeHead(200, headers);
       res.end('<ok/>');
       return;
     }
+    if (req.method === 'GET' && req.url === '/sap/bc/adt/discovery' && setCookieOnSafeGet) {
+      res.writeHead(200, { 'set-cookie': 'bas-read-session=kept; path=/sap/bc/adt' });
+      res.end('<read/>');
+      return;
+    }
     if (UNSAFE_METHODS.includes(req.method)) {
+      if (genericForbidden) {
+        res.writeHead(403);
+        res.end('User is not authorized to change this object');
+        return;
+      }
       if (neverAcceptUnsafe) {
         res.writeHead(403, { 'x-csrf-token': 'Required' });
         res.end('CSRF token validation failed');
@@ -36,7 +64,11 @@ function sapLikeBackend({ neverAcceptUnsafe = false, rotateOnFetch = false } = {
       // Without rotation any still-live token+cookie pair is accepted; with
       // rotation only the newest issued session remains valid, matching SAP
       // server-side session invalidation.
-      const valid = match && cookie.includes(`sap-session-${match[1]}=`) && (!rotateOnFetch || Number(match[1]) === state.sessionCounter);
+      const valid = match
+        && cookie.includes(`sap-session-${match[1]}=`)
+        && (!rotateOnFetch || Number(match[1]) === state.sessionCounter)
+        && (!partialRefreshCookies || cookie.includes('sap-usercontext=sap-client=100'))
+        && (!partialRefreshCookies || Number(match[1]) === 1 || !cookie.includes('sap-stale='));
       if (!valid) {
         res.writeHead(403, { 'x-csrf-token': 'Required' });
         res.end('CSRF token validation failed');
@@ -79,7 +111,7 @@ async function withBackend(options, handler) {
   const relay = createBasDestinationRelay(
     { name: 'TEST', url: `http://127.0.0.1:${backendPort}`, authentication: 'BasicAuthentication' },
     {
-      env: { HTTP_PROXY: '' },
+      env: { HTTP_PROXY: '', ...(options?.env || {}) },
       fetchImpl: options?.fetchImpl || ((url, init) => globalThis.fetch(url, init)),
       log: message => logs.push(message)
     }
@@ -115,6 +147,30 @@ test('reuses the cached CSRF session for subsequent unsafe requests', async () =
   });
 });
 
+test('coalesces concurrent CSRF token fetches for the same ADT endpoint', async () => {
+  await withBackend(null, async ({ relayUrl, state }) => {
+    const responses = await Promise.all([
+      relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' }),
+      relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<y/>' })
+    ]);
+    assert.deepEqual(responses.map(response => response.status), [201, 201]);
+    assert.equal(state.requests.filter(request => request.headers['x-csrf-token'] === 'Fetch').length, 1);
+    assert.equal(state.requests.filter(request => request.method === 'POST').length, 2);
+  });
+});
+
+test('seeds the relay cookie jar from the incoming MCP request cookie', async () => {
+  await withBackend(null, async ({ relayUrl, state }) => {
+    await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', {
+      method: 'POST',
+      headers: { cookie: 'sap-initial-session=from-vsp' },
+      body: '<x/>'
+    });
+    const tokenFetch = state.requests.find(request => request.headers['x-csrf-token'] === 'Fetch');
+    assert.match(String(tokenFetch.headers.cookie), /sap-initial-session=from-vsp/);
+  });
+});
+
 test('self-heals when SAP rotates the session: refetches token and cookies', async () => {
   await withBackend({ rotateOnFetch: true }, async ({ relay, relayUrl, state }) => {
     // A first POST establishes session token-1. SAP then invalidates it
@@ -129,6 +185,46 @@ test('self-heals when SAP rotates the session: refetches token and cookies', asy
   });
 });
 
+test('merges partial session-cookie updates and applies cookie deletion on refresh', async () => {
+  await withBackend({ rotateOnFetch: true, partialRefreshCookies: true }, async ({ relayUrl, state }) => {
+    await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    state.sessionCounter += 1;
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<y/>' });
+    assert.equal(response.status, 201, `partial cookie refresh must heal, got ${response.status}`);
+    const posts = state.requests.filter(request => request.method === 'POST');
+    assert.match(String(posts[2].headers.cookie), /sap-usercontext=sap-client=100/);
+    assert.doesNotMatch(String(posts[2].headers.cookie), /sap-stale=/);
+  });
+});
+
+test('retains cookies received on a safe GET for later CSRF requests', async () => {
+  await withBackend({ setCookieOnSafeGet: true }, async ({ relayUrl, state }) => {
+    await relayFetch(relayUrl, '/sap/bc/adt/discovery');
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    assert.equal(response.status, 201);
+    const tokenFetch = state.requests.find(request => request.headers['x-csrf-token'] === 'Fetch');
+    assert.match(String(tokenFetch.headers.cookie), /bas-read-session=kept/);
+  });
+});
+
+test('does not retry generic authorization failures as CSRF errors', async () => {
+  await withBackend({ genericForbidden: true }, async ({ relayUrl, relay, state }) => {
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    assert.equal(response.status, 403);
+    assert.equal(state.requests.filter(request => request.method === 'POST').length, 1);
+    assert.equal(relay.stats.csrfRetries, 0);
+  });
+});
+
+test('does not repeat a CSRF failure when SAP returns a token without session cookies', async () => {
+  await withBackend({ omitCookies: true }, async ({ relayUrl, relay, state }) => {
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    assert.equal(response.status, 503, `unsafe calls must fail closed without a paired session, got ${response.status}`);
+    assert.equal(state.requests.filter(request => request.method === 'POST').length, 0);
+    assert.equal(relay.stats.csrfRetries, 0);
+  });
+});
+
 test('stops retrying after bounded attempts and surfaces the failure', async () => {
   await withBackend({ neverAcceptUnsafe: true }, async ({ relay, relayUrl, state }) => {
     const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
@@ -139,6 +235,45 @@ test('stops retrying after bounded attempts and surfaces the failure', async ()
   });
 });
 
+test('honors the configured bounded CSRF retry count', async () => {
+  await withBackend({ neverAcceptUnsafe: true, env: { SAP_AI_DEV_TOOLKIT_MAX_CSRF_RETRIES: '1' } }, async ({ relayUrl, relay, state }) => {
+    const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    assert.equal(response.status, 403);
+    assert.equal(state.requests.filter(request => request.method === 'POST').length, 1 + 1);
+    assert.equal(relay.stats.csrfRetries, 1);
+  });
+});
+
+test('uses the default for invalid retry settings and caps excessive retry counts', async () => {
+  await withBackend({ neverAcceptUnsafe: true, env: { SAP_AI_DEV_TOOLKIT_MAX_CSRF_RETRIES: '1.5' } }, async ({ relayUrl, state }) => {
+    await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    assert.equal(state.requests.filter(request => request.method === 'POST').length, 4, 'invalid values use the default of three retries');
+  });
+  await withBackend({ neverAcceptUnsafe: true, env: { SAP_AI_DEV_TOOLKIT_MAX_CSRF_RETRIES: '100' } }, async ({ relayUrl, state }) => {
+    await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
+    assert.equal(state.requests.filter(request => request.method === 'POST').length, 11, 'retry counts are capped at ten');
+  });
+});
+
+test('prefers the documented branded proxy setting including an explicit direct-connection override', async t => {
+  let dispatchedWithProxy = false;
+  const relay = createBasDestinationRelay(
+    { name: 'TEST', url: 'http://test.dest', authentication: 'BasicAuthentication' },
+    {
+      env: { HTTP_PROXY: 'http://127.0.0.1:1', SAP_AI_DEV_TOOLKIT_HTTP_PROXY: '' },
+      fetchImpl: async (_url, options = {}) => {
+        dispatchedWithProxy = Boolean(options.dispatcher);
+        return new Response('<ok/>', { status: 200, headers: { 'x-csrf-token': 'token', 'set-cookie': 'sap-session=s; path=/' } });
+      }
+    }
+  );
+  t.after(() => relay.close());
+  await relay.ready;
+  const probe = await relay.probeCsrfSession();
+  assert.equal(probe.sessionUsable, true);
+  assert.equal(dispatchedWithProxy, false, 'an explicit empty branded proxy setting means direct traffic');
+});
+
 test('GET requests pass through without CSRF handling', async () => {
   await withBackend(null, async ({ relayUrl, state, relay }) => {
     const response = await relayFetch(relayUrl, '/sap/bc/adt/discovery', { headers: { accept: 'application/xml' } });
@@ -189,7 +324,7 @@ test('falls back to a proxy tunnel when the absolute-form request is refused', a
 });
 
 test('keeps OnPremise Basic auth on a BAS proxy tunnel and verifies the CSRF session', async t => {
-  const { state, server } = sapLikeBackend();
+  const { state, server } = sapLikeBackend({ secureSessionCookie: true });
   const backendPort = await startServer(server);
   const connectTargets = [];
   const proxy = http.createServer();
@@ -224,12 +359,13 @@ test('keeps OnPremise Basic auth on a BAS proxy tunnel and verifies the CSRF ses
   });
 
   const probe = await relay.probeCsrfSession();
-  assert.deepEqual(probe, { httpStatus: 200, tokenReceived: true, cookieCount: 2 });
+  assert.deepEqual(probe, { httpStatus: 200, tokenReceived: true, cookieCount: 3, sessionUsable: true });
   const response = await relayFetch(relayUrl, '/sap/bc/adt/oo/classes', { method: 'POST', body: '<x/>' });
   assert.equal(response.status, 201, `expected a paired CSRF session, got ${response.status}: ${response.body}`);
   const post = state.requests.find(request => request.method === 'POST');
   assert.match(post.headers.authorization, /^Basic /);
   assert.match(String(post.headers.cookie), /sap-session-\d+=/);
+  assert.match(String(post.headers.cookie), /sap-secure=secure-value/, 'Secure SAP cookies must be sent through the HTTPS-backed BAS .dest route');
   assert.ok(connectTargets.length >= 2);
   assert.ok(connectTargets.every(target => target === 'cc-system.dest:80'));
   assert.equal(relay.stats.direct, false);

package/test/discovery.test.mjs

@@ -158,6 +158,35 @@ test('probes .dest only through configured HTTP proxy and accepts proxy-auth res
   assert.deepEqual(requests, [{ host: 'proxy-system.dest', path: 'http://proxy-system.dest/sap/bc/adt/discovery' }]);
 });
 
+test('uses the documented branded HTTP proxy for destination probes and respects explicit direct mode', async t => {
+  const requests = [];
+  const proxy = createServer((request, response) => {
+    requests.push({ host: request.headers.host, path: request.url });
+    response.writeHead(200);
+    response.end('<ok/>');
+  });
+  await new Promise(resolve => proxy.listen(0, '127.0.0.1', resolve));
+  t.after(() => new Promise(resolve => proxy.close(resolve)));
+  const proxyUrl = `http://127.0.0.1:${proxy.address().port}`;
+  const found = await discoverDestinations({
+    body: [{ Name: 'branded-proxy-system' }],
+    env: { HTTP_PROXY: 'http://127.0.0.1:1', SAP_AI_DEV_TOOLKIT_HTTP_PROXY: proxyUrl }
+  });
+  assert.equal(found[0].probe.status, 'available');
+  assert.deepEqual(requests, [{ host: 'branded-proxy-system.dest', path: 'http://branded-proxy-system.dest/sap/bc/adt/discovery' }]);
+
+  const direct = await discoverDestinations({
+    body: [{ Name: 'direct-system' }],
+    env: { HTTP_PROXY: proxyUrl, SAP_AI_DEV_TOOLKIT_HTTP_PROXY: '' },
+    probeImpl: async (_url, options) => {
+      assert.equal(options.proxyUrl, '', 'explicit empty branded proxy must bypass the configured proxy');
+      return { status: 200 };
+    }
+  });
+  assert.equal(direct[0].probe.status, 'available');
+  assert.equal(requests.length, 1);
+});
+
 test('fetches BAS destination lists through configured HTTP and HTTPS proxies', async t => {
   const proxyRequests = [];
   const directRequests = [];
@@ -202,6 +231,26 @@ test('fetches BAS destination lists through configured HTTP and HTTPS proxies',
   assert.equal(proxyRequests.length, 2);
 });
 
+test('branded HTTP proxy takes precedence over HTTPS_PROXY for secure BAS discovery', async () => {
+  let capturedDispatcher = 'not-called';
+  const body = await fetchDestinationList('https://bas.example', {
+    env: {
+      SAP_AI_DEV_TOOLKIT_HTTP_PROXY: '',
+      HTTPS_PROXY: 'http://127.0.0.1:1',
+      https_proxy: 'http://127.0.0.1:1'
+    },
+    fetchImpl: async (_url, options) => {
+      capturedDispatcher = options.dispatcher;
+      return new Response(JSON.stringify([{ Name: 'secure-system' }]), {
+        status: 200,
+        headers: { 'content-type': 'application/json' }
+      });
+    }
+  });
+  assert.deepEqual(body, [{ Name: 'secure-system' }]);
+  assert.equal(capturedDispatcher, undefined, 'explicit branded empty proxy must disable inherited HTTPS_PROXY too');
+});
+
 test('redacts credential-bearing diagnostics without exposing payloads', () => {
   const value = redact({ name: 'dev', password: 'secret', authorization: 'Bearer abc', nested: { cookie: 'x', ok: 'visible' } });
   assert.deepEqual(value, { name: 'dev', password: '[redacted]', authorization: '[redacted]', nested: { cookie: '[redacted]', ok: 'visible' } });

package/test/fixtures/fake-vsp.mjs

@@ -9,22 +9,31 @@ const destination = url.replace(/^https?:\/\//, '').replace(/\.dest$/, '');
 const logPath = process.env.FAKE_LOG;
 function log(entry) { if (logPath) appendFileSync(logPath, `${JSON.stringify({ destination, ...entry })}\n`); }
 function reply(id, result) { process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`); }
-function requestADTThroughProxy(targetUrl, proxyUrl) {
+function requestADTThroughProxy(targetUrl, proxyUrl, { method = 'GET', body = '', bypassProxyForLoopback = false } = {}) {
   const target = new URL(targetUrl);
   const proxy = new URL(proxyUrl);
   if (target.protocol !== 'http:') throw new Error('fixture ADT request supports HTTP only');
   const headers = { host: target.host, accept: 'application/xml,text/xml,*/*' };
+  if (body) headers['content-type'] = 'application/xml';
   if (process.env.SAP_USER && process.env.SAP_PASSWORD) {
     headers.authorization = `Basic ${Buffer.from(`${process.env.SAP_USER}:${process.env.SAP_PASSWORD}`).toString('base64')}`;
   }
+  const loopback = bypassProxyForLoopback && ['127.0.0.1', 'localhost'].includes(target.hostname);
   return new Promise((resolve, reject) => {
-    const request = httpRequest({
+    const requestOptions = loopback ? {
+      hostname: target.hostname,
+      port: Number(target.port),
+      method,
+      path: `${target.pathname}${target.search}`,
+      headers
+    } : {
       hostname: proxy.hostname,
       port: Number(proxy.port),
-      method: 'GET',
+      method,
       path: target.href,
       headers
-    }, response => {
+    };
+    const request = httpRequest(requestOptions, response => {
       let body = '';
       response.setEncoding('utf8');
       response.on('data', chunk => { body += chunk; });
@@ -32,6 +41,7 @@ function requestADTThroughProxy(targetUrl, proxyUrl) {
     });
     request.setTimeout(5_000, () => request.destroy(new Error('fixture ADT request timed out')));
     request.on('error', reject);
+    if (body) request.write(body);
     request.end();
   });
 }
@@ -234,6 +244,15 @@ process.stdin.on('data', async chunk => {
         } catch {
           reply(message.id, { content: [{ type: 'text', text: 'fixture ADT request failed' }], isError: true });
         }
+      } else if (process.env.FAKE_RELAY_CSRF_TEST === 'true' && name === 'GetSystemInfo') {
+        try {
+          const target = new URL('/sap/bc/adt/datapreview/freestyle', url);
+          const proxy = process.env.HTTP_PROXY || process.env.http_proxy;
+          const adt = await requestADTThroughProxy(target.href, proxy, { method: 'POST', body: '<probe/>', bypassProxyForLoopback: true });
+          reply(message.id, { content: [{ type: 'text', text: `fixture ADT HTTP ${adt.status}: ${adt.body}` }], isError: adt.status < 200 || adt.status >= 300 });
+        } catch {
+          reply(message.id, { content: [{ type: 'text', text: 'fixture ADT write failed' }], isError: true });
+        }
       } else {
         reply(message.id, { content: [{ type: 'text', text: `${destination}:${name}` }], isError: false });
       }

package/test/launcher.test.mjs

@@ -134,6 +134,152 @@ test('doctor reports missing BAS configuration as redacted JSON', async () => {
   });
 });
 
+test('doctor preflights the failing ADT endpoint through the runtime relay and repairs its owned config', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'bas-doctor-csrf-'));
+  const configPath = join(directory, 'mcp.json');
+  const config = {
+    servers: {
+      'doctor-system': {
+        type: 'stdio',
+        command: 'sap-ai-dev',
+        env: {
+          H2O_URL: 'http://stale-bas.example',
+          SAP_AI_DEV_TOOLKIT_DESTINATION: 'doctor-system'
+        },
+        BAS_EXT: 'true'
+      },
+      ActionS4D_100: { type: 'stdio', command: 'third-party' }
+    }
+  };
+  await writeFile(configPath, JSON.stringify(config));
+  const requests = [];
+  const server = createServer((request, response) => {
+    let requestPath;
+    try { requestPath = new URL(request.url, `http://${request.headers.host}`).pathname; }
+    catch { requestPath = request.url; }
+    requests.push({ method: request.method, path: requestPath, csrf: request.headers['x-csrf-token'], cookie: request.headers.cookie });
+    if (request.url === '/api/listDestinations') {
+      response.setHeader('content-type', 'application/json');
+      response.end(JSON.stringify([{
+        Name: 'doctor-system',
+        WebIDEEnabled: true,
+        'HTML5.DynamicDestination': true,
+        WebIDEUsage: 'dev_abap',
+        Authentication: 'BasicAuthentication'
+      }]));
+      return;
+    }
+    if (requestPath === '/sap/bc/adt/datapreview/freestyle') {
+      if (request.method === 'GET' && request.headers['x-csrf-token'] === 'Fetch') {
+        response.writeHead(200, {
+          'x-csrf-token': 'doctor-token',
+          'set-cookie': 'sap-session=doctor-session; Path=/'
+        });
+        response.end('<ok/>');
+        return;
+      }
+      if (request.method === 'POST'
+        && request.headers['x-csrf-token'] === 'doctor-token'
+        && String(request.headers.cookie).includes('sap-session=doctor-session')) {
+        response.writeHead(200);
+        response.end('<written/>');
+        return;
+      }
+      response.writeHead(403, { 'x-csrf-token': 'Required' });
+      response.end('CSRF token validation failed');
+      return;
+    }
+    response.writeHead(200);
+    response.end('<ok/>');
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  t.after(async () => {
+    await new Promise(resolve => server.close(resolve));
+    await rm(directory, { recursive: true, force: true });
+  });
+  const proxy = `http://127.0.0.1:${server.address().port}`;
+  const result = await runLauncher(['--doctor', '--json'], {
+    ...process.env,
+    SAP_AI_DEV_TOOLKIT_BINARY: fakeVsp,
+    FAKE_RELAY_CSRF_TEST: 'true',
+    SAP_AI_DEV_MCP_CONFIG: configPath,
+    SAP_AI_DEV_TOOLKIT_DESTINATION: 'doctor-system',
+    H2O_URL: `http://127.0.0.1:${server.address().port}`,
+    HTTP_PROXY: proxy,
+    http_proxy: proxy,
+    NO_PROXY: '127.0.0.1,localhost',
+    no_proxy: '127.0.0.1,localhost'
+  });
+  assert.equal(result.code, 0, `${result.stdout}\n${result.stderr}`);
+  const report = JSON.parse(result.stdout);
+  assert.equal(report.ok, true);
+  assert.ok(report.checks.some(check => check.stage === 'BAS relay CSRF preflight' && check.status === 'passed'));
+  assert.ok(report.checks.some(check => check.stage === 'SAP system check' && check.status === 'passed'));
+  assert.ok(report.checks.some(check => check.stage === 'MCP config repair' && check.status === 'passed' && /1 managed BAS entry repaired/.test(check.detail)));
+  assert.ok(report.checks.some(check => check.stage === 'MCP tools/list' && /total MCP tools returned; chat-picker binding is host-managed/.test(check.detail)));
+  assert.ok(requests.some(request => request.method === 'GET' && request.path === '/sap/bc/adt/datapreview/freestyle' && request.csrf === 'Fetch'));
+  assert.ok(requests.some(request => request.method === 'POST' && request.path === '/sap/bc/adt/datapreview/freestyle' && request.csrf === 'doctor-token' && String(request.cookie).includes('sap-session=doctor-session')));
+  const repairedConfig = JSON.parse(await readFile(configPath, 'utf8'));
+  assert.equal(repairedConfig.servers['doctor-system'].env.H2O_URL, `http://127.0.0.1:${server.address().port}`);
+  assert.deepEqual(repairedConfig.servers.ActionS4D_100, config.servers.ActionS4D_100);
+});
+
+test('doctor stops before GetSystemInfo when the runtime CSRF preflight has no session cookie', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'bas-doctor-csrf-missing-cookie-'));
+  const configPath = join(directory, 'mcp.json');
+  await writeFile(configPath, JSON.stringify({ servers: {} }));
+  const requests = [];
+  const server = createServer((request, response) => {
+    let requestPath;
+    try { requestPath = new URL(request.url, `http://${request.headers.host}`).pathname; }
+    catch { requestPath = request.url; }
+    requests.push({ method: request.method, path: requestPath, csrf: request.headers['x-csrf-token'] });
+    if (request.url === '/api/listDestinations') {
+      response.setHeader('content-type', 'application/json');
+      response.end(JSON.stringify([{
+        Name: 'doctor-system',
+        WebIDEEnabled: true,
+        'HTML5.DynamicDestination': true,
+        WebIDEUsage: 'dev_abap',
+        Authentication: 'BasicAuthentication'
+      }]));
+      return;
+    }
+    if (requestPath === '/sap/bc/adt/datapreview/freestyle') {
+      response.writeHead(200, { 'x-csrf-token': 'orphan-token' });
+      response.end('<ok/>');
+      return;
+    }
+    response.writeHead(200);
+    response.end('<ok/>');
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  t.after(async () => {
+    await new Promise(resolve => server.close(resolve));
+    await rm(directory, { recursive: true, force: true });
+  });
+  const proxy = `http://127.0.0.1:${server.address().port}`;
+  const result = await runLauncher(['--doctor', '--json'], {
+    ...process.env,
+    SAP_AI_DEV_TOOLKIT_BINARY: fakeVsp,
+    FAKE_RELAY_CSRF_TEST: 'true',
+    SAP_AI_DEV_MCP_CONFIG: configPath,
+    SAP_AI_DEV_TOOLKIT_DESTINATION: 'doctor-system',
+    H2O_URL: `http://127.0.0.1:${server.address().port}`,
+    HTTP_PROXY: proxy,
+    http_proxy: proxy,
+    NO_PROXY: '127.0.0.1,localhost',
+    no_proxy: '127.0.0.1,localhost'
+  });
+  assert.equal(result.code, 1);
+  const report = JSON.parse(result.stdout);
+  assert.equal(report.ok, false);
+  assert.ok(report.checks.some(check => check.stage === 'BAS relay CSRF preflight' && check.status === 'failed' && /cookies=0; usableSession=false/.test(check.detail)));
+  assert.ok(report.checks.some(check => check.stage === 'SAP system check' && check.status === 'skipped' && /validated BAS proxy tunnel credential override/.test(check.detail)));
+  assert.equal(requests.some(request => request.method === 'GET' && request.path === '/sap/bc/adt/datapreview/freestyle' && request.csrf === 'Fetch'), true);
+  assert.equal(requests.some(request => request.method === 'POST' && request.path === '/sap/bc/adt/datapreview/freestyle'), false, 'doctor must not call GetSystemInfo after a failed preflight');
+});
+
 test('list-destinations JSON is redacted and probes through the BAS proxy', async () => {
   const requests = [];
   const server = createServer((request, response) => {

package/test/mcp-config-cf.test.mjs

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { buildMcpEntries, buildSapDevelopmentMcpEntries, collectCloudFoundryKeyReferencesFromAllEntries, collectManagedCloudFoundryKeyReferences, installMcpConfig, readMcpConfig } from '../src/mcp-config.mjs';
+import { buildMcpEntries, buildSapDevelopmentMcpEntries, collectCloudFoundryKeyReferencesFromAllEntries, collectManagedCloudFoundryKeyReferences, installMcpConfig, readMcpConfig, repairManagedMcpConfig, resolveMcpConfigPath } from '../src/mcp-config.mjs';
 
 const bas = {
   source: 'bas', name: 'shared', serverName: 'shared', url: 'http://shared.dest',
@@ -78,6 +78,134 @@ test('stores and reconciles the MCP launcher executable location', async t => {
   assert.deepEqual(Object.keys((await readMcpConfig(path)).servers), ['userServer']);
 });
 
+test('resolves documented, toolkit, and legacy MCP config paths in order', async () => {
+  assert.equal(await resolveMcpConfigPath({
+    SAP_AI_DEV_MCP_CONFIG: '/tmp/documented-mcp.json',
+    SAP_AI_DEV_TOOLKIT_MCP_CONFIG: '/tmp/toolkit-mcp.json',
+    BAS_VSP_MCP_CONFIG: '/tmp/legacy-mcp.json'
+  }), '/tmp/documented-mcp.json');
+  assert.equal(await resolveMcpConfigPath({
+    SAP_AI_DEV_TOOLKIT_MCP_CONFIG: '/tmp/toolkit-mcp.json',
+    BAS_VSP_MCP_CONFIG: '/tmp/legacy-mcp.json'
+  }), '/tmp/toolkit-mcp.json');
+  assert.equal(await resolveMcpConfigPath({ BAS_VSP_MCP_CONFIG: '/tmp/legacy-mcp.json' }), '/tmp/legacy-mcp.json');
+});
+
+test('doctor repair updates only discovered toolkit BAS entries and is idempotent', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'sap-ai-toolkit-doctor-repair-'));
+  const path = join(directory, 'mcp.json');
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const cf = cfDestination('space-one', 'instance-one', 'cf-key');
+  const strictDestination = { ...bas, name: 'strict', serverName: 'strict', url: 'http://strict.dest' };
+  const managed = buildMcpEntries([bas], { H2O_URL: 'http://old-h2o.example' }).shared;
+  const strictManaged = buildMcpEntries([strictDestination], { H2O_URL: 'http://old-h2o.example' }).strict;
+  const cfEntry = buildMcpEntries([cf], { H2O_URL: 'http://cf-h2o.example' })[cf.serverName];
+  const companion = buildSapDevelopmentMcpEntries(['sap-fiori-tools'])['sap-fiori-tools'];
+  const unrelated = { type: 'stdio', command: 'external-server' };
+  const unverifiedManaged = {
+    ...managed,
+    env: { ...managed.env, SAP_AI_DEV_TOOLKIT_DESTINATION: 'temporarily-unavailable' }
+  };
+  const config = {
+    userFlag: true,
+    servers: {
+      shared: { ...managed, env: { ...managed.env, H2O_URL: 'http://old-h2o.example' } },
+      strict: { ...strictManaged, env: { ...strictManaged.env, SAP_ALLOW_TRANSPORTABLE_EDITS: 'false' } },
+      'temporarily-unavailable': unverifiedManaged,
+      [cf.serverName]: cfEntry,
+      'sap-fiori-tools': companion,
+      ActionS4D_100: unrelated
+    }
+  };
+  await writeFile(path, JSON.stringify(config, null, 2));
+
+  const first = await repairManagedMcpConfig([bas, strictDestination], { env: { H2O_URL: 'http://current-h2o.example' }, path, discoveryComplete: true });
+  assert.equal(first.changed, true);
+  assert.equal(first.repaired, 2);
+  const repaired = await readMcpConfig(path);
+  assert.equal(repaired.userFlag, true);
+  assert.equal(repaired.servers.shared.env.H2O_URL, 'http://current-h2o.example');
+  assert.equal(repaired.servers.shared.env.SAP_ALLOW_TRANSPORTABLE_EDITS, 'true');
+  assert.equal(repaired.servers.strict.env.SAP_ALLOW_TRANSPORTABLE_EDITS, 'false', "doctor must preserve a user's restricted write setting");
+  assert.deepEqual(repaired.servers['temporarily-unavailable'], unverifiedManaged);
+  assert.deepEqual(repaired.servers[cf.serverName], cfEntry);
+  assert.deepEqual(repaired.servers['sap-fiori-tools'], companion);
+  assert.deepEqual(repaired.servers.ActionS4D_100, unrelated);
+  assert.equal(repaired.servers.newDestination, undefined, 'repair must not add unselected destinations');
+
+  const beforeSecondRepair = await readFile(path, 'utf8');
+  const second = await repairManagedMcpConfig([bas, strictDestination], { env: { H2O_URL: 'http://current-h2o.example' }, path, discoveryComplete: true });
+  assert.equal(second.changed, false);
+  assert.equal(second.repaired, 0);
+  assert.equal(await readFile(path, 'utf8'), beforeSecondRepair, 'an already-healed config must not be rewritten');
+});
+
+test('doctor repair leaves malformed config untouched', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'sap-ai-toolkit-doctor-repair-invalid-'));
+  const path = join(directory, 'mcp.json');
+  const malformed = '{ "servers": ';
+  await writeFile(path, malformed);
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  await assert.rejects(
+    () => repairManagedMcpConfig([bas], { env: { H2O_URL: 'http://h2o.example' }, path, discoveryComplete: true }),
+    /invalid JSON/
+  );
+  assert.equal(await readFile(path, 'utf8'), malformed);
+});
+
+test('doctor repair skips config changes if destination discovery is incomplete', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'sap-ai-toolkit-doctor-repair-incomplete-'));
+  const path = join(directory, 'mcp.json');
+  const entry = buildMcpEntries([bas], { H2O_URL: 'http://old-h2o.example' }).shared;
+  const initial = JSON.stringify({ servers: { shared: entry } });
+  await writeFile(path, initial);
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const result = await repairManagedMcpConfig([bas], { env: { H2O_URL: 'http://new-h2o.example' }, path });
+  assert.equal(result.changed, false);
+  assert.match(result.skipped, /incomplete/);
+  assert.equal(await readFile(path, 'utf8'), initial);
+});
+
+test('doctor repair refreshes stale toolkit launchers without changing npx behavior', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'sap-ai-toolkit-doctor-launcher-repair-'));
+  const path = join(directory, 'mcp.json');
+  const bin = join(directory, 'bin');
+  await import('node:fs/promises').then(({ mkdir }) => mkdir(bin));
+  const command = join(bin, 'sap-ai-dev');
+  await writeFile(command, '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const npx = {
+    ...buildMcpEntries([bas], { H2O_URL: 'http://old-h2o.example' }).shared,
+    command: 'npx',
+    args: ['--yes', '--package=sap-ai-dev-toolkit@0.4.2', 'sap-ai-dev'],
+    env: {
+      ...buildMcpEntries([bas], { H2O_URL: 'http://old-h2o.example' }).shared.env,
+      SAP_AI_DEV_TOOLKIT_DESTINATION: 'shared',
+      OPERATOR_SETTING: 'preserve'
+    }
+  };
+  const direct = {
+    ...buildMcpEntries([bas], { H2O_URL: 'http://old-h2o.example' }).shared,
+    command: 'stale-sap-ai-dev'
+  };
+  await writeFile(path, JSON.stringify({ servers: { shared: npx, other: { ...direct, env: { ...direct.env, SAP_AI_DEV_TOOLKIT_DESTINATION: 'other' } }, userServer: { command: 'other' } } }));
+
+  const result = await repairManagedMcpConfig([bas], {
+    env: { H2O_URL: 'http://current-h2o.example', PATH: bin },
+    path,
+    discoveryComplete: true,
+    packageVersion: '0.4.5'
+  });
+  assert.equal(result.repaired, 1, 'only the entry that maps to the discovered destination is repaired');
+  const repaired = await readMcpConfig(path);
+  assert.equal(repaired.servers.shared.command, 'npx');
+  assert.deepEqual(repaired.servers.shared.args, ['--yes', '--package=sap-ai-dev-toolkit@0.4.5', 'sap-ai-dev']);
+  assert.equal(repaired.servers.shared.env.OPERATOR_SETTING, 'preserve');
+  assert.equal(repaired.servers.shared.env.H2O_URL, 'http://current-h2o.example');
+  assert.equal(repaired.servers.other.command, 'stale-sap-ai-dev', 'unmatched toolkit entry must remain untouched');
+  assert.deepEqual(repaired.servers.userServer, { command: 'other' });
+});
+
 test('extracts key references only from package-managed Cloud Foundry entries', () => {
   const cloudFoundry = buildMcpEntries([
     cfDestination('space-one', 'instance-one', 'destination-key', 'OnPremise')

package/test/mcp-proxy.test.mjs

@@ -271,6 +271,36 @@ test('merges paged tools and routes calls to the selected child', async t => {
     assert.equal(init.env.allowTransportableEdits, 'true');
   }
 });
+
+test('routes tools/call using the exact name advertised for a BAS destination', async t => {
+  const directory = await mkdtemp(join(tmpdir(), 'bas-namespaced-tool-roundtrip-'));
+  const log = join(directory, 'children.log');
+  const logs = [];
+  const proxy = new MCPProxy({
+    binary: fixture,
+    destinations: [{ name: 'ActionS4D_100', url: 'http://ActionS4D_100.dest', client: '100' }],
+    env: { ...process.env, SAP_AI_DEV_TOOLKIT_MODE: 'expert', FAKE_LOG: log },
+    log: message => logs.push(message)
+  });
+  t.after(async () => { await proxy.close(); await rm(directory, { recursive: true, force: true }); });
+  proxy.start();
+  const initialized = await proxy.handle({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05' } });
+  assert.equal(initialized.error, undefined, `${JSON.stringify(initialized.error)} ${logs.join(' | ')}`);
+  const listed = await proxy.handle({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+  assert.equal(listed.error, undefined, JSON.stringify(listed.error));
+  const tool = listed.result.tools.find(candidate => candidate.name === 'actions4d-100__WriteSource');
+  assert.ok(tool, 'tools/list must publish the normalized destination namespace');
+  const called = await proxy.handle({
+    jsonrpc: '2.0',
+    id: 3,
+    method: 'tools/call',
+    params: { name: tool.name, arguments: { source: 'REPORT zself_heal.' } }
+  });
+  assert.equal(called.error, undefined);
+  assert.equal(called.result.content[0].text, 'ActionS4D_100:WriteSource');
+  const calls = (await readFile(log, 'utf8')).trim().split('\n').map(line => JSON.parse(line)).filter(entry => entry.event === 'call');
+  assert.deepEqual(calls.map(entry => entry.name), ['WriteSource']);
+});
 test('runs LintABAP locally and returns parser findings', async t => {
   const { directory, log, proxy } = await fixtureProxy();
   t.after(async () => { await proxy.close(); await rm(directory, { recursive: true, force: true }); });