@salesforce/sfdx-agent-sdk 0.50.0 → 0.52.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.52.0] - 2026-08-24
+
+### Features
+- **agent-sdk,harness-claude,harness-mastra,harness-openai**: support OAuth authProvider on remote MCP servers @W-23939243@ ([#757](https://github.com/forcedotcom/agentic-dx/pull/757))
+
+## [0.51.0] - 2026-08-18
+
+### Chores
+- **deps-dev**: bump the eslint group across 1 directory with 2 updates ([#754](https://github.com/forcedotcom/agentic-dx/pull/754))
+- **deps-dev**: bump the dev-dependencies group with 2 updates ([#753](https://github.com/forcedotcom/agentic-dx/pull/753))
+
 ## [0.50.0] - 2026-08-17
 
 ### Features

package/README.md

@@ -386,6 +386,45 @@ type MCPRemoteServerConfig = {
 };
 ```
 
+#### OAuth-protected remote MCP servers
+
+To connect an OAuth-protected third-party remote MCP server (Figma, Linear, Notion, Sentry, Neon, Hugging Face, …),
+supply an `McpOAuthClientProvider` through the manager's **`mcpAuthProviderResolver`**, not on the server config. The
+provider is a credential-bearing runtime object, so it is deliberately kept **off** the persisted `AgentConfig` — it is
+resolved per agent at install / restore / update and threaded to the harness at runtime, never serialized to disk.
+
+```ts
+const manager = await createAgentManager(storageRoot, harnessFactory, {
+  // (agentId, config) => Record<remoteServerName, McpOAuthClientProvider> | undefined
+  mcpAuthProviderResolver: (_agentId, _config) => ({ figma: myFigmaProvider }),
+});
+```
+
+The harness forwards the provider into the underlying HTTP transport (`@modelcontextprotocol/sdk`'s
+`StreamableHTTPClientTransport` on Claude / OpenAI, `@mastra/mcp`'s `HttpServerDefinition` on Mastra). The transport
+attaches existing tokens and silently refreshes them when possible. If user interaction is required, it invokes the
+provider's `redirectToAuthorization` callback and surfaces `McpServerErrorDetail.category === 'oauth-required'`;
+ADX does not open a browser or accept the authorization callback code. The static `headers` seam cannot provide this
+recovery because headers are snapshotted at publish time.
+
+- **`McpOAuthClientProvider`** (exported) is a harness-neutral interface that structurally mirrors the required core of
+  the MCP SDK's `OAuthClientProvider`, so a real provider assigns to it with no cast and the SDK stays free of a direct
+  `@modelcontextprotocol/sdk` dependency. **`McpAuthProviders`** (exported) is the `Readonly<Record<serverName,
+  McpOAuthClientProvider>>` the resolver returns.
+- **One provider instance per server**, and return the **same** instance across calls — the upstream contract forbids
+  tokens / codes / verifiers crossing sessions, and a harness cycles a server when its provider reference changes (so
+  returning a fresh instance each update reconnects that server every time).
+- **One auth owner per server (enforced centrally).** The SDK normalizes the resolver's output before handing it to a
+  harness: a provider is **dropped** for a Salesforce Platform URL (the rotating org JWT owns auth there), a stdio /
+  disabled / unknown server; and a provider **paired with a static `Authorization` header** is **rejected**
+  (`AgentSDKErrorType.INVALID_MCP_AUTH_CONFIG`) because the MCP SDK transport would let the static header silently win
+  over the provider token. For a provider-owned non-Salesforce server the harness attaches the proxy-aware inner `fetch`
+  (no Salesforce JWT injected, `HTTPS_PROXY` preserved) while the provider drives auth.
+
+> **Interactive authorization stays with the consumer.** AFV's provider owns the Sign in UI, browser, VS Code callback,
+> and code exchange. After it saves the new tokens, call `Agent.reconnectMcpServer` to connect. ADX owns runtime provider
+> forwarding and silent refresh only; the transport's `finishAuth(code)` seam is not part of the public API.
+
 **Tool-exposure policy** (which tools bypass the active runtime's tool-search deferral) is configured per-agent on the
 harness extension surface, not per-server here. See `MastraAgentConfig.toolSearch.alwaysActive` and
 `ClaudeAgentConfig.toolSearch.alwaysActive` for the entry shape that covers "all tools from server X", "tool Y on server
@@ -411,16 +450,17 @@ only `MCPRemoteServerConfig` carries it.
 
 #### `McpServerErrorDetail`
 
-Structured projection of an MCP server failure. Mirror is also attached to the `mcp-server-discovery-failed` telemetry
-event so subscribers can route on it without pattern-matching `error.message`.
+Structured projection of an MCP server failure. Route interactive authorization on `category === 'oauth-required'`;
+an ordinary missing or invalid bearer remains `http-401`. The same detail is attached to `mcp-server-discovery-failed`
+telemetry so subscribers can route on it without pattern-matching `error.message`.
 
 | Field       | Type                     | Description                                                                                                                                                                                                                 |
 | ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `category`  | `McpServerErrorCategory` | Stable category for routing logic. Set is additive across minor versions — values are added but never renamed or removed.                                                                                                   |
 | `code?`     | `number`                 | JSON-RPC error code from the underlying `McpError`, when the failure originated as a JSON-RPC error. Undefined for transport-level failures and for harnesses whose underlying SDK does not surface the code (e.g. Claude). |
-| `retriable` | `boolean`                | Whether the SDK considers the failure transient (worth `Agent.reconnectMcpServer` / `Agent.refreshMcpAuth`) versus fatal.                                                                                                   |
+| `retriable` | `boolean`                | Whether the SDK considers the failure transient (worth `Agent.reconnectMcpServer`) versus fatal.                                                                                                                            |
 
-`McpServerErrorCategory` values: `'connect-timeout'`, `'http-401'`, `'http-403'`, `'http-4xx'`, `'http-5xx'`,
+`McpServerErrorCategory` values: `'connect-timeout'`, `'oauth-required'`, `'http-401'`, `'http-403'`, `'http-4xx'`, `'http-5xx'`,
 `'transport-eof'`, `'protocol-error'`, `'config-error'`, `'aborted'`, `'unknown'`.
 
 #### `McpToolInfo`

package/dist/agent-manager.d.ts

@@ -1,8 +1,8 @@
 import { type Clock, LogBus, type LogRecord, type Unsubscribe, type UniqueIDGenerator } from '@salesforce/agentic-common';
 import { type AgentHarness, type ConfigOf } from './harness/agent-harness.js';
 import type { HarnessFactory } from './harness/harness-factory.js';
-import { type AgentConfig } from './harness/harness-config.js';
-import { type Agent } from './agent.js';
+import { type AgentConfig, type McpAuthProviderResolver } from './harness/harness-config.js';
+import { type Agent, type AgentRuntimeResolvers } from './agent.js';
 import type { HooksForAgent } from './types/redaction.js';
 import { type TelemetryEventCallback } from './types/telemetry-events.js';
 import type { WireCommunicationEventCallback } from './types/wire-communication-event.js';
@@ -138,7 +138,7 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
     private readonly harnessSupportedProviderHints;
     private readonly agentIdGenerator;
     private readonly agentConnectivityResolver;
-    private readonly hooksForAgent;
+    private readonly resolvers;
     private readonly clock;
     private readonly identityStore;
     private readonly agents;
@@ -161,7 +161,7 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
      * is private, so this is the only way to obtain an instance, but
      * consumers should always go through {@link createAgentManager}.
      */
-    static __build<H extends AgentHarness>(harness: H, harnessSupportedProviderHints: readonly ProviderHint[], agentConnectivityResolver: AgentConnectivityResolver, hooksForAgent: HooksForAgent | undefined, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
+    static __build<H extends AgentHarness>(harness: H, harnessSupportedProviderHints: readonly ProviderHint[], agentConnectivityResolver: AgentConnectivityResolver, resolvers: AgentRuntimeResolvers, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
     private init;
     shutdown(): Promise<void>;
     createAgent(projectRoot: string, config?: ConfigOf<H> & {
@@ -228,4 +228,11 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
 export declare function createAgentManager<H extends AgentHarness = AgentHarness>(storageRootFolder: string, harnessFactory: HarnessFactory<H>, options?: {
     connectivityResolver?: AgentConnectivityResolver;
     hooksForAgent?: HooksForAgent;
+    /**
+     * Resolves the per-agent OAuth provider map for remote MCP servers.
+     * See {@link McpAuthProviderResolver}. Providers are supplied here at
+     * runtime and never persisted; required to connect OAuth-protected
+     * third-party remote MCP servers.
+     */
+    mcpAuthProviderResolver?: McpAuthProviderResolver;
 }): Promise<AgentManager<H>>;

package/dist/agent-manager.js

@@ -7,6 +7,7 @@ import { resolve } from 'node:path';
 import { stat } from 'node:fs/promises';
 import { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
 import { toHarnessConfig } from './harness/harness-config.js';
+import { normalizeMcpAuthProviders } from './mcp-auth.js';
 import { DefaultAgent } from './agent.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 import { TelemetryRouter } from './internal/telemetry-router.js';
@@ -28,7 +29,7 @@ export class DefaultAgentManager {
     harnessSupportedProviderHints;
     agentIdGenerator;
     agentConnectivityResolver;
-    hooksForAgent;
+    resolvers;
     clock;
     identityStore;
     agents = new Map();
@@ -43,11 +44,11 @@ export class DefaultAgentManager {
     wireRouter;
     unroutedUnsubs;
     disposed = false;
-    constructor(harness, harnessSupportedProviderHints, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus) {
+    constructor(harness, harnessSupportedProviderHints, agentConnectivityResolver, resolvers, identityStore, agentIdGenerator, clock, logBus) {
         this.harness = harness;
         this.harnessSupportedProviderHints = harnessSupportedProviderHints;
         this.agentConnectivityResolver = agentConnectivityResolver;
-        this.hooksForAgent = hooksForAgent;
+        this.resolvers = resolvers;
         this.identityStore = identityStore;
         this.agentIdGenerator = agentIdGenerator;
         this.clock = clock;
@@ -75,9 +76,9 @@ export class DefaultAgentManager {
      * is private, so this is the only way to obtain an instance, but
      * consumers should always go through {@link createAgentManager}.
      */
-    static async __build(harness, harnessSupportedProviderHints, agentConnectivityResolver, hooksForAgent, storageRootFolder, agentIdGenerator, clock, logBus) {
+    static async __build(harness, harnessSupportedProviderHints, agentConnectivityResolver, resolvers, storageRootFolder, agentIdGenerator, clock, logBus) {
         const identityStore = new AgentIdentityStore(storageRootFolder, harness.harnessId, logBus);
-        const manager = new DefaultAgentManager(harness, harnessSupportedProviderHints, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus);
+        const manager = new DefaultAgentManager(harness, harnessSupportedProviderHints, agentConnectivityResolver, resolvers, identityStore, agentIdGenerator, clock, logBus);
         await manager.init();
         return manager;
     }
@@ -183,8 +184,9 @@ export class DefaultAgentManager {
         if (!this.harnessSupportedProviderHints.includes(providerHint)) {
             throw new AgentSDKError(`Harness "${this.harness.harnessId}" does not support providerHint "${providerHint}". Supported: ${this.harnessSupportedProviderHints.join(', ')}.`, AgentSDKErrorType.MODEL_NOT_SUPPORTED_BY_HARNESS);
         }
-        const hooks = this.hooksForAgent?.(agentId, config) ?? {};
-        await this.harness.createAgent(agentId, projectRoot, runtime.modelConnectivityInfo, toHarnessConfig(config, runtime.orgJwt), { ...(options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}), hooks });
+        const hooks = this.resolvers.hooksForAgent?.(agentId, config) ?? {};
+        const mcpAuthProviders = normalizeMcpAuthProviders(config.mcpServers, this.resolvers.mcpAuthProviderResolver?.(agentId, config));
+        await this.harness.createAgent(agentId, projectRoot, runtime.modelConnectivityInfo, toHarnessConfig(config, runtime.orgJwt), { ...(options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}), hooks, mcpAuthProviders });
         const agentSlice = this.router.registerAgent(agentId);
         // Forward-compat: register the agent against the wire-communication router
         // too. Today every WireCommunicationEvent lands on the unrouted slice (no
@@ -192,7 +194,7 @@ export class DefaultAgentManager {
         // symmetrically with the telemetry router so the wiring is in place if/when
         // the event shape grows an agentId field.
         this.wireRouter.registerAgent(agentId);
-        const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.modelConnectivityInfo, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.harnessSupportedProviderHints, this.hooksForAgent, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
+        const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.modelConnectivityInfo, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.harnessSupportedProviderHints, this.resolvers, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
         this.agents.set(agentId, agent);
         const agentCreatedAt = this.clock.now();
         const modelName = runtime.modelConnectivityInfo.model.name;
@@ -359,7 +361,7 @@ export async function createAgentManager(storageRootFolder, harnessFactory, opti
     }
     const agentConnectivityResolver = options?.connectivityResolver ?? new DefaultAgentConnectivityResolver();
     const clock = new RealClock();
-    return DefaultAgentManager.__build(harness, harnessFactory.supportedProviderHints, agentConnectivityResolver, options?.hooksForAgent, storageRootFolder, new UUIDGenerator(), clock, 
+    return DefaultAgentManager.__build(harness, harnessFactory.supportedProviderHints, agentConnectivityResolver, { hooksForAgent: options?.hooksForAgent, mcpAuthProviderResolver: options?.mcpAuthProviderResolver }, storageRootFolder, new UUIDGenerator(), clock, 
     // The manager's root log bus shares the manager clock and self-reads the process environment context.
     new LogBus(clock));
 }

package/dist/agent.d.ts

@@ -1,6 +1,6 @@
 import { type Clock, type JSONWebToken, LogBus, type LogRecord, type OrgConnection, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import type { AgentHarness } from './harness/agent-harness.js';
-import { type AgentConfig } from './harness/harness-config.js';
+import { type AgentConfig, type McpAuthProviderResolver } from './harness/harness-config.js';
 import { type ChatSession } from './chat-session.js';
 import type { McpServerInfo } from './mcp-config.js';
 import type { AgentConnectivityResolver } from './agent-connectivity-resolver.js';
@@ -144,6 +144,15 @@ export interface Agent {
     /** Subscribe to structured log records scoped to this agent (and its sessions). Returns an unsubscribe function. */
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
 }
+/**
+ * The per-agent runtime resolvers the SDK threads from `createAgentManager` into each agent — callbacks the consumer
+ * supplies once and the SDK re-invokes per install / restore / update. Bundled so a new runtime binding is one field
+ * here, not another parameter through every manager → agent seam. Each member is optional (unset by the consumer).
+ */
+export type AgentRuntimeResolvers = {
+    hooksForAgent?: HooksForAgent;
+    mcpAuthProviderResolver?: McpAuthProviderResolver;
+};
 /**
  * Default implementation of {@link Agent} that delegates
  * agent and thread operations to an {@link AgentHarness}.
@@ -158,7 +167,7 @@ export declare class DefaultAgent implements Agent {
     private orgJwt;
     private readonly agentConnectivityResolver;
     private readonly harnessSupportedProviderHints;
-    private readonly hooksForAgent;
+    private readonly resolvers;
     private readonly identityStore;
     private readonly sessions;
     private readonly sessionSliceUnregisters;
@@ -181,17 +190,18 @@ export declare class DefaultAgent implements Agent {
      * @param orgConnection - Authenticated org connection carrying identity and env inference.
      * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
      * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
-     * @param hooksForAgent - Per-agent hooks resolver supplied by the SDK consumer at `createAgentManager` time. The
-     *     agent re-invokes it on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the
-     *     rollback path) so the bag the harness sees always reflects the current persisted config. `undefined` when
-     *     the consumer didn't pass a `hooksForAgent`.
+     * @param resolvers - Per-agent runtime resolvers ({@link AgentRuntimeResolvers}: `hooksForAgent`,
+     *     `mcpAuthProviderResolver`) supplied by the SDK consumer at `createAgentManager` time. The agent re-invokes
+     *     them on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the rollback path)
+     *     so what the harness sees always reflects the current persisted config. Each member is `undefined` when the
+     *     consumer didn't pass it.
      * @param identityStore - SDK-owned persistence for the `{ agentId, projectRoot, AgentConfig }` triple. The agent
      *     calls `write()` on a successful `updateAgentConfig` so disk state and in-memory state stay in lockstep.
      * @param router - Telemetry router used to obtain session slices when sessions are created.
      * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
      * @param parent - Manager's bus pair; this agent forwards its events upward into them.
      */
-    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, modelConnectivityInfo: ModelConnectivityInfo, orgConnection: OrgConnection | undefined, orgJwt: JSONWebToken | undefined, agentConnectivityResolver: AgentConnectivityResolver, harnessSupportedProviderHints: readonly ProviderHint[], hooksForAgent: HooksForAgent | undefined, identityStore: AgentIdentityStore, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, modelConnectivityInfo: ModelConnectivityInfo, orgConnection: OrgConnection | undefined, orgJwt: JSONWebToken | undefined, agentConnectivityResolver: AgentConnectivityResolver, harnessSupportedProviderHints: readonly ProviderHint[], resolvers: AgentRuntimeResolvers, identityStore: AgentIdentityStore, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
     /**
      * @requirements
      * - MUST return the agent's ID.

package/dist/agent.js

@@ -4,6 +4,7 @@
  */
 import { LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
 import { toHarnessConfig } from './harness/harness-config.js';
+import { normalizeMcpAuthProviders } from './mcp-auth.js';
 import { DefaultChatSession } from './chat-session.js';
 import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 import { createTelemetryBus } from './types/telemetry-events.js';
@@ -21,7 +22,7 @@ export class DefaultAgent {
     orgJwt;
     agentConnectivityResolver;
     harnessSupportedProviderHints;
-    hooksForAgent;
+    resolvers;
     identityStore;
     sessions = new Map();
     sessionSliceUnregisters = new Map();
@@ -46,17 +47,18 @@ export class DefaultAgent {
      * @param orgConnection - Authenticated org connection carrying identity and env inference.
      * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
      * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
-     * @param hooksForAgent - Per-agent hooks resolver supplied by the SDK consumer at `createAgentManager` time. The
-     *     agent re-invokes it on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the
-     *     rollback path) so the bag the harness sees always reflects the current persisted config. `undefined` when
-     *     the consumer didn't pass a `hooksForAgent`.
+     * @param resolvers - Per-agent runtime resolvers ({@link AgentRuntimeResolvers}: `hooksForAgent`,
+     *     `mcpAuthProviderResolver`) supplied by the SDK consumer at `createAgentManager` time. The agent re-invokes
+     *     them on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the rollback path)
+     *     so what the harness sees always reflects the current persisted config. Each member is `undefined` when the
+     *     consumer didn't pass it.
      * @param identityStore - SDK-owned persistence for the `{ agentId, projectRoot, AgentConfig }` triple. The agent
      *     calls `write()` on a successful `updateAgentConfig` so disk state and in-memory state stay in lockstep.
      * @param router - Telemetry router used to obtain session slices when sessions are created.
      * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
      * @param parent - Manager's bus pair; this agent forwards its events upward into them.
      */
-    constructor(harness, agentId, projectRoot, config, modelConnectivityInfo, orgConnection, orgJwt, agentConnectivityResolver, harnessSupportedProviderHints, hooksForAgent, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+    constructor(harness, agentId, projectRoot, config, modelConnectivityInfo, orgConnection, orgJwt, agentConnectivityResolver, harnessSupportedProviderHints, resolvers, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
         this.harness = harness;
         this.agentId = agentId;
         this.projectRoot = projectRoot;
@@ -66,7 +68,7 @@ export class DefaultAgent {
         this.orgJwt = orgJwt;
         this.agentConnectivityResolver = agentConnectivityResolver;
         this.harnessSupportedProviderHints = harnessSupportedProviderHints;
-        this.hooksForAgent = hooksForAgent;
+        this.resolvers = resolvers;
         this.identityStore = identityStore;
         this.router = router;
         this.clock = clock;
@@ -157,10 +159,12 @@ export class DefaultAgent {
             nextOrgJwt = runtime.orgJwt;
         }
         try {
-            const nextHooks = this.hooksForAgent?.(this.agentId, nextConfig) ?? {};
+            const nextHooks = this.resolvers.hooksForAgent?.(this.agentId, nextConfig) ?? {};
+            const nextMcpAuthProviders = normalizeMcpAuthProviders(nextConfig.mcpServers, this.resolvers.mcpAuthProviderResolver?.(this.agentId, nextConfig));
             await this.harness.updateAgent(this.agentId, nextModelConnectivityInfo, toHarnessConfig(nextConfig, nextOrgJwt), {
                 ...(options?.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}),
                 hooks: nextHooks,
+                mcpAuthProviders: nextMcpAuthProviders,
             });
             // Persist before the in-memory swaps so a write failure flows through the same
             // catch block as an updateAgent failure: the rollback re-runs updateAgent against
@@ -177,8 +181,9 @@ export class DefaultAgent {
             // against its current state — if updateAgent partially applied (e.g. some MCP
             // servers were already cycled), reverting via updateAgent restores them too.
             try {
-                const previousHooks = this.hooksForAgent?.(this.agentId, previousConfig) ?? {};
-                await this.harness.updateAgent(this.agentId, previousModelConnectivityInfo, toHarnessConfig(previousConfig, previousOrgJwt), { hooks: previousHooks });
+                const previousHooks = this.resolvers.hooksForAgent?.(this.agentId, previousConfig) ?? {};
+                const previousMcpAuthProviders = normalizeMcpAuthProviders(previousConfig.mcpServers, this.resolvers.mcpAuthProviderResolver?.(this.agentId, previousConfig));
+                await this.harness.updateAgent(this.agentId, previousModelConnectivityInfo, toHarnessConfig(previousConfig, previousOrgJwt), { hooks: previousHooks, mcpAuthProviders: previousMcpAuthProviders });
             }
             catch {
                 // Ignore restoration errors; rethrow the original failure.

package/dist/errors.d.ts

@@ -4,6 +4,7 @@ export declare const AgentSDKErrorType: {
     readonly COMPACTION_FAILED: 'COMPACTION_FAILED';
     readonly DISPOSED: 'DISPOSED';
     readonly INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS';
+    readonly INVALID_MCP_AUTH_CONFIG: 'INVALID_MCP_AUTH_CONFIG';
     readonly INVALID_MESSAGE_CONTENT: 'INVALID_MESSAGE_CONTENT';
     readonly MCP_SERVER_DISABLED: 'MCP_SERVER_DISABLED';
     readonly MCP_SERVER_NOT_FOUND: 'MCP_SERVER_NOT_FOUND';

package/dist/errors.js

@@ -8,6 +8,7 @@ export const AgentSDKErrorType = {
     COMPACTION_FAILED: 'COMPACTION_FAILED',
     DISPOSED: 'DISPOSED',
     INCOMPATIBLE_HARNESS: 'INCOMPATIBLE_HARNESS',
+    INVALID_MCP_AUTH_CONFIG: 'INVALID_MCP_AUTH_CONFIG',
     INVALID_MESSAGE_CONTENT: 'INVALID_MESSAGE_CONTENT',
     MCP_SERVER_DISABLED: 'MCP_SERVER_DISABLED',
     MCP_SERVER_NOT_FOUND: 'MCP_SERVER_NOT_FOUND',

package/dist/harness/agent-harness.d.ts

@@ -1,5 +1,5 @@
 import type { LogRecord, Unsubscribe } from '@salesforce/agentic-common';
-import type { McpServerInfo } from '../mcp-config.js';
+import type { McpServerInfo, McpAuthProviders } from '../mcp-config.js';
 import type { ChatStreamResult } from '../types/events.js';
 import type { Message, MessagePart } from '../types/messages.js';
 import type { TelemetryEventCallback } from '../types/telemetry-events.js';
@@ -142,11 +142,20 @@ export interface AgentHarness {
      *     native error path so the original tool output never leaks to the
      *     model. The SDK does not own fail-closed semantics; consumers
      *     wrap their hook bodies in `try`/`catch` themselves when they
-     *     want a richer fail-closed substitute.
+     *   want a richer fail-closed substitute.
+     *   - `mcpAuthProviders` — per-agent OAuth provider map (remote MCP server
+     *     name → {@link McpOAuthClientProvider}), resolved by the SDK from
+     *     `createAgentManager`'s `mcpAuthProviderResolver` and already normalized
+     *     (Salesforce URLs / stdio / disabled / missing servers dropped, static-
+     *     Authorization conflicts rejected — see `normalizeMcpAuthProviders`).
+     *     Providers are runtime bindings, NEVER part of `HarnessAgentConfig`;
+     *     harnesses store the map on per-agent state and forward `providers[name]`
+     *     into the remote transport for that server.
      */
     createAgent(agentId: string, projectRoot: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
+        mcpAuthProviders?: McpAuthProviders;
     }): Promise<void>;
     /**
      * Destroy an agent and release its resources (MCP connections, workspace, memory).
@@ -179,9 +188,12 @@ export interface AgentHarness {
      *   matching the rest of the cross-harness contract.
      * - preserve the in-memory MCP client (and its discovered tool catalog)
      *   for any server name whose config is `mcpServerConfigEqual` to the
-     *   currently-applied one. No transport teardown, no `tools/list`
-     *   re-run, no per-server discovery telemetry.
-     * - cycle (disconnect-then-reconnect) any server whose config differs.
+     *   currently-applied one AND whose applied OAuth provider reference (from
+     *   `options.mcpAuthProviders`) is unchanged. No transport teardown, no
+     *   `tools/list` re-run, no per-server discovery telemetry.
+     * - cycle (disconnect-then-reconnect) any server whose config differs OR
+     *   whose applied provider reference changed (a swapped provider instance
+     *   must cycle the server so the new one owns auth).
      * - disconnect any server present in the currently-applied config but
      *   absent from the next config, removing it from
      *   `getMcpServerInfo()`'s output.
@@ -233,10 +245,15 @@ export interface AgentHarness {
      *     re-resolved on every `updateAgent` so consumers can vary hooks by
      *     config (and so a rollback `updateAgent(previousConfig)` restores
      *     the prior hook bag too).
+     *   - `mcpAuthProviders` — per-agent normalized OAuth provider map, re-resolved
+     *     on every `updateAgent` (so a provider swap cycles its server, and a
+     *     rollback `updateAgent(previousConfig)` restores the prior providers).
+     *     Same runtime-only semantics as `createAgent.options.mcpAuthProviders`.
      */
     updateAgent(agentId: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
+        mcpAuthProviders?: McpAuthProviders;
     }): Promise<void>;
     /**
      * List the IDs of all currently registered agents.

package/dist/harness/harness-config.d.ts

@@ -1,5 +1,5 @@
 import type { Decision, ToolDefinition, ToolPolicyRule } from '../types/tools.js';
-import type { MCPConfiguration } from '../mcp-config.js';
+import type { MCPConfiguration, McpAuthProviders } from '../mcp-config.js';
 import type { JSONWebToken } from '@salesforce/agentic-common';
 import type { Model, ModelName } from '../models/index.js';
 /**
@@ -88,6 +88,25 @@ export type AgentConfig = {
      */
     defaultToolDecision?: Decision;
 };
+/**
+ * Resolves the per-agent OAuth {@link McpAuthProviders} map (remote MCP server
+ * name → provider) from the agent's id and the config the SDK has on file.
+ * Invoked by `AgentManager` once per agent install (`createAgent`, boot-time
+ * restore) and by `Agent.updateAgentConfig`; the resolved map is normalized by
+ * the SDK (see `normalizeMcpAuthProviders`) and threaded to the harness via
+ * `AgentHarness.createAgent` / `updateAgent`'s `options.mcpAuthProviders`.
+ *
+ * This is the seam that keeps credential-bearing provider objects OFF the
+ * persisted {@link AgentConfig}: providers are supplied here at runtime, never
+ * serialized. Mirrors `HooksForAgent`.
+ *
+ * The callback is sync — the SDK does not await. Return **stable, pre-constructed**
+ * provider instances: returning a NEW provider object for a server on each call
+ * intentionally cycles that server on every update (reference identity is how a
+ * provider swap is detected). Consumers needing async provider setup pre-construct
+ * before returning.
+ */
+export type McpAuthProviderResolver = (agentId: string, config: AgentConfig) => McpAuthProviders | undefined;
 /**
  * Harness-facing configuration for creating/updating an agent.
  *

package/dist/harness/public.d.ts

@@ -45,6 +45,7 @@ export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './
 export type { AgentHooks } from '../types/redaction.js';
 export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
 export { mcpServerConfigEqual } from '../mcp-config.js';
+export type { McpAuthProviders, McpOAuthClientProvider } from '../mcp-config.js';
 export { HarnessBusOwner } from './harness-bus-owner.js';
 export { lowerStreamInput, type InputMessagePart } from './stream-input.js';
 export { GenSink } from './gen-sink.js';

package/dist/index.d.ts

@@ -6,9 +6,9 @@ export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMa
 export type { ResolverResult, ResolverTiers, ToolInvocation } from './policy-resolver.js';
 export type { ContextUsage, FinishReason, UsageMetadata } from './types/usage.js';
 export type { AgentHooks, HooksForAgent, ToolResultRedactor, ToolResultRedactionInput, ToolResultRedactionResult, } from './types/redaction.js';
-export type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness/harness-config.js';
+export type { AgentConfig, HarnessAgentConfig, McpAuthProviderResolver, StreamOptions, } from './harness/harness-config.js';
 export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
-export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
+export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpOAuthClientProvider, McpAuthProviders, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
 export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles, ACCEPTED_MODEL_WIRE_IDS, } from './models/index.js';
 export type { ClaudeModelOverrides, MultimodalFile, SupportedFileFormat, ThinkingMode } from './models/index.js';
@@ -28,7 +28,7 @@ export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent,
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';
 export type { EnvironmentFields } from '@salesforce/agentic-common';
 export { readEnvironmentContext, resolveFeatureId } from '@salesforce/agentic-common';
-export { resolveMcpServerHeaders } from './mcp-auth.js';
+export { resolveMcpServerHeaders, isSalesforcePlatformMcpUrl } from './mcp-auth.js';
 export type { OrgConnection, OrgConnectionFactory } from '@salesforce/agentic-common';
 export type { JSONWebToken, JWTOptions, RequiredJWTHeaders, RequiredJWTPayload } from '@salesforce/agentic-common';
 export { Workspace } from './workspace.js';

package/dist/index.js

@@ -23,6 +23,6 @@ export { WireCommunicationFileWriter, } from './wire-communication-file-writer.j
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
 export { readEnvironmentContext, resolveFeatureId } from '@salesforce/agentic-common';
 // ── MCP Auth ────────────────────────────────────────────────────────
-export { resolveMcpServerHeaders } from './mcp-auth.js';
+export { resolveMcpServerHeaders, isSalesforcePlatformMcpUrl } from './mcp-auth.js';
 export { Workspace } from './workspace.js';
 //# sourceMappingURL=index.js.map

package/dist/mcp-auth.d.ts

@@ -1,4 +1,5 @@
 import type { JSONWebToken } from '@salesforce/agentic-common';
+import type { MCPConfiguration, McpAuthProviders } from './mcp-config.js';
 /**
  * Returns true if the URL matches a Salesforce Hosted MCP Server endpoint.
  * Covers all environments (prod, dev, test, perf, stage) and all API versions
@@ -18,3 +19,22 @@ export declare function isSalesforcePlatformMcpUrl(url: string | URL): boolean;
  * @returns The resolved headers — original headers plus any injected auth.
  */
 export declare function resolveMcpServerHeaders(url: string | URL, orgJwt: JSONWebToken | undefined, headers?: Record<string, string>): Promise<Record<string, string>>;
+/**
+ * Normalizes the raw provider map returned by a consumer's
+ * `mcpAuthProviderResolver` into the map the harness may act on, enforcing the
+ * "one Authorization owner per server" rule centrally (so no harness reimplements
+ * this policy). For each provider entry, keyed by server name:
+ *
+ * - **Dropped** (provider ignored) when the named server is missing, is a stdio
+ *   server, is disabled, or is a Salesforce Platform URL. Salesforce URLs are
+ *   authenticated by the rotating org JWT, which owns auth there; forwarding a
+ *   provider alongside it would arm two competing Authorization owners.
+ * - **Rejected** (throws) when the server carries a static `Authorization`
+ *   header AND a provider — the MCP SDK transport spreads static `requestInit`
+ *   headers OVER the provider token, so the static header would silently win and
+ *   strand the provider in a 401 loop. Failing loud at resolve time beats a
+ *   silent auth failure at runtime.
+ *
+ * Returns a fresh, reference-only map (the same provider instances, never mutated).
+ */
+export declare function normalizeMcpAuthProviders(mcpServers: MCPConfiguration | undefined, resolved: McpAuthProviders | undefined): McpAuthProviders;

package/dist/mcp-auth.js

@@ -2,6 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { AgentSDKError, AgentSDKErrorType } from './errors.js';
 const SALESFORCE_PLATFORM_MCP_URL_REGEX = /^https:\/\/((dev|test|perf|stage)\.)?api\.salesforce\.com\/platform\/mcp\//;
 /**
  * Returns true if the URL matches a Salesforce Hosted MCP Server endpoint.
@@ -37,4 +38,40 @@ export async function resolveMcpServerHeaders(url, orgJwt, headers = {}) {
 function hasAuthorizationHeader(headers) {
     return Object.keys(headers).some((key) => key.toLowerCase() === 'authorization');
 }
+/**
+ * Normalizes the raw provider map returned by a consumer's
+ * `mcpAuthProviderResolver` into the map the harness may act on, enforcing the
+ * "one Authorization owner per server" rule centrally (so no harness reimplements
+ * this policy). For each provider entry, keyed by server name:
+ *
+ * - **Dropped** (provider ignored) when the named server is missing, is a stdio
+ *   server, is disabled, or is a Salesforce Platform URL. Salesforce URLs are
+ *   authenticated by the rotating org JWT, which owns auth there; forwarding a
+ *   provider alongside it would arm two competing Authorization owners.
+ * - **Rejected** (throws) when the server carries a static `Authorization`
+ *   header AND a provider — the MCP SDK transport spreads static `requestInit`
+ *   headers OVER the provider token, so the static header would silently win and
+ *   strand the provider in a 401 loop. Failing loud at resolve time beats a
+ *   silent auth failure at runtime.
+ *
+ * Returns a fresh, reference-only map (the same provider instances, never mutated).
+ */
+export function normalizeMcpAuthProviders(mcpServers, resolved) {
+    if (!resolved || !mcpServers)
+        return {};
+    const normalized = {};
+    for (const [name, provider] of Object.entries(resolved)) {
+        const server = mcpServers[name];
+        if (!server || server.type !== 'remote' || server.enabled === false)
+            continue;
+        if (isSalesforcePlatformMcpUrl(server.url))
+            continue;
+        if (server.headers && hasAuthorizationHeader(server.headers)) {
+            throw new AgentSDKError(`MCP server "${name}" has both a static Authorization header and an OAuth authProvider. ` +
+                `Remove the static Authorization header — the provider owns auth for this server.`, AgentSDKErrorType.INVALID_MCP_AUTH_CONFIG);
+        }
+        normalized[name] = provider;
+    }
+    return normalized;
+}
 //# sourceMappingURL=mcp-auth.js.map

package/dist/mcp-config.d.ts

@@ -35,12 +35,82 @@ export type MCPStdioServerConfig = {
     /** Timeout in milliseconds for individual requests to the server. */
     timeout?: number;
 };
+/**
+ * Harness-neutral contract for an MCP OAuth client provider, letting an
+ * OAuth-protected remote MCP server recover the RFC 9728 `401` challenge its
+ * transport receives (the static {@link MCPRemoteServerConfig.headers} seam
+ * cannot — headers are snapshotted at publish time).
+ *
+ * This package is harness-runtime-free (a lint rule bans importing
+ * `@modelcontextprotocol/*`), so this structurally mirrors the *required* core
+ * of the MCP SDK's `OAuthClientProvider` — same pattern as {@link McpToolAnnotations}.
+ * It is bidirectionally compatible: a real provider assigns to this field, and
+ * this field assigns into the transport option with no cast. Optional upstream
+ * members are omitted (a real instance still carries them at runtime); the
+ * harness-side compile-time drift-guard pins the compatibility.
+ */
+export interface McpOAuthClientProvider {
+    /** URL the user agent is redirected to after authorization (or `undefined` for non-interactive flows). */
+    readonly redirectUrl: string | URL | undefined;
+    /** Metadata about this OAuth client. */
+    readonly clientMetadata: {
+        redirect_uris: string[];
+    };
+    /** Loads this client's registration, or `undefined` if not yet registered. */
+    clientInformation(): {
+        client_id: string;
+    } | undefined | Promise<{
+        client_id: string;
+    } | undefined>;
+    /** Persists a dynamic client registration for later {@link clientInformation} reads. */
+    saveClientInformation?(clientInformation: {
+        client_id: string;
+    }): void | Promise<void>;
+    /** Loads any existing OAuth tokens for the current session, or `undefined`. */
+    tokens(): {
+        access_token: string;
+        token_type: string;
+    } | undefined | Promise<{
+        access_token: string;
+        token_type: string;
+    } | undefined>;
+    /** Stores new OAuth tokens after a successful authorization. */
+    saveTokens(tokens: {
+        access_token: string;
+        token_type: string;
+    }): void | Promise<void>;
+    /** Redirects the user agent to the given URL to begin the authorization flow. */
+    redirectToAuthorization(authorizationUrl: URL): void | Promise<void>;
+    /** Saves a PKCE code verifier before redirecting to the authorization flow. */
+    saveCodeVerifier(codeVerifier: string): void | Promise<void>;
+    /** Loads the PKCE code verifier needed to validate the authorization result. */
+    codeVerifier(): string | Promise<string>;
+}
+/**
+ * A per-agent map of remote MCP server name → its OAuth {@link McpOAuthClientProvider}.
+ *
+ * Providers are behavioral, credential-bearing runtime objects, so they are
+ * NOT part of the persisted {@link MCPConfiguration}. They are supplied at
+ * runtime through the manager's `mcpAuthProviderResolver` and threaded to the
+ * harness via the `createAgent` / `updateAgent` options bag — never serialized
+ * to disk. A harness cycles a server when its provider reference changes.
+ */
+export type McpAuthProviders = Readonly<Record<string, McpOAuthClientProvider>>;
 /** MCP server accessible over HTTP/SSE at a remote URL. */
 export type MCPRemoteServerConfig = {
     type: 'remote';
     /** URL of the remote MCP server endpoint. */
     url: string | URL;
-    /** HTTP headers sent with requests to the server. */
+    /**
+     * HTTP headers sent with requests to the server.
+     *
+     * When an OAuth `authProvider` is supplied for this server (via the
+     * manager's `mcpAuthProviderResolver`), this must NOT carry an
+     * `Authorization` header — the MCP SDK transport spreads static
+     * `requestInit` headers OVER the provider token, so a static
+     * `Authorization` would silently win and strand the provider. The SDK
+     * rejects that combination at resolve time (see `normalizeMcpAuthProviders`).
+     */
     headers?: Record<string, string>;
     /** Whether this server is enabled. Defaults to `true`. */
     enabled?: boolean;
@@ -187,6 +257,8 @@ export type McpToolInfo = {
 export type McpServerErrorCategory = 
 /** 3s default or configured timeout exceeded. */
 'connect-timeout'
+/** OAuth needs user interaction; the host must authorize before reconnecting. */
+ | 'oauth-required'
 /** Unauthorized — JWT missing/expired. */
  | 'http-401'
 /** Forbidden — JWT valid but the principal lacks permission. */
@@ -230,7 +302,7 @@ export type McpServerErrorDetail = {
     code?: number;
     /**
      * Whether the failure is transient (worth a retry via
-     * `Agent.reconnectMcpServer` / `Agent.refreshMcpAuth`) vs fatal (consumer
+     * `Agent.reconnectMcpServer`) vs fatal (consumer
      * must fix config). Harness implementations populate this with their best
      * heuristic; consumers may override per-category.
      */
@@ -259,6 +331,12 @@ export type McpServerErrorDetail = {
  *   strings round-trip; `headers` (key-order-insensitive); `timeout`,
  *   `reconnectionOptions` (field-wise).
  *
+ * This predicate compares only the serializable {@link MCPServerConfig}. A
+ * server's OAuth `authProvider` is NOT part of the config (it is a runtime
+ * binding supplied per-agent via `mcpAuthProviderResolver`); a harness cycles
+ * a server when this predicate fails OR its applied provider reference
+ * changed. See each harness's `updateAgent` diff.
+ *
  * Two configs that pass this predicate but produce different runtime tools
  * (e.g. an upstream stdio server whose binary was overwritten on disk) are
  * NOT detected here — the predicate compares declared config, not runtime

package/dist/mcp-config.js

@@ -40,6 +40,12 @@ export var McpServerStatus;
  *   strings round-trip; `headers` (key-order-insensitive); `timeout`,
  *   `reconnectionOptions` (field-wise).
  *
+ * This predicate compares only the serializable {@link MCPServerConfig}. A
+ * server's OAuth `authProvider` is NOT part of the config (it is a runtime
+ * binding supplied per-agent via `mcpAuthProviderResolver`); a harness cycles
+ * a server when this predicate fails OR its applied provider reference
+ * changed. See each harness's `updateAgent` diff.
+ *
  * Two configs that pass this predicate but produce different runtime tools
  * (e.g. an upstream stdio server whose binary was overwritten on disk) are
  * NOT detected here — the predicate compares declared config, not runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -47,24 +47,24 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.46.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.49.0",
-    "@salesforce/sfdx-agent-harness-openai": "0.15.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.48.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.51.0",
+    "@salesforce/sfdx-agent-harness-openai": "0.17.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.26",
-    "eslint": "^10.8.0",
+    "eslint": "^10.8.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-n": "^18.2.2",
+    "eslint-plugin-n": "^18.3.0",
     "globals": "^17.9.0",
     "lint-staged": "^17.3.0",
     "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
-    "tsx": "^4.23.5",
+    "tsx": "^4.23.12",
     "typescript": "^7.0.2",
-    "typescript-eslint": "^8.66.0",
+    "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.8"
   },
   "engines": {