agents 0.5.1 → 0.6.0

package/dist/{client-storage-D633wI1S.d.ts → client-storage-D5nDLKMW.d.ts}

@@ -1,5 +1,6 @@
-import { t as MCPObservabilityEvent } from "./mcp-DA0kDE7K.js";
+import { n as MCPObservabilityEvent } from "./agent-BHM7Gp_m.js";
 import { AgentMcpOAuthProvider } from "./mcp/do-oauth-client-provider.js";
+import { McpAgent } from "./mcp/index.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import {
   SSEClientTransport,
@@ -12,12 +13,24 @@ import {
 import {
   ElicitRequest,
   ElicitResult,
+  InitializeRequestParams,
+  JSONRPCMessage,
+  MessageExtraInfo,
   Prompt,
+  RequestId,
   Resource,
   ResourceTemplate,
   ServerCapabilities,
   Tool
 } from "@modelcontextprotocol/sdk/types.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  Transport,
+  TransportSendOptions
+} from "@modelcontextprotocol/sdk/shared/transport.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { Client as Client$1 } from "@modelcontextprotocol/sdk/client";
+import { EventStore } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
 //#region src/core/events.d.ts
 interface Disposable {
@@ -33,7 +46,8 @@ declare class Emitter<T> implements Disposable {
 //#endregion
 //#region src/mcp/types.d.ts
 type MaybePromise<T> = T | Promise<T>;
-type BaseTransportType = "sse" | "streamable-http";
+type HttpTransportType = "sse" | "streamable-http";
+type BaseTransportType = HttpTransportType | "rpc";
 type TransportType = BaseTransportType | "auto";
 interface CORSOptions {
   origin?: string;
@@ -48,6 +62,221 @@ interface ServeOptions {
   transport?: BaseTransportType;
   jurisdiction?: DurableObjectJurisdiction;
 }
+type McpClientOptions = ConstructorParameters<typeof Client$1>[1];
+//#endregion
+//#region src/mcp/client-transports.d.ts
+/**
+ * @deprecated Use SSEClientTransport from @modelcontextprotocol/sdk/client/sse.js instead. This alias will be removed in the next major version.
+ */
+declare class SSEEdgeClientTransport extends SSEClientTransport {
+  constructor(url: URL, options: SSEClientTransportOptions);
+}
+/**
+ * @deprecated Use StreamableHTTPClientTransport from @modelcontextprotocol/sdk/client/streamableHttp.js instead. This alias will be removed in the next major version.
+ */
+declare class StreamableHTTPEdgeClientTransport extends StreamableHTTPClientTransport {
+  constructor(url: URL, options: StreamableHTTPClientTransportOptions);
+}
+//#endregion
+//#region src/mcp/worker-transport.d.ts
+interface MCPStorageApi {
+  get(): Promise<TransportState | undefined> | TransportState | undefined;
+  set(state: TransportState): Promise<void> | void;
+}
+interface TransportState {
+  sessionId?: string;
+  initialized: boolean;
+  initializeParams?: InitializeRequestParams;
+}
+interface WorkerTransportOptions {
+  /**
+   * Function that generates a session ID for the transport.
+   * The session ID SHOULD be globally unique and cryptographically secure.
+   * Return undefined to disable session management (stateless mode).
+   */
+  sessionIdGenerator?: () => string;
+  /**
+   * Enable traditional Request/Response mode, this will disable streaming.
+   */
+  enableJsonResponse?: boolean;
+  /**
+   * Callback fired when a new session is initialized.
+   */
+  onsessioninitialized?: (sessionId: string) => void;
+  /**
+   * Callback fired when a session is closed via DELETE request.
+   */
+  onsessionclosed?: (sessionId: string) => void;
+  corsOptions?: CORSOptions;
+  /**
+   * Optional storage api for persisting transport state.
+   * Use this to store session state in Durable Object/Agent storage
+   * so it survives hibernation/restart.
+   */
+  storage?: MCPStorageApi;
+  /**
+   * Event store for resumability support.
+   * If provided, enables clients to reconnect and resume messages using Last-Event-ID.
+   */
+  eventStore?: EventStore;
+  /**
+   * Retry interval in milliseconds to suggest to clients in SSE retry field.
+   * Controls client reconnection timing for polling behavior.
+   */
+  retryInterval?: number;
+}
+declare class WorkerTransport implements Transport {
+  started: boolean;
+  private initialized;
+  private sessionIdGenerator?;
+  private enableJsonResponse;
+  private onsessioninitialized?;
+  private onsessionclosed?;
+  private standaloneSseStreamId;
+  private streamMapping;
+  private requestToStreamMapping;
+  private requestResponseMap;
+  private corsOptions?;
+  private storage?;
+  private stateRestored;
+  private eventStore?;
+  private retryInterval?;
+  private initializeParams?;
+  sessionId?: string;
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void;
+  constructor(options?: WorkerTransportOptions);
+  /**
+   * Restore transport state from persistent storage.
+   * This is automatically called on start.
+   */
+  private restoreState;
+  /**
+   * Persist current transport state to storage.
+   */
+  private saveState;
+  start(): Promise<void>;
+  /**
+   * Validates the MCP-Protocol-Version header on incoming requests.
+   *
+   * This performs a simple check: if a version header is present, it must be
+   * in the SUPPORTED_PROTOCOL_VERSIONS list. We do not track the negotiated
+   * version or enforce version consistency across requests - the SDK handles
+   * version negotiation during initialization, and we simply reject any
+   * explicitly unsupported versions.
+   *
+   * - Header present and supported: Accept
+   * - Header present and unsupported: 400 Bad Request
+   * - Header missing: Accept (version validation is optional)
+   */
+  private validateProtocolVersion;
+  private getHeaders;
+  handleRequest(request: Request, parsedBody?: unknown): Promise<Response>;
+  private handleGetRequest;
+  private handlePostRequest;
+  private handleDeleteRequest;
+  private handleOptionsRequest;
+  private handleUnsupportedRequest;
+  private validateSession;
+  close(): Promise<void>;
+  /**
+   * Close an SSE stream for a specific request, triggering client reconnection.
+   * Use this to implement polling behavior during long-running operations -
+   * client will reconnect after the retry interval specified in the priming event.
+   */
+  closeSSEStream(requestId: RequestId): void;
+  send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
+}
+//#endregion
+//#region src/mcp/auth-context.d.ts
+interface McpAuthContext {
+  props: Record<string, unknown>;
+}
+declare function getMcpAuthContext(): McpAuthContext | undefined;
+//#endregion
+//#region src/mcp/handler.d.ts
+interface CreateMcpHandlerOptions extends WorkerTransportOptions {
+  /**
+   * The route path that this MCP handler should respond to.
+   * If specified, the handler will only process requests that match this route.
+   * @default "/mcp"
+   */
+  route?: string;
+  /**
+   * An optional auth context to use for handling MCP requests.
+   * If not provided, the handler will look for props in the execution context.
+   */
+  authContext?: McpAuthContext;
+  /**
+   * An optional transport to use for handling MCP requests.
+   * If not provided, a WorkerTransport will be created with the provided WorkerTransportOptions.
+   */
+  transport?: WorkerTransport;
+}
+declare function createMcpHandler(
+  server: McpServer | Server,
+  options?: CreateMcpHandlerOptions
+): (request: Request, env: unknown, ctx: ExecutionContext) => Promise<Response>;
+/**
+ * @deprecated This has been renamed to createMcpHandler, and experimental_createMcpHandler will be removed in the next major version
+ */
+declare function experimental_createMcpHandler(
+  server: McpServer | Server,
+  options?: CreateMcpHandlerOptions
+): (request: Request, env: unknown, ctx: ExecutionContext) => Promise<Response>;
+//#endregion
+//#region src/mcp/rpc.d.ts
+declare const RPC_DO_PREFIX = "rpc:";
+interface RPCClientTransportOptions<T extends McpAgent = McpAgent> {
+  namespace: DurableObjectNamespace<T>;
+  name: string;
+  props?: Record<string, unknown>;
+}
+declare class RPCClientTransport implements Transport {
+  private _namespace;
+  private _name;
+  private _props?;
+  private _stub?;
+  private _started;
+  private _protocolVersion?;
+  sessionId?: string;
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void;
+  constructor(options: RPCClientTransportOptions<McpAgent>);
+  setProtocolVersion(version: string): void;
+  getProtocolVersion(): string | undefined;
+  start(): Promise<void>;
+  close(): Promise<void>;
+  send(
+    message: JSONRPCMessage | JSONRPCMessage[],
+    options?: TransportSendOptions
+  ): Promise<void>;
+}
+interface RPCServerTransportOptions {
+  timeout?: number;
+}
+declare class RPCServerTransport implements Transport {
+  private _started;
+  private _pendingResponse;
+  private _responseResolver;
+  private _protocolVersion?;
+  private _timeout;
+  sessionId?: string;
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void;
+  constructor(options?: RPCServerTransportOptions);
+  setProtocolVersion(version: string): void;
+  getProtocolVersion(): string | undefined;
+  start(): Promise<void>;
+  close(): Promise<void>;
+  send(message: JSONRPCMessage, _options?: TransportSendOptions): Promise<void>;
+  handle(
+    message: JSONRPCMessage | JSONRPCMessage[]
+  ): Promise<JSONRPCMessage | JSONRPCMessage[] | undefined>;
+}
 //#endregion
 //#region src/mcp/client-connection.d.ts
 /**
@@ -71,9 +300,14 @@ declare const MCPConnectionState: {
  */
 type MCPConnectionState =
   (typeof MCPConnectionState)[keyof typeof MCPConnectionState];
+/**
+ * Transport options for MCP client connections.
+ * Combines transport-specific options with auth provider and type selection.
+ */
 type MCPTransportOptions = (
   | SSEClientTransportOptions
   | StreamableHTTPClientTransportOptions
+  | RPCClientTransportOptions
 ) & {
   authProvider?: AgentMcpOAuthProvider;
   type?: TransportType;
@@ -91,7 +325,7 @@ declare class MCPClientConnection {
   url: URL;
   options: {
     transport: MCPTransportOptions;
-    client: ConstructorParameters<typeof Client>[1];
+    client: McpClientOptions;
   };
   client: Client;
   connectionState: MCPConnectionState;
@@ -112,7 +346,7 @@ declare class MCPClientConnection {
     info: ConstructorParameters<typeof Client>[0],
     options?: {
       transport: MCPTransportOptions;
-      client: ConstructorParameters<typeof Client>[1];
+      client: McpClientOptions;
     }
   );
   /**
@@ -320,7 +554,7 @@ declare class MCPClientConnection {
    */
   getTransport(
     transportType: BaseTransportType
-  ): StreamableHTTPClientTransport | SSEClientTransport;
+  ): StreamableHTTPClientTransport | SSEClientTransport | RPCClientTransport;
   private tryConnect;
   private _capabilityErrorHandler;
 }
@@ -340,16 +574,31 @@ type MCPServerRow = {
 };
 //#endregion
 export {
-  BaseTransportType as a,
-  ServeOptions as c,
-  Event as d,
+  ServeOptions as C,
+  Event as E,
+  McpClientOptions as S,
+  Emitter as T,
+  WorkerTransportOptions as _,
+  RPCClientTransport as a,
+  BaseTransportType as b,
+  RPCServerTransportOptions as c,
+  createMcpHandler as d,
+  experimental_createMcpHandler as f,
+  WorkerTransport as g,
+  TransportState as h,
   MCPTransportOptions as i,
-  TransportType as l,
+  RPC_DO_PREFIX as l,
+  getMcpAuthContext as m,
   MCPClientConnection as n,
-  CORSOptions as o,
+  RPCClientTransportOptions as o,
+  McpAuthContext as p,
   MCPConnectionState as r,
-  MaybePromise as s,
+  RPCServerTransport as s,
   MCPServerRow as t,
-  Emitter as u
+  CreateMcpHandlerOptions as u,
+  SSEEdgeClientTransport as v,
+  TransportType as w,
+  MaybePromise as x,
+  StreamableHTTPEdgeClientTransport as y
 };
-//# sourceMappingURL=client-storage-D633wI1S.d.ts.map
+//# sourceMappingURL=client-storage-D5nDLKMW.d.ts.map

package/dist/experimental/forever.d.ts

@@ -1,5 +1,5 @@
 import { RetryOptions } from "../retries.js";
-import "../client-storage-D633wI1S.js";
+import "../client-storage-D5nDLKMW.js";
 import { Agent, Schedule } from "../index.js";
 
 //#region src/experimental/forever.d.ts

package/dist/index.d.ts

@@ -5,14 +5,15 @@ import {
 import { EmailResolver, createHeaderBasedEmailResolver } from "./email.js";
 import { RetryOptions } from "./retries.js";
 import {
-  l as TransportType,
-  r as MCPConnectionState
-} from "./client-storage-D633wI1S.js";
+  r as MCPConnectionState,
+  w as TransportType
+} from "./client-storage-D5nDLKMW.js";
 import {
   AgentMcpOAuthProvider,
   AgentsOAuthProvider,
   DurableObjectOAuthClientProvider
 } from "./mcp/do-oauth-client-provider.js";
+import { McpAgent } from "./mcp/index.js";
 import { MCPClientManager } from "./mcp/client.js";
 import {
   RunWorkflowOptions,
@@ -204,6 +205,12 @@ type AddMcpServerOptions = {
   } /** Retry options for connection and reconnection attempts */;
   retry?: RetryOptions;
 };
+/**
+ * Options for adding an MCP server via RPC (Durable Object binding)
+ */
+type AddRpcMcpServerOptions = {
+  /** Props to pass to the McpAgent instance */ props?: Record<string, unknown>;
+};
 /**
  * Default options for Agent configuration.
  * Child classes can override specific options without spreading.
@@ -944,6 +951,8 @@ declare class Agent<
    * Returns undefined if no match found - use options.agentBinding as fallback.
    */
   private _findAgentBindingName;
+  private _findBindingNameForNamespace;
+  private _restoreRpcMcpServers;
   /**
    * Handle a callback from a workflow.
    * Called when the Agent receives a callback at /_workflow/callback.
@@ -1023,29 +1032,30 @@ declare class Agent<
     state?: unknown
   ): void;
   /**
-   * Connect to a new MCP Server
+   * Connect to a new MCP Server via RPC (Durable Object binding)
    *
-   * @example
-   * // Simple usage
-   * await this.addMcpServer("github", "https://mcp.github.com");
+   * The binding name and props are persisted to storage so the connection
+   * is automatically restored after Durable Object hibernation.
    *
    * @example
-   * // With options (preferred for custom headers, transport, etc.)
-   * await this.addMcpServer("github", "https://mcp.github.com", {
-   *   transport: { headers: { "Authorization": "Bearer ..." } }
-   * });
+   * await this.addMcpServer("counter", env.MY_MCP);
+   * await this.addMcpServer("counter", env.MY_MCP, { props: { userId: "123" } });
+   */
+  addMcpServer<T extends McpAgent>(
+    serverName: string,
+    binding: DurableObjectNamespace<T>,
+    options?: AddRpcMcpServerOptions
+  ): Promise<{
+    id: string;
+    state: typeof MCPConnectionState.READY;
+  }>;
+  /**
+   * Connect to a new MCP Server via HTTP (SSE or Streamable HTTP)
    *
    * @example
-   * // Legacy 5-parameter signature (still supported)
-   * await this.addMcpServer("github", url, callbackHost, agentsPrefix, options);
-   *
-   * @param serverName Name of the MCP server
-   * @param url MCP Server URL
-   * @param callbackHostOrOptions Options object, or callback host string (legacy)
-   * @param agentsPrefix agents routing prefix if not using `agents` (legacy)
-   * @param options MCP client and transport options (legacy)
-   * @returns Server id and state - either "authenticating" with authUrl, or "ready"
-   * @throws If connection or discovery fails
+   * await this.addMcpServer("github", "https://mcp.github.com");
+   * await this.addMcpServer("github", "https://mcp.github.com", { transport: { type: "sse" } });
+   * await this.addMcpServer("github", url, callbackHost, agentsPrefix, options); // legacy
    */
   addMcpServer(
     serverName: string,
@@ -1068,7 +1078,6 @@ declare class Agent<
     | {
         id: string;
         state: typeof MCPConnectionState.READY;
-        authUrl?: undefined;
       }
   >;
   removeMcpServer(id: string): Promise<void>;
@@ -1223,6 +1232,7 @@ declare class StreamingResponse {
 //#endregion
 export {
   AddMcpServerOptions,
+  AddRpcMcpServerOptions,
   Agent,
   AgentContext,
   type AgentMcpOAuthProvider,

package/dist/index.js

@@ -3,7 +3,7 @@ import { camelCaseToKebabCase } from "./utils.js";
 import { createHeaderBasedEmailResolver, signAgentHeaders } from "./email.js";
 import { __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context.js";
 import { isErrorRetryable, tryN, validateRetryOptions } from "./retries.js";
-import { i as DisposableStore, n as MCPConnectionState } from "./client-connection-CGMuV62J.js";
+import { a as RPC_DO_PREFIX, n as MCPConnectionState, s as DisposableStore } from "./client-connection-BqngKttp.js";
 import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider.js";
 import { MCPClientManager } from "./mcp/client.js";
 import { genericObservability } from "./observability/index.js";
@@ -66,6 +66,7 @@ const unstable_callable = (metadata = {}) => {
 function getNextCronTime(cron) {
 	return parseCronExpression(cron).getNextDate();
 }
+let _didWarnRpcExperimental = false;
 const STATE_ROW_ID = "cf_state_row_id";
 const STATE_WAS_CHANGED = "cf_state_was_changed";
 const DEFAULT_STATE = {};
@@ -606,6 +607,7 @@ var Agent = class Agent extends Server {
 			}, async () => {
 				await this._tryCatch(async () => {
 					await this.mcp.restoreConnectionsFromStorage(this.name);
+					await this._restoreRpcMcpServers();
 					this.broadcastMcpServers();
 					this._checkOrphanedWorkflows();
 					return _onStart(props);
@@ -2096,6 +2098,37 @@ var Agent = class Agent extends Server {
 			if (key === className || camelCaseToKebabCase(key) === camelCaseToKebabCase(className)) return key;
 		}
 	}
+	_findBindingNameForNamespace(namespace) {
+		for (const [key, value] of Object.entries(this.env)) if (value === namespace) return key;
+	}
+	async _restoreRpcMcpServers() {
+		const rpcServers = this.mcp.getRpcServersFromStorage();
+		for (const server of rpcServers) {
+			if (this.mcp.mcpConnections[server.id]) continue;
+			const opts = server.server_options ? JSON.parse(server.server_options) : {};
+			const namespace = this.env[opts.bindingName];
+			if (!namespace) {
+				console.warn(`[Agent] Cannot restore RPC MCP server "${server.name}": binding "${opts.bindingName}" not found in env`);
+				continue;
+			}
+			const normalizedName = server.server_url.replace(RPC_DO_PREFIX, "");
+			try {
+				await this.mcp.connect(`${RPC_DO_PREFIX}${normalizedName}`, {
+					reconnect: { id: server.id },
+					transport: {
+						type: "rpc",
+						namespace,
+						name: normalizedName,
+						props: opts.props
+					}
+				});
+				const conn = this.mcp.mcpConnections[server.id];
+				if (conn && conn.connectionState === MCPConnectionState.CONNECTED) await this.mcp.discoverIfConnected(server.id);
+			} catch (error) {
+				console.error(`[Agent] Error restoring RPC MCP server "${server.name}":`, error);
+			}
+		}
+	}
 	/**
 	* Handle a callback from a workflow.
 	* Called when the Agent receives a callback at /_workflow/callback.
@@ -2202,63 +2235,90 @@ var Agent = class Agent extends Server {
 			});
 		} else if (action === "reset") this.setState(this.initialState);
 	}
-	/**
-	* Connect to a new MCP Server
-	*
-	* @example
-	* // Simple usage
-	* await this.addMcpServer("github", "https://mcp.github.com");
-	*
-	* @example
-	* // With options (preferred for custom headers, transport, etc.)
-	* await this.addMcpServer("github", "https://mcp.github.com", {
-	*   transport: { headers: { "Authorization": "Bearer ..." } }
-	* });
-	*
-	* @example
-	* // Legacy 5-parameter signature (still supported)
-	* await this.addMcpServer("github", url, callbackHost, agentsPrefix, options);
-	*
-	* @param serverName Name of the MCP server
-	* @param url MCP Server URL
-	* @param callbackHostOrOptions Options object, or callback host string (legacy)
-	* @param agentsPrefix agents routing prefix if not using `agents` (legacy)
-	* @param options MCP client and transport options (legacy)
-	* @returns Server id and state - either "authenticating" with authUrl, or "ready"
-	* @throws If connection or discovery fails
-	*/
-	async addMcpServer(serverName, url, callbackHostOrOptions, agentsPrefix, options) {
+	async addMcpServer(serverName, urlOrBinding, callbackHostOrOptions, agentsPrefix, options) {
+		const existingServer = this.mcp.listServers().find((s) => s.name === serverName);
+		if (existingServer && this.mcp.mcpConnections[existingServer.id]) {
+			const conn = this.mcp.mcpConnections[existingServer.id];
+			if (conn.connectionState === MCPConnectionState.AUTHENTICATING && conn.options.transport.authProvider?.authUrl) return {
+				id: existingServer.id,
+				state: MCPConnectionState.AUTHENTICATING,
+				authUrl: conn.options.transport.authProvider.authUrl
+			};
+			if (conn.connectionState === MCPConnectionState.FAILED) throw new Error(`MCP server "${serverName}" is in failed state: ${conn.connectionError}`);
+			return {
+				id: existingServer.id,
+				state: MCPConnectionState.READY
+			};
+		}
+		if (typeof urlOrBinding !== "string") {
+			if (!_didWarnRpcExperimental) {
+				_didWarnRpcExperimental = true;
+				console.warn("[agents] addMcpServer with a Durable Object binding (RPC transport) is experimental. The API may change between releases. We'd love your feedback: https://github.com/cloudflare/agents/issues/548");
+			}
+			const rpcOpts = callbackHostOrOptions;
+			const normalizedName = serverName.toLowerCase().replace(/\s+/g, "-");
+			const reconnectId = existingServer?.id;
+			const { id } = await this.mcp.connect(`${RPC_DO_PREFIX}${normalizedName}`, {
+				reconnect: reconnectId ? { id: reconnectId } : void 0,
+				transport: {
+					type: "rpc",
+					namespace: urlOrBinding,
+					name: normalizedName,
+					props: rpcOpts?.props
+				}
+			});
+			const conn = this.mcp.mcpConnections[id];
+			if (conn && conn.connectionState === MCPConnectionState.CONNECTED) {
+				const discoverResult = await this.mcp.discoverIfConnected(id);
+				if (discoverResult && !discoverResult.success) throw new Error(`Failed to discover MCP server capabilities: ${discoverResult.error}`);
+			} else if (conn && conn.connectionState === MCPConnectionState.FAILED) throw new Error(`Failed to connect to MCP server "${serverName}" via RPC: ${conn.connectionError}`);
+			const bindingName = this._findBindingNameForNamespace(urlOrBinding);
+			if (bindingName) this.mcp.saveRpcServerToStorage(id, serverName, normalizedName, bindingName, rpcOpts?.props);
+			return {
+				id,
+				state: MCPConnectionState.READY
+			};
+		}
+		const url = urlOrBinding;
+		const httpOptions = callbackHostOrOptions;
 		let resolvedCallbackHost;
 		let resolvedAgentsPrefix;
 		let resolvedOptions;
 		let resolvedCallbackPath;
-		if (typeof callbackHostOrOptions === "object" && callbackHostOrOptions !== null) {
-			resolvedCallbackHost = callbackHostOrOptions.callbackHost;
-			resolvedCallbackPath = callbackHostOrOptions.callbackPath;
-			resolvedAgentsPrefix = callbackHostOrOptions.agentsPrefix ?? "agents";
+		if (typeof httpOptions === "object" && httpOptions !== null) {
+			resolvedCallbackHost = httpOptions.callbackHost;
+			resolvedCallbackPath = httpOptions.callbackPath;
+			resolvedAgentsPrefix = httpOptions.agentsPrefix ?? "agents";
 			resolvedOptions = {
-				client: callbackHostOrOptions.client,
-				transport: callbackHostOrOptions.transport,
-				retry: callbackHostOrOptions.retry
+				client: httpOptions.client,
+				transport: httpOptions.transport,
+				retry: httpOptions.retry
 			};
 		} else {
-			resolvedCallbackHost = callbackHostOrOptions;
+			resolvedCallbackHost = httpOptions;
 			resolvedAgentsPrefix = agentsPrefix ?? "agents";
 			resolvedOptions = options;
 		}
-		if (!this._resolvedOptions.sendIdentityOnConnect && !resolvedCallbackPath) throw new Error("callbackPath is required in addMcpServer options when sendIdentityOnConnect is false — the default callback URL would expose the instance name. Provide a callbackPath and route the callback request to this agent via getAgentByName.");
+		if (!this._resolvedOptions.sendIdentityOnConnect && resolvedCallbackHost && !resolvedCallbackPath) throw new Error("callbackPath is required in addMcpServer options when sendIdentityOnConnect is false — the default callback URL would expose the instance name. Provide a callbackPath and route the callback request to this agent via getAgentByName.");
 		if (!resolvedCallbackHost) {
 			const { request } = getCurrentAgent();
-			if (!request) throw new Error("callbackHost is required when not called within a request context");
-			const requestUrl = new URL(request.url);
-			resolvedCallbackHost = `${requestUrl.protocol}//${requestUrl.host}`;
+			if (request) {
+				const requestUrl = new URL(request.url);
+				resolvedCallbackHost = `${requestUrl.protocol}//${requestUrl.host}`;
+			}
+		}
+		let callbackUrl;
+		if (resolvedCallbackHost) {
+			const normalizedHost = resolvedCallbackHost.replace(/\/$/, "");
+			callbackUrl = resolvedCallbackPath ? `${normalizedHost}/${resolvedCallbackPath.replace(/^\//, "")}` : `${normalizedHost}/${resolvedAgentsPrefix}/${camelCaseToKebabCase(this._ParentClass.name)}/${this.name}/callback`;
 		}
-		const normalizedHost = resolvedCallbackHost.replace(/\/$/, "");
-		const callbackUrl = resolvedCallbackPath ? `${normalizedHost}/${resolvedCallbackPath.replace(/^\//, "")}` : `${normalizedHost}/${resolvedAgentsPrefix}/${camelCaseToKebabCase(this._ParentClass.name)}/${this.name}/callback`;
 		await this.mcp.ensureJsonSchema();
 		const id = nanoid(8);
-		const authProvider = this.createMcpOAuthProvider(callbackUrl);
-		authProvider.serverId = id;
+		let authProvider;
+		if (callbackUrl) {
+			authProvider = this.createMcpOAuthProvider(callbackUrl);
+			authProvider.serverId = id;
+		}
 		const transportType = resolvedOptions?.transport?.type ?? "auto";
 		let headerTransportOpts = {};
 		if (resolvedOptions?.transport?.headers) headerTransportOpts = {
@@ -2282,11 +2342,14 @@ var Agent = class Agent extends Server {
 		});
 		const result = await this.mcp.connectToServer(id);
 		if (result.state === MCPConnectionState.FAILED) throw new Error(`Failed to connect to MCP server at ${url}: ${result.error}`);
-		if (result.state === MCPConnectionState.AUTHENTICATING) return {
-			id,
-			state: result.state,
-			authUrl: result.authUrl
-		};
+		if (result.state === MCPConnectionState.AUTHENTICATING) {
+			if (!callbackUrl) throw new Error("This MCP server requires OAuth authentication. Provide callbackHost in addMcpServer options to enable the OAuth flow.");
+			return {
+				id,
+				state: result.state,
+				authUrl: result.authUrl
+			};
+		}
 		const discoverResult = await this.mcp.discoverIfConnected(id);
 		if (discoverResult && !discoverResult.success) throw new Error(`Failed to discover MCP server capabilities: ${discoverResult.error}`);
 		return {