feat(lightspeed): harden DCR token minting and improve type safety

- Wrap getPluginRequestToken in per-server try/catch so one failing DCR
  server does not break all MCP integration
- Return 502 with clear error on token mint failure in /validate endpoint
- Bundle authService+credentials into dcrAuth object to prevent partial
  provision at compile time
- Export McpServerAuth type and use it instead of raw string
- Remove redundant per-request warning for dual auth+token config

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: maysunfaisal

workspaces/lightspeed/plugins/lightspeed-backend/report.api.md

@@ -20,9 +20,12 @@ export function createRouter(options: RouterOptions): Promise<express.Router>;
 const lightspeedPlugin: BackendFeature;
 export default lightspeedPlugin;
 
+// @public
+export type McpServerAuth = 'dcr';
+
 // @public
 export interface McpServerResponse {
-  auth?: string;
+  auth?: McpServerAuth;
   // (undocumented)
   enabled: boolean;
   // (undocumented)

workspaces/lightspeed/plugins/lightspeed-backend/src/index.ts

@@ -19,6 +19,7 @@ export * from './service/router';
 
 export type { RouterOptions } from './service/types';
 export type {
+  McpServerAuth,
   McpServerResponse,
   McpServerStatus,
   McpToolInfo,

workspaces/lightspeed/plugins/lightspeed-backend/src/service/mcp-server-types.ts

@@ -32,6 +32,12 @@ export interface McpUserSettingsRow {
  */
 export type McpServerStatus = 'connected' | 'error' | 'unknown';
 
+/**
+ * Authentication mode for MCP servers.
+ * @public
+ */
+export type McpServerAuth = 'dcr';
+
 /**
  * Public-facing response for an MCP server with user settings merged.
  * @public
@@ -45,7 +51,7 @@ export interface McpServerResponse {
   hasToken: boolean;
   hasUserToken: boolean;
   /** Authentication mode — `'dcr'` means tokens are minted automatically. */
-  auth?: string;
+  auth?: McpServerAuth;
 }
 
 /**

workspaces/lightspeed/plugins/lightspeed-backend/src/service/router.ts

@@ -45,6 +45,7 @@ import {
 } from './constant';
 import { McpUserSettingsStore } from './mcp-server-store';
 import {
+  McpServerAuth,
   McpServerResponse,
   McpServerStatus,
   McpValidationResult,
@@ -78,8 +79,6 @@ import { validateCompletionsRequest } from './validation';
  *    app-config.  If neither exists, the server is omitted from MCP-HEADERS.
  *    Users can also set their own tokens via the Lightspeed UI.
  */
-type McpServerAuth = 'dcr';
-
 interface StaticMcpServer {
   name: string;
   token?: string;
@@ -106,8 +105,7 @@ async function buildMcpHeaders(
   store: McpUserSettingsStore,
   userEntityRef: string,
   options?: {
-    authService?: AuthService;
-    credentials?: BackstageCredentials;
+    dcrAuth?: { authService: AuthService; credentials: BackstageCredentials };
     logger?: LoggerService;
   },
 ): Promise<string> {
@@ -121,18 +119,19 @@ async function buildMcpHeaders(
     if (!enabled) continue;
 
     if (server.auth === 'dcr') {
-      if (server.token && options?.logger) {
-        options.logger.warn(
-          `MCP server '${server.name}' has both auth: dcr and a static token; ` +
-            `the static token is ignored when auth is dcr`,
-        );
-      }
-      if (options?.authService && options?.credentials) {
-        const { token } = await options.authService.getPluginRequestToken({
-          onBehalfOf: options.credentials,
-          targetPluginId: 'mcp-actions',
-        });
-        headers[server.name] = { Authorization: `${token}` };
+      if (options?.dcrAuth) {
+        try {
+          const { token } =
+            await options.dcrAuth.authService.getPluginRequestToken({
+              onBehalfOf: options.dcrAuth.credentials,
+              targetPluginId: 'mcp-actions',
+            });
+          headers[server.name] = { Authorization: `${token}` };
+        } catch (err) {
+          options?.logger?.error(
+            `Failed to mint DCR token for MCP server '${server.name}': ${err}`,
+          );
+        }
       } else {
         options?.logger?.warn(
           `MCP server '${server.name}' has auth: dcr but AuthService is not available; skipping`,
@@ -400,11 +399,21 @@ export async function createRouter(
 
         let effectiveToken: string | undefined;
         if (server.auth === 'dcr') {
-          const { token: dcrToken } = await auth.getPluginRequestToken({
-            onBehalfOf: credentials,
-            targetPluginId: 'mcp-actions',
-          });
-          effectiveToken = dcrToken;
+          try {
+            const { token: dcrToken } = await auth.getPluginRequestToken({
+              onBehalfOf: credentials,
+              targetPluginId: 'mcp-actions',
+            });
+            effectiveToken = dcrToken;
+          } catch (err) {
+            logger.error(
+              `Failed to mint DCR token for server '${name}': ${err}`,
+            );
+            res.status(502).json({
+              error: `Failed to mint authentication token for DCR server '${name}' — check Backstage auth configuration`,
+            });
+            return;
+          }
         } else {
           const setting = await settingsStore.get(name, userEntityRef);
           effectiveToken = setting?.token || server.token;
@@ -715,7 +724,7 @@ export async function createRouter(
           staticServers,
           settingsStore,
           userEntityRef,
-          { authService: auth, credentials, logger },
+          { dcrAuth: { authService: auth, credentials }, logger },
         );
 
         const abortController = new AbortController();