@objectstack/connector-mcp 14.8.0 → 15.1.0

package/src/connector-mcp-plugin.ts

@@ -1,13 +1,19 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { Plugin, PluginContext } from '@objectstack/core';
-import type { Connector } from '@objectstack/spec/integration';
+import type { Connector, ConnectorProviderFactory } from '@objectstack/spec/integration';
 import { createMcpConnector, type McpConnectorOptions } from './mcp-connector.js';
+import {
+    createMcpProviderFactory,
+    MCP_PROVIDER_KEY,
+    type McpDeclarativeStdioPolicy,
+} from './mcp-provider.js';
 
 /**
  * Minimal surface of the automation engine this plugin depends on — the
- * connector registry from ADR-0018 §Addendum. Kept structural so the plugin
- * needs no runtime dependency on `@objectstack/service-automation`.
+ * connector registry (ADR-0018 §Addendum) plus the provider registry (ADR-0097).
+ * Kept structural so the plugin needs no runtime dependency on
+ * `@objectstack/service-automation`.
  */
 export interface ConnectorRegistrySurface {
     registerConnector(
@@ -18,26 +24,49 @@ export interface ConnectorRegistrySurface {
         >,
     ): void;
     unregisterConnector(name: string): void;
+    registerConnectorProvider(providerKey: string, factory: ConnectorProviderFactory): void;
 }
 
-export interface ConnectorMcpPluginOptions extends McpConnectorOptions {}
+/**
+ * Options for {@link ConnectorMcpPlugin}. All optional (ADR-0097): with no
+ * `transport` the plugin contributes only the `mcp` provider factory — so a
+ * stack can declare `provider: 'mcp'` instances as pure metadata. Supply a
+ * `transport` to ALSO connect one hand-wired MCP server at `start()`.
+ */
+export interface ConnectorMcpPluginOptions extends Partial<McpConnectorOptions> {
+    /**
+     * Policy for stdio transports on **declarative** `provider: 'mcp'`
+     * instances (#3055). Default **deny**: metadata (including a runtime Studio
+     * publish) must not spawn local processes unless the host opts in.
+     * `string[]` allowlists specific commands; `true` allows any. Hand-wired
+     * connectors configured via these plugin options are not subject to it —
+     * their command lives in host code, not metadata.
+     */
+    declarativeStdio?: McpDeclarativeStdioPolicy;
+}
 
 /**
- * ConnectorMcpPlugin — connects to an MCP server, discovers its tools, and
- * registers them as a single connector on the automation engine (ADR-0024).
- * One generic adapter, configured per server (transport + `include`), never
- * per-server code.
+ * ConnectorMcpPlugin — contributes the generic MCP adapter (ADR-0024) in two forms:
+ *
+ *  1. **Provider factory** (`mcp`, ADR-0097): registered at `init()` so the
+ *     automation service can materialize declarative `provider: 'mcp'`
+ *     `connectors:` entries — connecting to the server and mapping its tools to
+ *     connector actions — at boot.
+ *  2. **Hand-wired instance** (optional, back-compat): when constructed with a
+ *     `transport`, it also connects that one server at `start()` and registers
+ *     the resulting connector.
  *
- * Lifecycle: on `start()` it connects and builds the connector once; on
- * `stop()` it tears the MCP connection down. If no automation engine is present
- * — or the server is unreachable at boot — the plugin logs and skips: a missing
- * optional connector is not a fatal error (same posture as `ConnectorRestPlugin`).
+ * Lifecycle: on `start()` a configured instance connects and builds the
+ * connector once; on `destroy()` it tears the MCP connection down. If no
+ * automation engine is present — or the server is unreachable at boot — the
+ * hand-wired path logs and skips: a missing optional connector is not fatal
+ * (unlike a *declarative* provider-bound instance, which fails boot loudly).
  */
 export class ConnectorMcpPlugin implements Plugin {
     name = 'com.objectstack.connector.mcp';
     version = '1.0.0';
     type = 'standard' as const;
-    // Ensure the automation engine (and its connector registry) is started first.
+    // Ensure the automation engine (and its connector/provider registries) exist first.
     dependencies = ['com.objectstack.service-automation'];
 
     private readonly options: ConnectorMcpPluginOptions;
@@ -45,23 +74,31 @@ export class ConnectorMcpPlugin implements Plugin {
     private automation?: ConnectorRegistrySurface;
     private close?: () => Promise<void>;
 
-    constructor(options: ConnectorMcpPluginOptions) {
+    constructor(options: ConnectorMcpPluginOptions = {}) {
         this.options = options;
     }
 
-    async init(_ctx: PluginContext): Promise<void> {
-        // No services to register; the connector is registered in start() once
-        // the automation engine is available and the MCP server has been queried.
+    async init(ctx: PluginContext): Promise<void> {
+        // Contribute the `mcp` provider factory (ADR-0097) before the automation
+        // service materializes declarative instances during its start().
+        const automation = this.tryGetAutomation(ctx);
+        if (automation && typeof automation.registerConnectorProvider === 'function') {
+            automation.registerConnectorProvider(
+                MCP_PROVIDER_KEY,
+                createMcpProviderFactory({
+                    clientFactory: this.options.clientFactory,
+                    declarativeStdio: this.options.declarativeStdio,
+                }),
+            );
+            ctx.logger.info("ConnectorMcpPlugin: registered 'mcp' connector provider");
+        }
     }
 
     async start(ctx: PluginContext): Promise<void> {
-        let automation: ConnectorRegistrySurface | undefined;
-        try {
-            automation = ctx.getService<ConnectorRegistrySurface>('automation');
-        } catch {
-            automation = undefined;
-        }
+        // Provider-only usage (no transport) contributes just the factory in init().
+        if (!this.options.transport) return;
 
+        const automation = this.tryGetAutomation(ctx);
         if (!automation || typeof automation.registerConnector !== 'function') {
             ctx.logger.info('ConnectorMcpPlugin: no automation engine — MCP connector not registered');
             return;
@@ -69,7 +106,7 @@ export class ConnectorMcpPlugin implements Plugin {
 
         let bundle;
         try {
-            bundle = await createMcpConnector(this.options);
+            bundle = await createMcpConnector(this.options as McpConnectorOptions);
         } catch (err) {
             // The MCP server is unreachable / failed discovery at boot. Skip the
             // optional connector rather than failing the whole bootstrap.
@@ -101,4 +138,12 @@ export class ConnectorMcpPlugin implements Plugin {
             try { await this.close(); } catch { /* ignore */ }
         }
     }
+
+    private tryGetAutomation(ctx: PluginContext): ConnectorRegistrySurface | undefined {
+        try {
+            return ctx.getService<ConnectorRegistrySurface>('automation');
+        } catch {
+            return undefined;
+        }
+    }
 }

package/src/index.ts

@@ -31,3 +31,9 @@ export {
     type ConnectorMcpPluginOptions,
     type ConnectorRegistrySurface,
 } from './connector-mcp-plugin.js';
+export {
+    createMcpProviderFactory,
+    MCP_PROVIDER_KEY,
+    type McpProviderDeps,
+    type McpDeclarativeStdioPolicy,
+} from './mcp-provider.js';

package/src/mcp-provider.test.ts

@@ -0,0 +1,193 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// ADR-0097 — the `mcp` provider factory: materialize a declarative
+// `provider: 'mcp'` connector instance by connecting to the server (an injected
+// fake client here), listing its tools, and mapping them to actions.
+
+import { describe, it, expect } from 'vitest';
+import type { ConnectorProviderContext } from '@objectstack/spec/integration';
+import { isConnectorUpstreamUnavailable } from '@objectstack/spec/integration';
+import type { McpClientLike, McpToolDescriptor, McpTransport } from './mcp-connector.js';
+import { createMcpProviderFactory, MCP_PROVIDER_KEY } from './mcp-provider.js';
+
+const TOOLS: McpToolDescriptor[] = [
+    { name: 'create_issue', description: 'Create an issue', inputSchema: { type: 'object' } },
+    { name: 'list_issues', description: 'List issues' },
+];
+
+/** Capture the transport the factory built, and serve fixed tools. */
+function fakeClientFactory() {
+    const seen: { transport?: McpTransport } = {};
+    let closed = false;
+    const factory = async (transport: McpTransport): Promise<McpClientLike> => {
+        seen.transport = transport;
+        return {
+            listTools: async () => TOOLS,
+            callTool: async () => ({ content: [{ type: 'text', text: 'ok' }] }),
+            close: async () => { closed = true; },
+        };
+    };
+    return { factory, seen, isClosed: () => closed };
+}
+
+function ctx(partial: Partial<ConnectorProviderContext> & Pick<ConnectorProviderContext, 'providerConfig'>): ConnectorProviderContext {
+    return { name: 'github', label: 'GitHub', type: 'api', ...partial };
+}
+
+describe('mcp provider factory (ADR-0097)', () => {
+    it('advertises the mcp provider key', () => {
+        expect(MCP_PROVIDER_KEY).toBe('mcp');
+    });
+
+    it('connects, lists tools, and maps them to actions', async () => {
+        const { factory: clientFactory } = fakeClientFactory();
+        // stdio on a declarative instance requires the host opt-in (#3055).
+        const factory = createMcpProviderFactory({ clientFactory, declarativeStdio: ['my-mcp'] });
+        const mat = await factory(ctx({ providerConfig: { transport: { kind: 'stdio', command: 'my-mcp' } } }));
+        expect(mat.def.name).toBe('github');
+        expect(Object.keys(mat.handlers).sort()).toEqual(['create_issue', 'list_issues']);
+        expect(typeof mat.close).toBe('function');
+    });
+
+    it('applies the tool allowlist from providerConfig.include', async () => {
+        const { factory: clientFactory } = fakeClientFactory();
+        const factory = createMcpProviderFactory({ clientFactory, declarativeStdio: ['my-mcp'] });
+        const mat = await factory(
+            ctx({ providerConfig: { transport: { kind: 'stdio', command: 'my-mcp' }, include: ['create_issue'] } }),
+        );
+        expect(Object.keys(mat.handlers)).toEqual(['create_issue']);
+    });
+
+    it('folds resolved bearer auth into an http transport header', async () => {
+        const captured = fakeClientFactory();
+        const factory = createMcpProviderFactory({ clientFactory: captured.factory });
+        await factory(
+            ctx({
+                providerConfig: { transport: { kind: 'http', url: 'https://mcp.example.com' } },
+                auth: { type: 'bearer', token: 'tok' },
+            }),
+        );
+        const t = captured.seen.transport;
+        expect(t?.kind).toBe('http');
+        expect(t?.kind === 'http' && t.headers?.Authorization).toBe('Bearer tok');
+    });
+
+    it('throws when the transport is missing', async () => {
+        const factory = createMcpProviderFactory();
+        await expect(factory(ctx({ providerConfig: {} }))).rejects.toThrow(/providerConfig\.transport/);
+    });
+
+    it('throws for an unknown transport kind', async () => {
+        const factory = createMcpProviderFactory();
+        await expect(
+            factory(ctx({ providerConfig: { transport: { kind: 'carrier-pigeon' } } })),
+        ).rejects.toThrow(/kind must be 'stdio' or 'http'/);
+    });
+});
+
+// ── #3017 — fault classification: config stays fatal, upstream degrades ─────
+
+describe('mcp provider fault classification (#3017)', () => {
+    const stdio = { transport: { kind: 'stdio', command: 'my-mcp' } };
+    const allowMyMcp = { declarativeStdio: ['my-mcp'] };
+
+    it('classifies a connect failure as upstream-unavailable (retryable), keeping the cause', async () => {
+        const boom = new Error('connect ECONNREFUSED 127.0.0.1:9999');
+        const clientFactory = async (): Promise<McpClientLike> => { throw boom; };
+        const factory = createMcpProviderFactory({ clientFactory, ...allowMyMcp });
+
+        const err = await factory(ctx({ providerConfig: stdio })).then(
+            () => { throw new Error('expected rejection'); },
+            (e: unknown) => e,
+        );
+        expect(isConnectorUpstreamUnavailable(err)).toBe(true);
+        expect((err as Error).message).toMatch(/'github' could not reach its MCP server/);
+        expect((err as Error).message).toContain('ECONNREFUSED');
+        expect((err as { cause?: unknown }).cause).toBe(boom);
+    });
+
+    it('classifies a tools/list failure as upstream-unavailable and closes the client', async () => {
+        let closed = false;
+        const clientFactory = async (): Promise<McpClientLike> => ({
+            listTools: async () => { throw new Error('request timed out'); },
+            callTool: async () => ({}),
+            close: async () => { closed = true; },
+        });
+        const factory = createMcpProviderFactory({ clientFactory, ...allowMyMcp });
+
+        const err = await factory(ctx({ providerConfig: stdio })).then(
+            () => { throw new Error('expected rejection'); },
+            (e: unknown) => e,
+        );
+        expect(isConnectorUpstreamUnavailable(err)).toBe(true);
+        expect(closed).toBe(true); // discovery failure must not leak the connection
+    });
+
+    it('keeps transport-shape faults plain — configuration errors stay fatal at boot', async () => {
+        const factory = createMcpProviderFactory();
+        const err = await factory(ctx({ providerConfig: {} })).then(
+            () => { throw new Error('expected rejection'); },
+            (e: unknown) => e,
+        );
+        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
+    });
+});
+
+// ── #3055 — declarative stdio policy: default-deny + host allowlist ─────────
+//
+// A declarative stdio transport spawns a local process from metadata (a Studio
+// publish reaches materialization at runtime), so it is gated OFF unless the
+// host opts in. Violations are CONFIGURATION faults: plain throw (fatal at
+// boot, skipped on reload) — never upstream-unavailable, which would retry a
+// security rejection into existence.
+
+describe('mcp provider declarative stdio policy (#3055)', () => {
+    const stdioCfg = { transport: { kind: 'stdio', command: 'my-mcp' } };
+
+    it('DENIES a declarative stdio transport by default, as a plain (non-retryable) fault', async () => {
+        const { factory: clientFactory, seen } = fakeClientFactory();
+        const factory = createMcpProviderFactory({ clientFactory }); // no policy
+        const err = await factory(ctx({ providerConfig: stdioCfg })).then(
+            () => { throw new Error('expected rejection'); },
+            (e: unknown) => e,
+        );
+        expect((err as Error).message).toMatch(/stdio transports are disabled by default/);
+        expect((err as Error).message).toContain("declarativeStdio: ['my-mcp']"); // actionable opt-in hint
+        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
+        expect(seen.transport).toBeUndefined(); // rejected before any connection attempt
+    });
+
+    it('allowlist admits exactly the listed command and rejects others', async () => {
+        const { factory: clientFactory } = fakeClientFactory();
+        const factory = createMcpProviderFactory({ clientFactory, declarativeStdio: ['npx', 'my-mcp'] });
+        const mat = await factory(ctx({ providerConfig: stdioCfg }));
+        expect(mat.def.name).toBe('github');
+
+        const err = await factory(
+            ctx({ providerConfig: { transport: { kind: 'stdio', command: 'bash' } } }),
+        ).then(
+            () => { throw new Error('expected rejection'); },
+            (e: unknown) => e,
+        );
+        expect((err as Error).message).toMatch(/not in the host's declarativeStdio allowlist \[npx, my-mcp\]/);
+        expect(isConnectorUpstreamUnavailable(err)).toBe(false);
+    });
+
+    it('declarativeStdio: true allows any command (explicit full trust)', async () => {
+        const { factory: clientFactory } = fakeClientFactory();
+        const factory = createMcpProviderFactory({ clientFactory, declarativeStdio: true });
+        const mat = await factory(
+            ctx({ providerConfig: { transport: { kind: 'stdio', command: 'anything' } } }),
+        );
+        expect(Object.keys(mat.handlers).length).toBeGreaterThan(0);
+    });
+
+    it('http transports are NOT subject to the policy', async () => {
+        const { factory: clientFactory } = fakeClientFactory();
+        const factory = createMcpProviderFactory({ clientFactory }); // default-deny policy in force
+        const mat = await factory(
+            ctx({ providerConfig: { transport: { kind: 'http', url: 'https://mcp.example.com' } } }),
+        );
+        expect(mat.def.name).toBe('github');
+    });
+});

package/src/mcp-provider.ts

@@ -0,0 +1,205 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ConnectorProviderFactory, ResolvedConnectorAuth } from '@objectstack/spec/integration';
+import { ConnectorUpstreamUnavailableError } from '@objectstack/spec/integration';
+import { createMcpConnector, type McpConnectorOptions, type McpTransport } from './mcp-connector.js';
+
+/**
+ * The provider key this package contributes (ADR-0097). A declarative
+ * `connectors:` entry with `provider: 'mcp'` is materialized by this factory.
+ */
+export const MCP_PROVIDER_KEY = 'mcp';
+
+/**
+ * Host policy for **declarative** stdio transports (#3055). A stdio transport
+ * launches a local child process, and declarative entries arrive through
+ * metadata — including a runtime Studio publish — so spawning from them is
+ * gated OFF by default:
+ *
+ *  - `undefined` / `false` — deny (default): a `provider: 'mcp'` entry with a
+ *    stdio transport is rejected as a configuration fault.
+ *  - `string[]` — allowlist: the transport's `command` must strictly equal one
+ *    of the listed commands. NOTE this is a coarse trust boundary — listing a
+ *    launcher like `npx` effectively allows any package it can run; list the
+ *    specific server binaries you trust. Sandboxed execution is the enterprise
+ *    tier (ADR-0024 §4).
+ *  - `true` — allow any command (explicit full trust; hosts that treat every
+ *    metadata author as an operator).
+ *
+ * Hand-wired connectors (plugin instance options / `createMcpConnector`) are
+ * NOT subject to this policy: their command was written in host code, a
+ * different trust anchor than metadata.
+ */
+export type McpDeclarativeStdioPolicy = boolean | string[];
+
+/** Injectable dependencies for {@link createMcpProviderFactory} (tests). */
+export interface McpProviderDeps {
+  /** Injected MCP client factory; defaults to the SDK-backed client. */
+  clientFactory?: McpConnectorOptions['clientFactory'];
+  /** Policy for declarative stdio transports (#3055). Default: deny. */
+  declarativeStdio?: McpDeclarativeStdioPolicy;
+}
+
+/** Shape of `providerConfig` for a `provider: 'mcp'` declarative instance. */
+interface McpProviderConfig {
+  /** How to reach the MCP server (stdio or streamable-http). */
+  transport?: unknown;
+  /** Optional tool-name allowlist — only these tools become actions. */
+  include?: unknown;
+}
+
+function isStringRecord(v: unknown): v is Record<string, string> {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return false;
+  return Object.values(v as Record<string, unknown>).every((x) => typeof x === 'string');
+}
+
+/**
+ * Fold the resolved instance `auth` into an MCP **http** transport's headers
+ * (ADR-0024 keeps MCP credentials with the transport). `credentialRef` has
+ * already been resolved upstream, so this only maps the static credential to the
+ * right header. Not applied to stdio transports — a stdio server receives its
+ * credentials through `transport.env`.
+ */
+function applyAuthToHeaders(
+  auth: ResolvedConnectorAuth | undefined,
+  headers: Record<string, string>,
+): void {
+  if (!auth || auth.type === 'none') return;
+  switch (auth.type) {
+    case 'bearer':
+      headers['Authorization'] = `Bearer ${auth.token}`;
+      return;
+    case 'basic':
+      headers['Authorization'] = `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString('base64')}`;
+      return;
+    case 'api-key':
+      // Header-based only for MCP http (query-param keys are not part of the transport).
+      if (!auth.paramName) headers[auth.headerName ?? 'X-API-Key'] = auth.key;
+      return;
+  }
+}
+
+/** Validate + normalize `providerConfig.transport`, injecting resolved auth for http. */
+function normalizeTransport(
+  raw: unknown,
+  connectorName: string,
+  auth: ResolvedConnectorAuth | undefined,
+): McpTransport {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error(
+      `connector-mcp provider: connector '${connectorName}' requires providerConfig.transport ` +
+        `({ kind: 'stdio', command, ... } or { kind: 'http', url, ... }).`,
+    );
+  }
+  const t = raw as Record<string, unknown>;
+  if (t.kind === 'stdio') {
+    if (typeof t.command !== 'string' || t.command.length === 0) {
+      throw new Error(
+        `connector-mcp provider: connector '${connectorName}' stdio transport requires a 'command' string.`,
+      );
+    }
+    return {
+      kind: 'stdio',
+      command: t.command,
+      args: Array.isArray(t.args) ? t.args.map((a) => String(a)) : undefined,
+      env: isStringRecord(t.env) ? t.env : undefined,
+    };
+  }
+  if (t.kind === 'http') {
+    if (typeof t.url !== 'string' || t.url.length === 0) {
+      throw new Error(
+        `connector-mcp provider: connector '${connectorName}' http transport requires a 'url' string.`,
+      );
+    }
+    const headers: Record<string, string> = { ...(isStringRecord(t.headers) ? t.headers : {}) };
+    applyAuthToHeaders(auth, headers);
+    return { kind: 'http', url: t.url, headers: Object.keys(headers).length > 0 ? headers : undefined };
+  }
+  throw new Error(
+    `connector-mcp provider: connector '${connectorName}' providerConfig.transport.kind must be 'stdio' or 'http'.`,
+  );
+}
+
+/**
+ * Enforce the {@link McpDeclarativeStdioPolicy} for one declarative instance
+ * (#3055). Throws a **plain** Error on violation: a security-policy rejection
+ * is a configuration fault — fatal at boot, skipped+logged on reload — and must
+ * never be classified upstream-unavailable (it cannot be retried into
+ * existence).
+ */
+function assertDeclarativeStdioAllowed(
+  policy: McpDeclarativeStdioPolicy | undefined,
+  command: string,
+  connectorName: string,
+): void {
+  if (policy === true) return;
+  if (Array.isArray(policy)) {
+    if (policy.includes(command)) return;
+    throw new Error(
+      `connector-mcp provider: connector '${connectorName}' declares a stdio transport with command '${command}', ` +
+        `which is not in the host's declarativeStdio allowlist [${policy.join(', ')}]. ` +
+        `Add the command to new ConnectorMcpPlugin({ declarativeStdio: [...] }) if this server is trusted (#3055).`,
+    );
+  }
+  throw new Error(
+    `connector-mcp provider: connector '${connectorName}' declares a stdio transport (command '${command}'), ` +
+      `but declarative stdio transports are disabled by default — a stdio transport launches a local process ` +
+      `from stack metadata (including runtime Studio publishes). If this server is trusted, opt in deliberately: ` +
+      `new ConnectorMcpPlugin({ declarativeStdio: ['${command}'] }) — or use an http transport (#3055, ADR-0024 §4).`,
+  );
+}
+
+/**
+ * Build the `mcp` {@link ConnectorProviderFactory} (ADR-0097 / ADR-0024). At boot
+ * the automation service invokes it for each `provider: 'mcp'` declarative
+ * instance: it connects to the MCP server named by `providerConfig.transport`,
+ * lists its tools, and produces the same `{ def, handlers, close }` bundle
+ * {@link createMcpConnector} builds for a hand-wired MCP connector — one action
+ * per tool, dispatched to the server's `tools/call`.
+ *
+ * Stdio transports on declarative instances are policy-gated (default deny) —
+ * see {@link McpDeclarativeStdioPolicy} (#3055).
+ *
+ * The connection is opened at materialization. Faults are classified (#3017):
+ * an invalid transport shape is a *configuration* fault and throws plain —
+ * fatal at boot per the ADR-0097 fail-loud contract — while a connect /
+ * `tools/list` failure (server down, refused, timed out) is an *operational*
+ * fault and throws {@link ConnectorUpstreamUnavailableError}, which the
+ * materializer turns into a degraded instance that is retried with backoff
+ * instead of aborting the whole app boot.
+ */
+export function createMcpProviderFactory(deps: McpProviderDeps = {}): ConnectorProviderFactory {
+  return async (ctx) => {
+    const cfg = (ctx.providerConfig ?? {}) as McpProviderConfig;
+    const transport = normalizeTransport(cfg.transport, ctx.name, ctx.auth);
+    if (transport.kind === 'stdio') {
+      assertDeclarativeStdioAllowed(deps.declarativeStdio, transport.command, ctx.name);
+    }
+    const includeList = Array.isArray(cfg.include)
+      ? cfg.include.filter((x): x is string => typeof x === 'string')
+      : undefined;
+    const include = includeList ? (toolName: string) => includeList.includes(toolName) : undefined;
+
+    let bundle;
+    try {
+      bundle = await createMcpConnector({
+        name: ctx.name,
+        label: ctx.label,
+        description: ctx.description,
+        transport,
+        include,
+        clientFactory: deps.clientFactory,
+      });
+    } catch (err) {
+      // Everything past transport validation is talking to the server (connect,
+      // handshake, tools/list) — operational, hence retryable. A credential the
+      // server rejects also lands here: indistinguishable from the outside, and
+      // retrying it is loud (logged per attempt), never silent.
+      throw new ConnectorUpstreamUnavailableError(
+        `connector-mcp provider: connector '${ctx.name}' could not reach its MCP server: ${(err as Error).message}`,
+        { cause: err },
+      );
+    }
+    return { def: bundle.def, handlers: bundle.handlers, close: bundle.close };
+  };
+}