Fix configurable-scope regression, wire publisher field, and document breaking change

- resolveTokenScopeForServer now accepts sharedScope parameter (defaults to
  prod ATG constant for backward compat) so V1 fallback scope is derived from
  mcpPlatformAuthenticationScope rather than a hardcoded constant. This fixes a
  false migration error when the auth scope is overridden via configuration.

- attachPerAudienceTokens reads mcpPlatformAuthenticationScope from config and
  passes it into resolveTokenScopeForServer, ensuring the scope resolution and
  the legacy-path guard always compare against the same configured value.

- publisher field is now preserved through both gateway and manifest
  normalization (previously declared in MCPServerConfig but silently dropped).

- Updated GetToolingGatewayForDigitalWorker JSDoc example URL to /agents/v2/.

- Added Breaking Changes section to CHANGELOG [Unreleased] documenting the
  listToolServers(agenticAppId, authToken) throw for V2 servers with migration
  guidance. Added publisher to the Added section.

- 5 new tests for resolveTokenScopeForServer with custom sharedScope, including
  a regression guard for the false migration-error scenario.

Author: biswapm

CHANGELOG.md

@@ -45,9 +45,28 @@ Both `Agent365.Observability.OtelWrite` (Delegated) and `Agent365.Observability.
 
 ## [Unreleased]
 
+### Breaking Changes (`@microsoft/agents-a365-tooling`)
+
+- **`listToolServers(agenticAppId, authToken)` throws for V2 MCP servers** — The deprecated
+  two-argument overload now throws a hard error if the gateway returns any server whose
+  `audience` field does not match the shared ATG app ID (i.e. a V2 server). The legacy
+  signature cannot perform per-audience OBO because it has no `Authorization` object or
+  `authHandlerName`. Agents whose blueprints only have V1 permissions are unaffected.
+
+  **Migration** — switch to the preferred overload which handles both V1 and V2 automatically:
+  ```typescript
+  // Before (deprecated)
+  const servers = await service.listToolServers(agenticAppId, authToken);
+
+  // After
+  const servers = await service.listToolServers(turnContext, authorization, 'graph');
+  // authToken is optional; omit it and the SDK auto-generates it via token exchange.
+  ```
+
 ### Added (`@microsoft/agents-a365-tooling`)
 
 - **V1/V2 per-audience token acquisition** — `resolveTokenScopeForServer` now supports explicit `scope` field for V2 MCP servers. When a V2 server provides a `scope` value, the token is requested as `{audience}/{scope}`; otherwise falls back to `{audience}/.default` (pre-consented permissions cover both cases).
+- **`publisher` field preserved end-to-end** — `MCPServerConfig.publisher` is now carried through both gateway and manifest normalization and is available to callers of `listToolServers`.
 
 ### Fixed (`@microsoft/agents-a365-tooling-extensions-openai`, `@microsoft/agents-a365-tooling-extensions-langchain`)
 

packages/agents-a365-tooling/src/McpToolServerConfigurationService.ts

@@ -163,11 +163,13 @@ export class McpToolServerConfigurationService {
     servers: MCPServerConfig[],
     acquire: TokenAcquirer
   ): Promise<MCPServerConfig[]> {
+    // Fetch once so scope resolution and the legacy-path guard use the same value.
+    const sharedScope = this.configProvider.getConfiguration().mcpPlatformAuthenticationScope;
     const tokenCache = new Map<string, string | null>(); // scope → token (null = no token available)
 
     const result: MCPServerConfig[] = [];
     for (const server of servers) {
-      const scope = resolveTokenScopeForServer(server);
+      const scope = resolveTokenScopeForServer(server, sharedScope);
       if (!tokenCache.has(scope)) {
         tokenCache.set(scope, await acquire(server, scope));
       }
@@ -404,6 +406,7 @@ export class McpToolServerConfigurationService {
         headers: s.headers,
         audience: s.audience,
         scope: s.scope,
+        publisher: s.publisher,
       }));
     } catch (err: unknown) {
       const error = err as Error & { code?: string };
@@ -465,6 +468,7 @@ export class McpToolServerConfigurationService {
           headers: s.headers,
           audience: s.audience,
           scope: s.scope,
+          publisher: s.publisher,
         };
       });
     } catch (err: unknown) {

packages/agents-a365-tooling/src/Utility.ts

@@ -153,7 +153,7 @@ export class Utility {
    *
    * Example:
    *   Utility.GetToolingGatewayForDigitalWorker(agenticAppId)
-   *   // => "https://agent365.svc.cloud.microsoft/agents/{agenticAppId}/mcpServers"
+   *   // => "https://agent365.svc.cloud.microsoft/agents/v2/{agenticAppId}/mcpServers"
    *
    * @param agenticAppId - The unique identifier for the agent identity.
    * @param configProvider - Optional configuration provider. Defaults to defaultToolingConfigurationProvider.

packages/agents-a365-tooling/src/configuration/ToolingConfiguration.ts

@@ -8,25 +8,42 @@ import { MCPServerConfig } from '../contracts';
 // Constants for tooling-specific settings
 const MCP_PLATFORM_PROD_BASE_URL = 'https://agent365.svc.cloud.microsoft';
 const PROD_MCP_PLATFORM_AUTHENTICATION_SCOPE = 'ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/.default';
-const ATG_APP_ID = 'ea9ffc3e-8a23-4a7d-836d-234d7c7565c1';
-const ATG_APP_ID_URI = `api://${ATG_APP_ID}`;   // "api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1"
 
 /**
  * Resolve the OAuth scope to request for a given MCP server.
- * V2 servers carry their own audience GUID in the `audience` field; V1 servers (no audience,
- * or audience matching the shared ATG AppId or its api:// URI form) fall back to the shared ATG scope.
+ *
+ * V2 servers carry their own audience in the `audience` field and get a per-audience token.
+ * V1 servers (no `audience`, or audience matching the shared scope's own audience in plain
+ * or api:// form) fall back to `sharedScope` — the configured mcpPlatformAuthenticationScope.
+ *
+ * @param server     The MCP server config returned by the gateway or manifest.
+ * @param sharedScope The configured shared scope (mcpPlatformAuthenticationScope).
+ *   Defaults to the prod ATG scope so that external callers without a custom config
+ *   continue to work without passing the argument.
  */
-export function resolveTokenScopeForServer(server: MCPServerConfig): string {
-  if (server.audience &&
-      server.audience !== ATG_APP_ID &&
-      server.audience !== ATG_APP_ID_URI) {
-    // V2 server: use explicit scope if provided, otherwise fall back to /.default
-    if (server.scope) {
-      return `${server.audience}/${server.scope}`;
+export function resolveTokenScopeForServer(
+  server: MCPServerConfig,
+  sharedScope: string = PROD_MCP_PLATFORM_AUTHENTICATION_SCOPE
+): string {
+  if (server.audience) {
+    // Extract the audience portion of sharedScope (everything before the last '/').
+    // e.g. 'ea9ffc3e-.../.default'      → 'ea9ffc3e-...'
+    //      'api://ea9ffc3e-.../.default' → 'api://ea9ffc3e-...'
+    const sharedAudience = sharedScope.slice(0, sharedScope.lastIndexOf('/'));
+    // Build the alternate form so we match both 'guid' and 'api://guid'.
+    const sharedAudienceAlt = sharedAudience.startsWith('api://')
+      ? sharedAudience.slice(6)        // 'api://guid' → 'guid'
+      : `api://${sharedAudience}`;     // 'guid'       → 'api://guid'
+
+    if (server.audience !== sharedAudience && server.audience !== sharedAudienceAlt) {
+      // V2 server: use its own audience with explicit scope or /.default fallback.
+      return server.scope
+        ? `${server.audience}/${server.scope}`
+        : `${server.audience}/.default`;
     }
-    return `${server.audience}/.default`;
   }
-  return `${ATG_APP_ID}/.default`;
+  // V1 server: no audience, or audience matches the shared ATG audience.
+  return sharedScope;
 }
 
 /**

tests/tooling/configuration/ToolingConfiguration.test.ts

@@ -325,6 +325,51 @@ describe('resolveTokenScopeForServer', () => {
       scope: 'Tools.ListInvoke.All'
     })).toBe(`${v2AppId}/Tools.ListInvoke.All`);
   });
+
+  describe('custom sharedScope (configurable mcpPlatformAuthenticationScope)', () => {
+    const customScope = 'api://custom-atg/.default';
+    const customAudience = 'api://custom-atg';
+
+    it('should return customScope for a V1 server with no audience when sharedScope is overridden', () => {
+      expect(resolveTokenScopeForServer(
+        { mcpServerName: 'mail', url: 'https://mail.example.com' },
+        customScope
+      )).toBe(customScope);
+    });
+
+    it('should return customScope when server audience matches the custom shared audience (api:// form)', () => {
+      expect(resolveTokenScopeForServer(
+        { mcpServerName: 'mail', url: 'https://mail.example.com', audience: customAudience },
+        customScope
+      )).toBe(customScope);
+    });
+
+    it('should return customScope when server audience matches the custom shared audience (plain form)', () => {
+      // audience field may arrive as plain GUID/id even when sharedScope uses api:// prefix
+      expect(resolveTokenScopeForServer(
+        { mcpServerName: 'mail', url: 'https://mail.example.com', audience: 'custom-atg' },
+        customScope
+      )).toBe(customScope);
+    });
+
+    it('should still treat a V2 server as V2 even when sharedScope is custom', () => {
+      const v2Audience = 'aaaabbbb-1234-5678-abcd-111122223333';
+      expect(resolveTokenScopeForServer(
+        { mcpServerName: 'tools', url: 'https://tools.example.com', audience: v2Audience },
+        customScope
+      )).toBe(`${v2Audience}/.default`);
+    });
+
+    it('should not raise false migration error in legacy prod acquirer when sharedScope is overridden', () => {
+      // Regression guard: with the old hardcoded constant, resolveTokenScopeForServer returned
+      // 'ea9ffc3e-.../.default' while createLegacyProdTokenAcquirer compared against the custom
+      // scope — mismatch → false throw. Now both sides use the same configured value.
+      expect(resolveTokenScopeForServer(
+        { mcpServerName: 'mail', url: 'https://mail.example.com' },
+        customScope
+      )).toBe(customScope); // returned scope === sharedScope → no throw
+    });
+  });
 });
 
 describe('defaultToolingConfigurationProvider', () => {