feat(sdk): add URL-only mode with init() and isUrlMode

Support direct provider URLs via `urls` option, bypassing directory
lookup. CLI/MCP uses client.init() for discovery and filters out
search_providers in URL mode.

Made-with: Cursor

Author: Bekacru

packages/cli/src/client.ts

@@ -20,9 +20,11 @@ function openBrowser(url: string): void {
 
 export function createClient(config: ClientConfig = {}): AgentAuthClient {
   const storage = new FileStorage(config.storageDir);
+  const urlMode = (config.urls?.length ?? 0) > 0;
   return new AgentAuthClient({
     storage,
-    directoryUrl: config.directoryUrl ?? process.env.AGENT_AUTH_DIRECTORY_URL,
+    urls: config.urls,
+    directoryUrl: urlMode ? undefined : (config.directoryUrl ?? process.env.AGENT_AUTH_DIRECTORY_URL),
     hostName: config.hostName ?? process.env.AGENT_AUTH_HOST_NAME,
     providers: config.providers as any,
     onApprovalRequired(info) {

packages/cli/src/mcp.ts

@@ -87,20 +87,13 @@ function jsonSchemaToZod(params: ToolParameters): ZodRawShape | undefined {
 export async function startMcpServer(config: ClientConfig): Promise<void> {
   const client = createClient(config);
 
-  if (config.urls?.length) {
-    await Promise.all(
-      config.urls.map(async (url) => {
-        try {
-          await client.discoverProvider(url);
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          console.error(`Warning: could not discover ${url}: ${msg}`);
-        }
-      }),
-    );
-  }
+  await client.init();
 
-  const tools = getAgentAuthTools(client);
+  let tools = getAgentAuthTools(client);
+
+  if (client.isUrlMode) {
+    tools = filterTools(tools, { exclude: ["search_providers"] });
+  }
 
   const server = new McpServer(
     { name: "auth-agent", version: "0.1.0" },

packages/sdk/src/client.ts

@@ -65,12 +65,21 @@ export class AgentAuthClient {
   private readonly onApprovalStatusChange: ((status: AgentStatus) => void | Promise<void>) | null;
   private readonly approvalTimeoutMs: number;
   private readonly abortController: AbortController;
+  private readonly urls: string[] | null;
 
   constructor(opts: AgentAuthClientOptions = {}) {
     this.storage = opts.storage ?? new MemoryStorage();
     this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
-    this.directoryUrl = opts.directoryUrl ?? "https://agent-auth.directory";
-    this.allowDirectDiscovery = opts.allowDirectDiscovery ?? !this.directoryUrl;
+    const urlMode = (opts.urls?.length ?? 0) > 0;
+    this.urls = urlMode ? opts.urls! : null;
+    this.directoryUrl =
+      opts.directoryUrl !== undefined
+        ? opts.directoryUrl
+        : urlMode
+          ? null
+          : "https://agent-auth.directory";
+    this.allowDirectDiscovery =
+      opts.allowDirectDiscovery ?? (urlMode ? true : !this.directoryUrl);
     this.jwtExpirySeconds = opts.jwtExpirySeconds ?? 60;
     this.hostName = opts.hostName ?? detectHostName();
     this.onApprovalRequired = opts.onApprovalRequired ?? null;
@@ -85,6 +94,32 @@ export class AgentAuthClient {
     }
   }
 
+  /**
+   * Initialize the client — discovers any URLs passed via the `urls`
+   * option. Call this once after construction when using URL-only mode.
+   * Returns the discovered provider configs (failures are logged, not thrown).
+   */
+  async init(): Promise<ProviderConfig[]> {
+    if (!this.urls?.length) return [];
+    const results = await Promise.allSettled(
+      this.urls.map((url) => this.discoverProvider(url)),
+    );
+    const configs: ProviderConfig[] = [];
+    for (const r of results) {
+      if (r.status === "fulfilled") {
+        configs.push(r.value);
+      }
+    }
+    return configs;
+  }
+
+  /**
+   * Whether the client is in URL-only mode (no directory).
+   */
+  get isUrlMode(): boolean {
+    return this.urls !== null && this.urls.length > 0;
+  }
+
   /**
    * Cancel all in-flight polling loops (approval, async execution)
    * and prevent new ones from starting. Call this when tearing down

packages/sdk/src/types.ts

@@ -335,6 +335,16 @@ export interface AgentAuthClientOptions {
    * @default true when no directoryUrl, false when directoryUrl is set
    */
   allowDirectDiscovery?: boolean;
+  /**
+   * Provider URLs to discover at startup.
+   * When set, the directory is disabled and only these providers
+   * are available — `listProviders` returns only them,
+   * `searchProviders` is unavailable, and `search` is cache-only.
+   *
+   * Callers must await {@link AgentAuthClient.init | `init()`} after
+   * construction to complete URL discovery.
+   */
+  urls?: string[];
   /**
    * Pre-configured providers. Skips discovery for these.
    */