Default addSpec baseUrl from the spec's servers; explicit [] means no auth

RhysSullivan · RhysSullivan · commit 98c87fda6d6a · 2026-06-11T16:54:22.000-07:00
Refinements from review of the derivation fallback:

- baseUrl now also derives from the spec's first server when the caller
  passes none (same default the add page applies). Without it, a
  headless add produced tools with no host to call — every invocation
  failed with a bare 'HTTP request failed'.
- An explicit empty authenticationTemplate now means 'no auth methods'
  and suppresses derivation. The add page sends the user's edited
  method list even when emptied, so deleting every detected method in
  the inspect step survives instead of being silently re-derived.
- The addSpec tool description documents both defaults and the
  override semantics.
- The e2e scenario now adds the integration purely by spec URL — the
  Resend emulator serves its own /openapi.json now — with no baseUrl
  and no template, so both derivations are covered by the live
  paste-key flow and the emulator ledger check.
diff --git a/e2e/scenarios/connect-handoff.test.ts b/e2e/scenarios/connect-handoff.test.ts
@@ -32,51 +32,17 @@ const unique = (prefix: string) => `${prefix}_${randomBytes(4).toString("hex")}`
 
 const EMULATOR_BASE = "https://resend.emulators.dev";
 
-/** Minimal Resend-shaped OpenAPI subset pointed at the emulator. Bearer auth
- *  mirrors the real provider (and the Sentry spec that failed in prod): the
- *  add-account modal must render a paste-a-token flow from a bare
- *  `http`/`bearer` security scheme, not just from an explicit apiKey
- *  authenticationTemplate. */
-const resendSpec = {
-  openapi: "3.0.3",
-  info: { title: "Resend (emulated)", version: "1.0.0" },
-  paths: {
-    "/emails": {
-      post: {
-        operationId: "sendEmail",
-        tags: ["emails"],
-        requestBody: {
-          required: true,
-          content: {
-            "application/json": {
-              schema: {
-                type: "object",
-                properties: {
-                  from: { type: "string" },
-                  to: { type: "string" },
-                  subject: { type: "string" },
-                  html: { type: "string" },
-                },
-                required: ["from", "to", "subject"],
-              },
-            },
-          },
-        },
-        responses: { "200": { description: "sent" } },
-      },
-    },
-  },
-  components: {
-    securitySchemes: { auth_token: { type: "http", scheme: "bearer" } },
-  },
-  security: [{ auth_token: [] }],
-} as const;
+// The emulator serves its own OpenAPI document (bearer auth, same shape as
+// real Resend — and as the Sentry spec that failed in prod). Adding it by URL
+// with no authenticationTemplate exercises exactly the agentic path: the
+// add-account modal must render a paste-a-token flow derived from the spec's
+// bare `http`/`bearer` security scheme.
+const EMULATOR_SPEC_URL = `${EMULATOR_BASE}/openapi.json`;
 
 const addSpecCode = (slug: string) => `
 const added = await tools.executor.openapi.addSpec({
-  spec: { kind: "blob", value: ${JSON.stringify(JSON.stringify(resendSpec))} },
+  spec: { kind: "url", url: ${JSON.stringify(EMULATOR_SPEC_URL)} },
   slug: ${JSON.stringify(slug)},
-  baseUrl: ${JSON.stringify(EMULATOR_BASE)},
 });
 return added.ok ? { ok: true, slug: added.data.slug, toolCount: added.data.toolCount } : { ok: false, error: added.error };
 `;
diff --git a/packages/plugins/openapi/src/react/AddOpenApiSource.tsx b/packages/plugins/openapi/src/react/AddOpenApiSource.tsx
@@ -318,7 +318,13 @@ export default function AddOpenApiSource(props: {
         slug: resolvedSourceId,
         description: resolvedDisplayName,
         baseUrl: resolvedBaseUrl,
-        ...(!isGoogleBundlePreset && editedAuthenticationTemplate.length > 0
+        // Always send the edited method list (even empty) when the user has
+        // inspected a preview: an explicit [] means "no auth methods", while
+        // OMITTING the field tells the server to derive defaults from the
+        // spec — which would silently resurrect methods the user deleted.
+        // The Google bundle path stays omitted; its auth is converter-derived
+        // server-side.
+        ...(!isGoogleBundlePreset
           ? {
               // Serialize to the wire input dialect (apikey → request-shaped).
               authenticationTemplate: editedAuthenticationTemplate.map(openApiWireAuthInput),
diff --git a/packages/plugins/openapi/src/sdk/plugin.test.ts b/packages/plugins/openapi/src/sdk/plugin.test.ts
@@ -557,6 +557,65 @@ describe("OpenAPI Plugin", () => {
     ),
   );
 
+  it.effect("addSpec defaults baseUrl to the spec's first server when omitted", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const server = yield* servePluginTestApi();
+        const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
+
+        // No baseUrl passed — the spec's own servers entry must fill it, or
+        // every invocation on the integration fails with no host to call.
+        // oxlint-disable-next-line executor/no-json-parse -- boundary: test fixture surgery on the test server's own spec JSON
+        const spec = JSON.parse(server.specJson) as Record<string, unknown>;
+        const specWithServer = JSON.stringify({
+          ...spec,
+          servers: [{ url: server.baseUrl }],
+        });
+
+        yield* executor.openapi.addSpec({
+          spec: { kind: "blob", value: specWithServer },
+          slug: "derived_base_api",
+        });
+
+        const config = yield* executor.openapi.getConfig("derived_base_api");
+        expect(config?.baseUrl).toBe(server.baseUrl);
+      }),
+    ),
+  );
+
+  it.effect("addSpec treats an explicit empty authenticationTemplate as no auth", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const server = yield* servePluginTestApi();
+        const executor = yield* createExecutor(makeTestConfig({ plugins: testPlugins() }));
+
+        // The add page sends [] when the user deletes every detected method.
+        // That intent must survive — deriving methods back from the spec here
+        // would silently override the user's choice.
+        // oxlint-disable-next-line executor/no-json-parse -- boundary: test fixture surgery on the test server's own spec JSON
+        const spec = JSON.parse(server.specJson) as Record<string, unknown>;
+        const specWithBearer = JSON.stringify({
+          ...spec,
+          components: {
+            ...(spec.components as Record<string, unknown> | undefined),
+            securitySchemes: { auth_token: { type: "http", scheme: "bearer" } },
+          },
+          security: [{ auth_token: [] }],
+        });
+
+        yield* executor.openapi.addSpec({
+          spec: { kind: "blob", value: specWithBearer },
+          slug: "no_auth_api",
+          baseUrl: server.baseUrl,
+          authenticationTemplate: [],
+        });
+
+        const config = yield* executor.openapi.getConfig("no_auth_api");
+        expect(config?.authenticationTemplate ?? []).toEqual([]);
+      }),
+    ),
+  );
+
   it.effect("removeSpec cleans up the integration and its tools", () =>
     Effect.scoped(
       Effect.gen(function* () {
diff --git a/packages/plugins/openapi/src/sdk/plugin.ts b/packages/plugins/openapi/src/sdk/plugin.ts
@@ -41,7 +41,7 @@ import { extract } from "./extract";
 import { compileToolDefinitions, type ToolDefinition } from "./definitions";
 import { annotationsForOperation, invokeWithLayer } from "./invoke";
 import { previewSpec, previewSpecText, type SpecPreview } from "./preview";
-import { deriveAuthenticationTemplateFromPreview } from "./derive-auth";
+import { deriveAuthenticationTemplateFromPreview, firstBaseUrlForPreview } from "./derive-auth";
 import { openApiPresets } from "./presets";
 import { makeDefaultOpenapiStore, type OpenapiStore, type StoredOperation } from "./store";
 import type { Authentication } from "./types";
@@ -710,18 +710,31 @@ export const openApiPlugin = definePlugin((options?: OpenApiPluginOptions) => {
           const resolved = yield* resolveSpecForInput(config.spec, httpClientLayer);
           const compiled = yield* compileSpec(resolved.specText);
 
-          // No explicit template and nothing converter-derived → fall back to
-          // the spec's own declared auth (same derivation the add page runs on
-          // its preview). Without this, headless callers (MCP, API) silently
-          // produce auth-less integrations whose Add-connection modal is a
-          // dead end — see e2e/scenarios/connect-handoff.test.ts.
+          // Defaults the add page derives from its preview, applied here so
+          // headless callers (MCP, API) get the same integration the UI's
+          // add flow would produce — see e2e/scenarios/connect-handoff.test.ts:
+          //   - baseUrl: the spec's first server (else tools have no host to
+          //     call and every invocation fails with "HTTP request failed")
+          //   - authenticationTemplate: the spec's declared security schemes
+          //     (else the Add-connection modal is a dead "No authentication"
+          //     end with nowhere to paste a credential)
+          // An explicit input always wins; for auth, an explicit EMPTY array
+          // means "no auth methods" and suppresses the derivation.
+          const explicitBaseUrl = config.baseUrl ?? resolved.baseUrl;
+          const needsDerivedBaseUrl = explicitBaseUrl == null;
+          const needsDerivedAuth =
+            config.authenticationTemplate == null && resolved.authenticationTemplate == null;
+          const preview =
+            needsDerivedBaseUrl || needsDerivedAuth
+              ? yield* previewSpecText(resolved.specText)
+              : undefined;
+          const derivedBaseUrl =
+            needsDerivedBaseUrl && preview ? firstBaseUrlForPreview(preview) : undefined;
+          const effectiveBaseUrl = explicitBaseUrl ?? (derivedBaseUrl || undefined);
           const derivedAuthenticationTemplate =
-            config.authenticationTemplate || resolved.authenticationTemplate
-              ? undefined
-              : deriveAuthenticationTemplateFromPreview(
-                  yield* previewSpecText(resolved.specText),
-                  config.baseUrl ?? resolved.baseUrl,
-                );
+            needsDerivedAuth && preview
+              ? deriveAuthenticationTemplateFromPreview(preview, effectiveBaseUrl)
+              : undefined;
 
           const slug = IntegrationSlug.make(config.slug);
 
@@ -743,9 +756,7 @@ export const openApiPlugin = definePlugin((options?: OpenApiPluginOptions) => {
             ...(specInputToGoogleBundle(config.spec) !== undefined
               ? { googleDiscoveryUrls: specInputToGoogleBundle(config.spec) }
               : {}),
-            ...((config.baseUrl ?? resolved.baseUrl)
-              ? { baseUrl: config.baseUrl ?? resolved.baseUrl }
-              : {}),
+            ...(effectiveBaseUrl ? { baseUrl: effectiveBaseUrl } : {}),
             ...(config.headers ? { headers: config.headers } : {}),
             ...(config.queryParams ? { queryParams: config.queryParams } : {}),
             // Prefer the caller's explicit template; otherwise adopt the one the
@@ -899,7 +910,7 @@ export const openApiPlugin = definePlugin((options?: OpenApiPluginOptions) => {
           tool({
             name: "addSpec",
             description:
-              "Add an OpenAPI integration to the catalog and persist its operations as tools. Recommended flow: call `previewSpec`, choose a `slug`, declare an `authenticationTemplate` for how a credential is applied (apiKey header/query, or oauth bearer), then create a connection for that integration with the user's API key or via `oauth.start`.",
+              "Add an OpenAPI integration to the catalog and persist its operations as tools. Recommended flow: call `previewSpec`, choose a `slug`, then create a connection for that integration with the user's API key or via `oauth.start`. When `baseUrl` is omitted it defaults to the spec's first server; when `authenticationTemplate` is omitted the auth methods are derived from the spec's declared security schemes (pass an explicit template to override how a credential is applied — apiKey header/query, or oauth bearer — or an empty array for no auth methods).",
             annotations: {
               requiresApproval: true,
               approvalDescription: "Add an OpenAPI integration",
