@zackbart/connecta 0.18.1 → 0.18.3

package/dist/connectors/remote-mcp.js

@@ -3,6 +3,26 @@ import { KvOAuthProvider } from "../auth/downstream-oauth.js";
 import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
 import { ConnectorCallError } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
+/**
+ * Apply a maintained provider's slot copy and header framing to credential
+ * auth the deployment left bare.
+ *
+ * A provider knows what its own key is called and how the endpoint expects it
+ * framed; a deployment that states either one keeps its answer. Every other
+ * auth shape passes through untouched, so a provider can hand this its whole
+ * `auth` option without branching first.
+ */
+export function withCredentialDefaults(auth, defaults) {
+    if (auth.type !== "credential")
+        return auth;
+    return {
+        ...auth,
+        credential: auth.credential ?? defaults.credential,
+        ...(auth.scheme === undefined && defaults.scheme !== undefined
+            ? { scheme: defaults.scheme }
+            : {}),
+    };
+}
 /**
  * How long a downstream gets to answer the session-termination DELETE before
  * teardown stops waiting. This is a network round-trip budget, deliberately
@@ -160,6 +180,65 @@ async function terminateSession(transport, logger, connectorId) {
         });
     });
 }
+const encoder = new TextEncoder();
+/** Base64 of a UTF-8 string, Web-API only so the core still runs on workerd. */
+function base64Utf8(value) {
+    let binary = "";
+    for (const byte of encoder.encode(value)) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+/**
+ * Hex SHA-256 of a credential, used only to notice that a cached client
+ * connected with a value the vault no longer holds. WebCrypto rather than a
+ * `node:` hash: the whole core has to keep running unchanged on Workers.
+ */
+async function digestOf(value) {
+    const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+    let hex = "";
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, "0");
+    return hex;
+}
+/**
+ * Assemble the one header a credential-auth connector sends.
+ *
+ * A scheme ending in `Basic` names HTTP Basic credentials wherever a provider
+ * nests it, so the `user:secret` it frames is base64-encoded — that is what
+ * makes plain `Basic` and Mixpanel's `Bearer Basic` one rule instead of two.
+ */
+function credentialHeaderValue(scheme, value) {
+    if (scheme === null)
+        return value;
+    return /(?:^|\s)basic$/i.test(scheme)
+        ? `${scheme} ${base64Utf8(value)}`
+        : `${scheme} ${value}`;
+}
+/**
+ * True when a stored credential carries a character a header cannot.
+ *
+ * The fetch specification refuses NUL, CR, and LF outright, and the runtime
+ * that refuses them says so in a `TypeError` that quotes the whole offending
+ * value — a message that would otherwise travel to the agent. The remaining C0
+ * controls and DEL are refused here too: no real API key contains one, and a
+ * paste that picked one up is a paste to redo rather than a request to send.
+ * Leading and trailing whitespace is already gone by the time this runs.
+ *
+ * A scan rather than a regular expression, because a character class over the
+ * control range is exactly what `no-control-regex` exists to flag, and the
+ * suppression would be less readable than the loop it suppressed.
+ */
+function carriesIllegalHeaderChar(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/** RFC 9110 field-name token, checked once at construction. */
+const HEADER_NAME_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 function isLoopbackHost(hostname) {
     return (hostname === "localhost" ||
         hostname === "127.0.0.1" ||
@@ -273,6 +352,29 @@ export function remoteMcp(id, opts) {
     const closedScopes = new WeakSet();
     const isOauth = opts.auth?.type === "oauth";
     const logger = opts.logger ?? console;
+    const credentialAuth = opts.auth?.type === "credential" ? opts.auth : undefined;
+    if (credentialAuth?.credential?.fields?.length) {
+        throw new Error(`[connecta] connector "${id}" credential auth declares named fields; ` +
+            "this shape sends one secret in one header and reads the reserved " +
+            "`value` field only.");
+    }
+    const credentialConfig = credentialAuth?.credential ?? {
+        label: "API key",
+    };
+    const credentialHeader = credentialAuth?.header?.trim() || "Authorization";
+    // A structural mistake in the deployment file, beside the `fields` refusal
+    // above: an unsendable header name is not worth discovering on the first
+    // request, where only a runtime error can report it.
+    if (credentialAuth && !HEADER_NAME_TOKEN.test(credentialHeader)) {
+        throw new Error(`[connecta] connector "${id}" credential auth declares header ` +
+            `"${credentialHeader}", which is not a valid HTTP field name.`);
+    }
+    // `undefined` means "not stated" and takes the bearer default; `null` and
+    // `""` both mean "send the stored value verbatim", which some providers
+    // require for a bare API key.
+    const credentialScheme = credentialAuth === undefined || credentialAuth.scheme === undefined
+        ? "Bearer"
+        : (credentialAuth.scheme?.trim() ?? "") || null;
     // Check the destination scheme once at construction: buildTransport (and the
     // SDK's fetch) attach any static credentials to every request, so an http://
     // endpoint sends bearer tokens / API keys in cleartext. Loopback is exempt
@@ -283,7 +385,10 @@ export function remoteMcp(id, opts) {
         if (opts.requireHttps) {
             throw new Error(`[connecta] connector "${id}" url ${opts.url} is not https:// (and not loopback) — refusing to connect (requireHttps).`);
         }
-        if (opts.auth?.type === "headers") {
+        // Both static shapes send a secret on every request; that an operator
+        // typed one into /credentials rather than a deployment file changes who
+        // owns it, not whether the wire carries it in the clear.
+        if (opts.auth?.type === "headers" || credentialAuth) {
             logger.warn(`[connecta] connector "${id}" sends static credentials to ${opts.url} over a non-https:// connection — those tokens will be transmitted in cleartext.`);
         }
     }
@@ -295,6 +400,77 @@ export function remoteMcp(id, opts) {
         }
     }
     const operatorDisconnectedError = () => new OperatorDisconnectedError();
+    /**
+     * The credential slot is declared but the vault has nothing in it (or has no
+     * key to read it with). Deliberately the same `auth_required` code an absent
+     * OAuth grant produces: the agent's next move is `authorize_connector`
+     * either way, and that tool reads `connector.credential` to hand the
+     * operator `/credentials` instead of a consent URL.
+     */
+    class CredentialRequiredError extends ConnectorCallError {
+        constructor(message) {
+            super("auth_required", message);
+        }
+    }
+    /**
+     * Read this request's credential. Called before every connect and before
+     * trusting any cached client, so an operator's replacement is picked up
+     * without a redeploy. The value stays in the caller's local scope.
+     */
+    const readCredential = async (ctx) => {
+        if (!ctx.credential) {
+            throw new CredentialRequiredError(`Connector "${id}" needs an operator-managed credential, but ` +
+                "credential storage is not configured. Set " +
+                "credentials.encryptionKey and redeploy.");
+        }
+        // A stored-shape mismatch already arrives as a typed auth_required from
+        // the registry's accessor; nothing to reclassify here.
+        const value = (await ctx.credential.get())?.trim();
+        if (!value) {
+            throw new CredentialRequiredError(`Connector "${id}" has no stored credential — call ` +
+                `authorize_connector({ connector: "${id}" }) and follow the ` +
+                "operator handoff it returns.");
+        }
+        // Refuse a value a header cannot carry BEFORE anything frames it. A
+        // wrapped newline in a pasted key is the ordinary way this happens, and
+        // the runtime that rejects the header quotes the whole value back in its
+        // TypeError — a message that travels to status, to the activity log, and
+        // to the agent. So the check lives here, and says only what is wrong.
+        if (carriesIllegalHeaderChar(value)) {
+            throw new CredentialRequiredError(`Connector "${id}"'s stored credential contains a character a header ` +
+                "cannot carry (a line break or other control character) — re-enter " +
+                "it on /credentials. The value is not shown or logged.");
+        }
+        return value;
+    };
+    /**
+     * Replace, never edit.
+     *
+     * Any error whose message quotes the credential — the raw value or the
+     * framed header it becomes — is discarded whole and replaced with a fixed
+     * sentence. Nothing is substringed, masked, or truncated out of the original:
+     * a redaction that keeps part of a secret is still a leak, and the original
+     * error is not worth one. This is defense in depth behind the validation
+     * above, which is what keeps an unsendable value from reaching a transport
+     * at all.
+     */
+    const withoutCredential = (err, ...secrets) => {
+        const quoted = secrets.filter((secret) => typeof secret === "string" && secret !== "");
+        if (quoted.length === 0)
+            return err;
+        const seen = new Set();
+        let current = err;
+        while (current instanceof Error && !seen.has(current)) {
+            seen.add(current);
+            if (quoted.some((secret) => current instanceof Error && current.message.includes(secret))) {
+                return new CredentialRequiredError(`Connector "${id}" could not send its stored credential as a ` +
+                    "header — re-enter it on /credentials. The value is not shown or " +
+                    "logged.");
+            }
+            current = current.cause;
+        }
+        return err;
+    };
     const scopeEndedError = () => new Error(`Connector "${id}" scope ended during connection.`);
     const requestOptions = (ctx) => ctx.timeoutMs || ctx.signal
         ? {
@@ -334,6 +510,7 @@ export function remoteMcp(id, opts) {
                 authRequired: false,
                 provider: null,
                 connectedGeneration: null,
+                credentialDigest: null,
                 closed: false,
             };
             states.set(scope, state);
@@ -345,7 +522,13 @@ export function remoteMcp(id, opts) {
         return state.provider;
     };
     const newProvider = (ctx) => new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`);
-    const buildTransport = (ctx, provider) => {
+    const buildTransport = (ctx, provider, 
+    /**
+     * This attempt's assembled header value, for credential auth only — framed
+     * by the caller so the raw secret is not passed around twice. Never
+     * retained past the transport it configures.
+     */
+    credentialFramed = null) => {
         if (opts._transportFactory)
             return opts._transportFactory(ctx);
         const url = new URL(opts.url);
@@ -356,7 +539,11 @@ export function remoteMcp(id, opts) {
                 fetch: guardedFetch,
             });
         }
-        const headers = opts.auth?.type === "headers" ? opts.auth.headers : undefined;
+        const headers = opts.auth?.type === "headers"
+            ? opts.auth.headers
+            : credentialAuth && credentialFramed !== null
+                ? { [credentialHeader]: credentialFramed }
+                : undefined;
         return new StreamableHTTPClientTransport(url, {
             ...(headers ? { requestInit: { headers } } : {}),
             fetch: guardedFetch,
@@ -370,6 +557,7 @@ export function remoteMcp(id, opts) {
         state.authRequired = false;
         state.provider = null;
         state.connectedGeneration = null;
+        state.credentialDigest = null;
         // `closed` is deliberately not cleared — see ConnectionState.
     };
     const ensureConnected = async (ctx, state) => {
@@ -415,6 +603,43 @@ export function remoteMcp(id, opts) {
                 reset(state);
             }
         }
+        // The static-credential counterpart of the epoch read above, and
+        // deliberately beside it: the vault is read before any cached client is
+        // trusted, so an operator's rotation on /credentials takes effect on the
+        // next call rather than the next deploy. Compared by digest — the
+        // plaintext lives in this function's scope and never reaches `state`.
+        let credentialValue = null;
+        let credentialFramed = null;
+        let credentialDigest = null;
+        if (credentialAuth) {
+            credentialValue = await readCredential(ctx);
+            credentialFramed = credentialHeaderValue(credentialScheme, credentialValue);
+            credentialDigest = await digestOf(credentialValue);
+            // Gated on a connect in flight as well as a cached client, exactly like
+            // the epoch read above: a rotation that lands while the first caller is
+            // still connecting must not let the second one ride the key the vault
+            // has already replaced.
+            if ((state.client || state.connecting) &&
+                state.credentialDigest !== null &&
+                state.credentialDigest !== credentialDigest) {
+                if (state.closed)
+                    throw scopeEndedError();
+                const connecting = state.connecting;
+                const client = state.client;
+                const transport = state.transport;
+                reset(state);
+                void connecting?.catch(() => { });
+                try {
+                    if (client)
+                        await client.close();
+                    else
+                        await transport?.close();
+                }
+                catch {
+                    // The rotated-away client is discarded either way.
+                }
+            }
+        }
         if (state.closed)
             throw scopeEndedError();
         if (state.client)
@@ -458,7 +683,7 @@ export function remoteMcp(id, opts) {
                     // below as one structured, non-retryable connector failure.
                     inputRequired: { autoFulfill: false },
                 });
-                const t = buildTransport(ctx, provider);
+                const t = buildTransport(ctx, provider, credentialFramed);
                 if (!ownsAttempt())
                     await abandon(t);
                 state.transport = t;
@@ -506,7 +731,11 @@ export function remoteMcp(id, opts) {
                     if (err instanceof UnauthorizedError) {
                         throw authRequiredError(err);
                     }
-                    throw err;
+                    // Defense in depth for the one error class that can quote the
+                    // credential: a runtime refusing the assembled header. `readCredential`
+                    // already rejects a value that cannot ride one, so reaching this is a
+                    // gap in that check rather than a routine outcome.
+                    throw withoutCredential(err, credentialValue, credentialFramed);
                 }
                 finally {
                     // Force reset may have abandoned this attempt and installed a new one
@@ -517,6 +746,10 @@ export function remoteMcp(id, opts) {
                 }
             })();
             state.connecting = attempt;
+            // Published with the attempt, not with its result: a rotation that lands
+            // while this connect is in flight has to be visible to the next caller,
+            // which would otherwise wait on a client bound to the older key.
+            state.credentialDigest = credentialDigest;
         }
         return state.connecting;
     };
@@ -562,6 +795,54 @@ export function remoteMcp(id, opts) {
             ? { callAdmission: opts.callAdmission }
             : {}),
         ...(opts.usageGuide !== undefined ? { usageGuide: opts.usageGuide } : {}),
+        // Declaring the slot is what makes the rest of the operator surface work:
+        // /credentials renders it, the shape check compares against it, and
+        // authorize_connector reads it to return the operator handoff rather than
+        // an OAuth URL this connector has none of.
+        ...(credentialAuth
+            ? {
+                credential: credentialConfig,
+                /**
+                 * The honest test for a proxy is the catalog: connect with the
+                 * stored value and count what the downstream serves. Nothing else
+                 * here is connecta's to verify — the credential's scope, project,
+                 * and mode are the provider's answer, not ours.
+                 */
+                testCredential: async (value, ctx) => {
+                    try {
+                        // The connect below reads the vault itself — the header is
+                        // assembled deep inside `ensureConnected`, and handing a
+                        // candidate down that path would mean threading a second secret
+                        // through the whole connection state. `/ui/credentials/<id>/test`
+                        // reads the stored value and passes it here, so today the two are
+                        // the same string. Check rather than assume: a route that later
+                        // tested an unsaved candidate would otherwise silently report on
+                        // the old value, which is the one answer worse than refusing.
+                        const stored = (await ctx.credential?.get())?.trim();
+                        if (stored !== value.trim()) {
+                            return {
+                                ok: false,
+                                message: "This connector tests the credential that is currently " +
+                                    "saved. Save the value first, then test it.",
+                            };
+                        }
+                        const tools = await connector.listTools(ctx);
+                        return {
+                            ok: true,
+                            message: `Connected — the downstream served ${tools.length} tool${tools.length === 1 ? "" : "s"}.`,
+                        };
+                    }
+                    catch (err) {
+                        return { ok: false, message: msg(err) };
+                    }
+                    finally {
+                        // A test owns the scope it just opened; leaving the session for
+                        // the downstream to age out is not this button's to spend.
+                        await connector.closeScope?.(ctx);
+                    }
+                },
+            }
+            : {}),
         // `tools/list` is cursor-paginated: the server chooses the page size and
         // signals "there is more" with a `nextCursor`, which the SDK's
         // Client.listTools() returns without following. Collect the whole chain
@@ -744,6 +1025,7 @@ export function remoteMcp(id, opts) {
             state.connecting = null;
             state.authRequired = false;
             state.connectedGeneration = null;
+            state.credentialDigest = null;
             // Ask the downstream to drop its session first — closing only aborts our
             // side, and the DELETE that frees the server's rides on the very
             // AbortSignal the close is about to trip.
@@ -766,12 +1048,25 @@ export function remoteMcp(id, opts) {
                 return { state: "ok" };
             }
             catch (err) {
+                // An empty slot, or one with no vault behind it, is reported the way a
+                // missing grant is: present, unauthenticated, and repairable — never a
+                // boot failure and never a silently absent connector.
+                if (err instanceof CredentialRequiredError) {
+                    return { state: "auth_required", message: err.message };
+                }
                 if (state.authRequired) {
-                    const url = await getProvider(ctx, state).pendingAuthorizationUrl();
+                    // Only an OAuth connector has a pending consent URL to offer. A
+                    // credential connector's downstream 401 is repaired on /credentials,
+                    // so do not reach into OAuth storage to look for one.
+                    const url = isOauth
+                        ? await getProvider(ctx, state).pendingAuthorizationUrl()
+                        : undefined;
                     return {
                         state: "auth_required",
                         ...(url !== undefined ? { authorizationUrl: url } : {}),
-                        message: "Authorization required — open the URL to connect.",
+                        message: credentialAuth
+                            ? "Authorization required — the downstream rejected this connector's stored credential."
+                            : "Authorization required — open the URL to connect.",
                     };
                 }
                 if (err instanceof OperatorDisconnectedError) {

package/dist/invocation.js

@@ -288,6 +288,7 @@ export class InvocationService {
         }
         const maxRetries = Math.min(2, Math.max(0, Math.trunc(context.maxRetries ?? 0)));
         let result;
+        let observedResult;
         while (true) {
             attempts++;
             let permit;
@@ -362,9 +363,8 @@ export class InvocationService {
                     // reports the same downstream-failure wording, and the throw lands
                     // inside the attempt where it stays retry-eligible and feeds health.
                     assertRawMcpSuccess(resolved.connector.kind, raw);
-                    result = context.unwrapResult
-                        ? unwrapMcpResult(resolved.connector.kind, raw)
-                        : raw;
+                    observedResult = unwrapMcpResult(resolved.connector.kind, raw);
+                    result = context.unwrapResult ? observedResult : raw;
                 }
                 finally {
                     connectorMs += Date.now() - connectorStarted;
@@ -440,6 +440,12 @@ export class InvocationService {
             const value = context.processResult
                 ? await context.processResult(result, resolved)
                 : result;
+            try {
+                this.registry.observeOutputShape(resolved.connector.id, resolved.definition, observedResult);
+            }
+            catch {
+                // Shape learning is advisory. It cannot change a completed call.
+            }
             resultProcessingMs += Date.now() - processingStarted;
             const diagnostics = timing();
             const friction = context.activityFriction?.(value);

package/dist/providers/linear.d.ts

@@ -32,7 +32,13 @@ export interface LinearOptions {
      * ([#342](https://github.com/zackbart/connecta/issues/342)).
      */
     access: LinearAccess;
-    /** OAuth by default; static headers support a Linear personal API key. */
+    /**
+     * OAuth by default. A Linear personal API key works either as a literal
+     * header or as an operator-managed credential (`{ type: "credential" }`).
+     * Linear's MCP documentation asks for `Authorization: Bearer <yourtoken>`
+     * for both API keys and OAuth tokens (https://linear.app/docs/mcp), which is
+     * the framing default, so the credential shape needs no `scheme` of its own.
+     */
     auth?: RemoteMcpAuth;
     /** Workspace-specific conventions appended to the maintained provider guide. */
     instructions?: string;

package/dist/providers/linear.js

@@ -1,4 +1,4 @@
-import { remoteMcp, } from "../connectors/remote-mcp.js";
+import { remoteMcp, withCredentialDefaults, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 /**
  * Linear publishes two hosted endpoints. `read-only` is not a client-side
@@ -189,7 +189,17 @@ export function linear(id, options) {
         description: access === "read-only"
             ? `Linear issue tracking and project planning (read-only) — ${purpose}`
             : `Linear issue tracking and project planning — ${purpose}`,
-        auth: options.auth ?? { type: "oauth" },
+        // Linear's MCP endpoint takes an API key the same way it takes an OAuth
+        // token — `Authorization: Bearer <yourtoken>` — so only the slot copy is
+        // provider-specific and the bearer framing default stands. The bare-header
+        // convention belongs to Linear's GraphQL API, not to this endpoint.
+        auth: withCredentialDefaults(options.auth ?? { type: "oauth" }, {
+            credential: {
+                label: "Personal API key",
+                description: "A Linear personal API key. It carries the issuing user's full workspace access and is stored encrypted; the read-only endpoint still limits what it can reach.",
+                placeholder: "lin_api_…",
+            },
+        }),
         requireHttps: true,
         usageGuide: {
             content: usageGuide(purpose, access, options.instructions),

package/dist/providers/mixpanel.d.ts

@@ -18,7 +18,11 @@ export interface MixpanelOptions {
      * rather than a convenient one.
      */
     region?: MixpanelRegion;
-    /** OAuth by default; static headers support Mixpanel service accounts. */
+    /**
+     * OAuth by default; static headers support Mixpanel service accounts, and
+     * `{ type: "credential" }` takes the same service account as an
+     * operator-managed `username:secret` that Connecta frames for the endpoint.
+     */
     auth?: RemoteMcpAuth;
     /** Account-specific conventions appended to the maintained provider guide. */
     instructions?: string;

package/dist/providers/mixpanel.js

@@ -1,4 +1,4 @@
-import { remoteMcp, } from "../connectors/remote-mcp.js";
+import { remoteMcp, withCredentialDefaults, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 export const MIXPANEL_MCP_ENDPOINTS = {
     us: "https://mcp.mixpanel.com/mcp",
@@ -214,7 +214,18 @@ export function mixpanel(id, options) {
         // an agent must not get wrong between two Mixpanel connections.
         title: options.title ?? `Mixpanel (${region})`,
         description: `Mixpanel product analytics (${REGION_COPY[region]} residency) — ${purpose}`,
-        auth: options.auth ?? { type: "oauth" },
+        // Mixpanel's beta service-account scheme is deliberately not ordinary HTTP
+        // Basic: the endpoint wants `Bearer Basic <base64(user:secret)>`. The
+        // operator therefore pastes the pair, not an encoded blob, and Connecta
+        // does the framing — the same shaping the maintainer drift check applies.
+        auth: withCredentialDefaults(options.auth ?? { type: "oauth" }, {
+            credential: {
+                label: "Service account",
+                description: "A Mixpanel service account as `username:secret`. Connecta encodes and frames it the way the hosted endpoint requires; it is stored encrypted and never displayed.",
+                placeholder: "username:secret",
+            },
+            scheme: "Bearer Basic",
+        }),
         requireHttps: true,
         usageGuide: {
             content: usageGuide(purpose, region, options.instructions),

package/dist/providers/revenuecat.d.ts

@@ -21,7 +21,9 @@ export interface RevenueCatOptions {
     purpose: string;
     /**
      * OAuth by default; static headers support a RevenueCat API v2 secret key
-     * as `Authorization: Bearer sk_…`.
+     * as `Authorization: Bearer sk_…`. `{ type: "credential" }` is the same
+     * single-project scope with the key pasted at `/credentials` instead — which
+     * is what two projects on two keys wants, since each is its own connector.
      */
     auth?: RemoteMcpAuth;
     /** Project-specific conventions appended to the maintained provider guide. */

package/dist/providers/revenuecat.js

@@ -1,4 +1,4 @@
-import { remoteMcp, } from "../connectors/remote-mcp.js";
+import { remoteMcp, withCredentialDefaults, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 /** RevenueCat publishes one hosted MCP endpoint, streamable HTTP. */
 export const REVENUECAT_MCP_ENDPOINT = "https://mcp.revenuecat.ai/mcp";
@@ -274,8 +274,17 @@ export function revenuecat(id, options) {
     if (!purpose) {
         throw new Error("revenuecat() requires a non-empty project purpose.");
     }
-    const auth = options.auth ?? { type: "oauth" };
-    const scoped = auth.type === "headers";
+    const auth = withCredentialDefaults(options.auth ?? { type: "oauth" }, {
+        credential: {
+            label: "API v2 secret key",
+            description: "A RevenueCat API v2 secret key. It reaches exactly one project, which is why two projects are two connectors; it is stored encrypted and never displayed.",
+            placeholder: "sk_…",
+        },
+    });
+    // Both static shapes reach one project. Where the key came from — the
+    // deployment file or the operator page — changes nothing an agent must know
+    // about scope, so the title, description, and guide follow the scope alone.
+    const scoped = auth.type !== "oauth";
     const connector = remoteMcp(id, {
         url: REVENUECAT_MCP_ENDPOINT,
         // The scope shape rides the title because browse-time discovery renders

package/dist/providers/stripe.d.ts

@@ -22,10 +22,16 @@ export interface StripeOAuthOptions extends StripeCommonOptions {
     mode?: never;
     connectedAccount?: never;
 }
-/** Static credentials have one fixed mode, including Stripe Connect calls. */
+/**
+ * Static credentials have one fixed mode, including Stripe Connect calls.
+ *
+ * Both static shapes belong here: a key the deployment supplies as a literal
+ * header, and one the operator pastes at `/credentials`. Neither can discover
+ * its own mode — a restricted key answers for exactly one — so both declare it.
+ */
 export interface StripeHeaderOptions extends StripeCommonOptions {
-    auth: Extract<RemoteMcpAuth, {
-        type: "headers";
+    auth: Exclude<RemoteMcpAuth, {
+        type: "oauth";
     }>;
     mode: StripeMode;
     /** Act as one Connect account by sending Stripe's `Stripe-Account` header. */

package/dist/providers/stripe.js

@@ -1,4 +1,4 @@
-import { remoteMcp, } from "../connectors/remote-mcp.js";
+import { remoteMcp, withCredentialDefaults, } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 /** Stripe publishes one hosted MCP endpoint for every account and mode. */
 export const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
@@ -109,17 +109,31 @@ function assertModeMatchesKey(id, mode, auth) {
     }
 }
 function resolveAuth(id, options) {
-    const auth = options.auth ?? { type: "oauth" };
+    const auth = withCredentialDefaults(options.auth ?? { type: "oauth" }, {
+        credential: {
+            label: "Secret or restricted API key",
+            description: "A Stripe secret or restricted API key for this connector's declared mode. Stripe sends it as a bearer token; it is stored encrypted and never displayed.",
+            placeholder: "sk_… or rk_…",
+        },
+    });
     const connectedAccount = options.connectedAccount?.trim();
     if (connectedAccount === undefined || connectedAccount === "")
         return auth;
     if (!connectedAccount.startsWith("acct_")) {
         throw new Error(`stripe("${id}") connectedAccount must be a Stripe account id ("acct_...").`);
     }
-    if (auth.type !== "headers") {
+    if (auth.type === "oauth") {
         throw new Error(`stripe("${id}") cannot reach a connected account over OAuth; Stripe ` +
             `requires a restricted API key for Stripe-Account calls.`);
     }
+    if (auth.type === "credential") {
+        // `Stripe-Account` is a second header beside the credential's own, and the
+        // credential shape assembles exactly one. A Connect connector therefore
+        // still takes its restricted key as a literal header.
+        throw new Error(`stripe("${id}") cannot reach a connected account with an ` +
+            `operator-managed credential; Stripe-Account is a second static ` +
+            `header, so declare auth: { type: "headers" } for this connector.`);
+    }
     return {
         type: "headers",
         headers: { ...auth.headers, "Stripe-Account": connectedAccount },
@@ -199,9 +213,14 @@ export function stripe(id, options) {
     if (auth.type === "oauth" && mode !== undefined) {
         throw new Error(`stripe("${id}") cannot declare a connector-wide mode for OAuth; Stripe returns mode with each account.`);
     }
-    if (auth.type === "headers" && mode !== "production" && mode !== "sandbox") {
-        throw new Error(`stripe("${id}") with headers auth requires mode "production" or "sandbox".`);
+    if (auth.type !== "oauth" && mode !== "production" && mode !== "sandbox") {
+        throw new Error(`stripe("${id}") with headers or credential auth requires mode ` +
+            `"production" or "sandbox".`);
     }
+    // Only a literal header can be inspected. An operator-managed credential is
+    // not readable at construction — there is nothing in the deployment file to
+    // read — so the declared mode stands alone, and a key pointed at the other
+    // one is Stripe's own refusal to report.
     if (auth.type === "headers") {
         assertModeMatchesKey(id, mode, auth);
     }