@zackbart/connecta 0.18.1 → 0.18.2

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 All notable changes to this package are documented here.
 
+## 0.18.2 — 2026-08-18
+
+This patch closes the gap the RevenueCat rollout exposed on the same day 0.18.1
+shipped: a hosted-MCP connection could authenticate with OAuth from the
+Connections page or with a header literal baked into the deployment file, but
+never with a key an operator pastes on `/credentials` the way every `api()`
+connector already can. Now it can. Nothing breaks, no constructor changes, and a
+deployment that keeps its static keys in runtime secrets can ignore this release.
+Two things are worth reading before adopting the new shape: the operator vault
+(`credentials.encryptionKey`) must be configured, and a key pasted with a
+wrapped newline is refused before it is framed rather than echoed back by the
+runtime that rejects it.
+
+### Added
+
+- **`auth: { type: "credential" }` for `remoteMcp()` and every maintained
+  hosted connection.** The connector declares an operator credential slot on
+  `/credentials` (label and guidance from the provider, overridable), reads the
+  stored value on every request before trusting a cached client, and frames it
+  as `Authorization: Bearer <value>` by default — `header` and `scheme` are
+  configurable, `scheme: null` sends the value bare, and a scheme ending in
+  `Basic` base64-encodes it, which is how Mixpanel's documented
+  `Bearer Basic <base64(user:secret)>` is spelled. A missing or empty value is
+  `auth_required`, and `authorize_connector` returns the operator handoff to
+  `/credentials`; a deployment without a vault warns at construction and answers
+  `recovery: "unavailable"` at use. Rotation on `/credentials` takes effect on
+  the next call: a SHA-256 digest of the connected value is compared per
+  request (including against an in-flight connect) and a differing digest
+  closes the old client. The `/credentials` Test action connects with the
+  candidate and counts the catalog, and only when an operator presses it — the
+  #179 refusal of proactive probing stands, now written into P10. Provider
+  defaults: Stripe (requires `mode`, refuses `connectedAccount`), Linear
+  (Bearer, per Linear's MCP docs), Mixpanel (`Bearer Basic`, service account),
+  RevenueCat (single-project branch, "API v2 secret key") (#439).
+
+### Changed
+
+- **A stored credential never reaches an agent or operator surface, even
+  malformed.** The value is refused before framing if it carries a control
+  character (the wrapped-newline paste), with a message that names the problem
+  and not the value; behind that, any error whose message or `cause` chain
+  quotes the raw or framed value is replaced whole rather than redacted. Both
+  layers are tested independently (#439).
+
+- **Provider conventions P9 and P10 say what is now true.** P9 names both
+  headless shapes and requires the framing to match the provider's published
+  MCP contract; P10 is retitled to allow an operator-requested credential test
+  while forbidding any unasked probe (#439).
+
+- **Linear's headers example uses `Bearer`.** Linear's MCP server documents
+  `Authorization: Bearer <token>` for API keys; the bare form is its GraphQL
+  convention. Existing `headers` connectors are untouched (#439).
+
 ## 0.18.1 — 2026-08-18
 
 This patch is the response to one long investigation run against a live

package/dist/connectors/remote-mcp.d.ts

@@ -1,12 +1,58 @@
 import type { FetchLike, Transport } from "@modelcontextprotocol/client";
 import { ConnectorCallError } from "../errors.js";
-import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorUsageGuide, Logger } from "../types.js";
+import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorCredentialConfig, ConnectorUsageGuide, Logger } from "../types.js";
+/**
+ * A static downstream credential the operator supplies at `/credentials`
+ * rather than the deployment baking into its source.
+ *
+ * The connector, its endpoint, and the credential *slot* stay declared in
+ * code; only the secret arrives through the operator route, exactly as for
+ * `api()`. One reserved `value` field, deliberately: a header is assembled
+ * from a name, a framing scheme, and one secret, and anything that needs two
+ * secrets composed into one header is a provider integration, not a proxy
+ * config ([#439](https://github.com/zackbart/connecta/issues/439)).
+ */
+interface RemoteMcpCredentialAuth {
+    type: "credential";
+    /**
+     * Operator-facing slot description rendered on `/credentials`. Defaults to
+     * `{ label: "API key" }`; a maintained provider passes the name the provider
+     * itself uses. Named `fields` are refused — this shape reads the reserved
+     * `value` field only.
+     */
+    credential?: ConnectorCredentialConfig;
+    /** Header the credential rides. Defaults to `Authorization`. */
+    header?: string;
+    /**
+     * Framing token placed before the value. Defaults to `"Bearer"`. `null` (or
+     * an empty string) sends the stored value verbatim, for an endpoint that
+     * reads a bare key. A scheme whose last token is `Basic` declares
+     * HTTP Basic credentials: the stored `user:secret` is base64-encoded first,
+     * so `"Basic"` produces `Basic <base64>` and Mixpanel's documented
+     * `"Bearer Basic"` produces `Bearer Basic <base64>`.
+     */
+    scheme?: string | null;
+}
 export type RemoteMcpAuth = {
     type: "headers";
     headers: Record<string, string>;
-} | {
+} | RemoteMcpCredentialAuth | {
     type: "oauth";
 };
+/**
+ * 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 declare function withCredentialDefaults(auth: RemoteMcpAuth, defaults: {
+    credential: ConnectorCredentialConfig;
+    /** Provider framing; omit to leave the `Bearer` default in place. */
+    scheme?: string | null;
+}): RemoteMcpAuth;
 export type RemoteMcpRedirectPolicy = "none" | "same-origin";
 export interface RemoteMcpOptions {
     url: string;
@@ -90,3 +136,4 @@ export declare function redirectSafeFetch(connectorId: string, policy?: RemoteMc
  * server or hide other connectors).
  */
 export declare function remoteMcp(id: string, opts: RemoteMcpOptions): Connector;
+export {};

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/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);
     }

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.18.1";
+export declare const CONNECTA_VERSION = "0.18.2";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.18.1";
+export const CONNECTA_VERSION = "0.18.2";

package/documentation/connectors.md

@@ -294,3 +294,28 @@ server issuer discovered and validated by the SDK; see
 [storage and credentials](./storage-and-credentials.md#downstream-oauth).
 The callback route validates `state` before passing the complete callback query
 to the SDK so RFC 9207 `iss` validation is not lost.
+
+A remote MCP connector that authenticates with a static key has two ways to
+receive one. `{ type: "headers", headers }` bakes the literal value into the
+deployment file, which suits a secret the runtime already holds.
+`{ type: "credential" }` declares the slot instead and lets an operator paste
+the key at `/credentials`, where it is encrypted at rest and rotatable without
+a redeploy:
+
+```ts
+remoteMcp("revenuecat_bepresent", {
+  url: "https://mcp.revenuecat.ai/mcp",
+  auth: {
+    type: "credential",
+    credential: { label: "API v2 secret key" },
+  },
+});
+```
+
+Header name and framing are configurable — `header` defaults to
+`Authorization`, `scheme` to `Bearer`, `scheme: null` sends the value bare, and
+a `Basic` framing base64-encodes a `user:secret` pair. Every maintained hosted
+connection takes the shape through its existing `auth` option and fills in its
+own label and framing. The full behavior, including rotation and the empty-slot
+state, is in
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).

package/documentation/linear.md

@@ -65,9 +65,12 @@ connection; it now answers 404.
 ## Authentication
 
 OAuth 2.1 with dynamic client registration is the default and keeps each
-connector instance's flow and tokens in its connector-scoped storage. Linear
-also accepts a bearer token or a personal API key passed directly in the
-`Authorization` header, which suits a headless deployment:
+connector instance's flow and tokens in its connector-scoped storage. Linear's
+MCP server also "supports passing OAuth token and API keys directly in the
+`Authorization: Bearer <yourtoken>` header instead of using the interactive
+authentication flow" ([Linear MCP docs](https://linear.app/docs/mcp)), which
+suits a headless deployment. Note the framing: the bare-`Authorization`
+convention is Linear's *GraphQL* API, and this endpoint is not that.
 
 ```ts
 linear("automation_tracker", {
@@ -75,7 +78,7 @@ linear("automation_tracker", {
   access: "read-only",
   auth: {
     type: "headers",
-    headers: { Authorization: env.LINEAR_API_KEY },
+    headers: { Authorization: `Bearer ${env.LINEAR_API_KEY}` },
   },
 });
 ```
@@ -85,6 +88,24 @@ configuration. A personal API key carries the acting user's full workspace
 permissions, so pair it with `access: "read-only"` unless the deployment
 genuinely writes.
 
+The same key can arrive from `/credentials` instead, which is what a deployment
+with no secret store — or an operator who rotates keys without a redeploy —
+wants:
+
+```ts
+linear("automation_tracker", {
+  purpose: "Headless release reporting",
+  access: "read-only",
+  auth: { type: "credential" },
+});
+```
+
+The slot renders as "Personal API key" and Connecta sends the stored value as
+`Authorization: Bearer <key>`, the framing Linear's MCP page documents; pass
+`credential` or `scheme` to override either. Until the operator saves a value
+the connector is present and reports `auth_required`. See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 ## Safety classification
 
 The wrapper classifies Linear's documented `list_*`, `get_*`, and

package/documentation/meta-tools.md

@@ -310,6 +310,11 @@ handoff:
   declared credential label and field names/guidance; or
 - `unavailable`: an honest deployment/configuration message.
 
+The class follows what the connector declares, not how it was authored: a
+`remoteMcp()` connection using `auth: { type: "credential" }` declares a slot
+and no OAuth flow, so it lands in `operator_config` beside every `api()`
+credential.
+
 The tool accepts no secret. `force` applies only to OAuth and may discard its
 stored grant before restarting consent. Static credential values are written
 only through the same-origin, Clerk-operator credential route. After OAuth

package/documentation/mixpanel.md

@@ -50,6 +50,25 @@ password, not ordinary configuration. Mixpanel currently labels service-account
 MCP authentication beta. Prefer OAuth unless the deployment is intentionally
 headless.
 
+The same service account can arrive from `/credentials` instead, and there the
+operator pastes the readable pair rather than an encoded blob:
+
+```ts
+mixpanel("automation_analytics", {
+  purpose: "Headless release-health reporting",
+  auth: { type: "credential" },
+});
+```
+
+The slot renders as "Service account" and takes `username:secret`. Connecta
+base64-encodes it and sends Mixpanel's documented `Bearer Basic` framing, so the
+operator never has to encode anything by hand. **The two paths take different
+strings:** the `headers` example above wants the already-encoded blob
+(`echo -n "username:secret" | base64`), and this one wants the plaintext pair.
+Migrating from one to the other means decoding, not copying. Until a value is
+saved the connector is present and reports `auth_required`. See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 ## Conditional input contracts
 
 Mixpanel's hosted descriptions enforce three cross-field conditions that its

package/documentation/operations.md

@@ -247,6 +247,7 @@ in.
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
 | `registry.test.ts` | construction and id validation, startup warnings, address resolution, catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
 | `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, and downstream session termination |
+| `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from `/credentials`: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, `lastError`, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
 | `remote-mcp-pagination.test.ts` | the `tools/list` cursor chain in both directions — exact cursor handoff, first-wins dedup, a failed later page rejecting rather than returning its prefix, the runaway backstops, the tool-metadata re-prime across pages, and paginated catalogs reaching the discovery path |
 | `request-admission.test.ts` | `/mcp` bounded before auth, the stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, and the separate fallback code pool |
 | `revenuecat-provider.test.ts` / `revenuecat-registry.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot`; then two project-scoped keys as two connectors in a real deployment |

package/documentation/provider-conventions.md

@@ -412,33 +412,49 @@ retries.
 
 OAuth per connector instance, stored in connector-scoped storage, is the
 default. The provider's own headless credential — a personal API key, a
-restricted key, a service account — is supported through explicit `headers`
-auth, documented as a secret rather than configuration, and paired with the
-narrowest mode the deployment can use. `requireHttps` is set. Recovery from an
-expired authorization is the ordinary `auth_required` → `authorize_connector`
-route.
+restricted key, a service account — is supported two ways: explicit `headers`
+auth, documented as a secret rather than configuration, and `{ type:
+"credential" }`, which declares an operator slot and takes the same secret from
+`/credentials` instead. Either way it is paired with the narrowest mode the
+deployment can use, and the framing matches the provider's *published* contract
+for the MCP endpoint — not a convention borrowed from that provider's other
+APIs, and not this repository's earlier example, which is the same claim wearing
+a circle. `requireHttps` is set. Recovery from an expired authorization is the
+ordinary `auth_required` → `authorize_connector` route, which returns the
+consent URL for OAuth and the `/credentials` handoff for a declared slot.
 
 *Why:* one route back from an expired credential is what keeps a failed call
 from becoming an abandoned task. *Cost:* wrong-tool selection.
 
-### P10 — There is no credential test; the equivalent check happens at construction
+### P10 — Nothing probes a credential unasked; a declared slot may be tested on request
 
-A proxy declares no operator credential slot and implements neither
-`testCredential` nor `testCredentials`. `remoteMcp()` has no `credential`
-option, and neither shape of proxy credential is vault-managed: OAuth lives in
+A proxy declares an operator credential slot exactly when its auth is `{ type:
+"credential" }`, and then it inherits H12 whole
+([#439](https://github.com/zackbart/connecta/issues/439)). The other two shapes
+declare no slot and hold nothing for the credentials page: OAuth lives in
 connector-scoped storage and is exercised by the authorization flow itself,
-while a headless key arrives as deployment configuration in `headers`, so there
-is nothing for the operator credentials page to hold or test. H12's guarantee is
-still owed, and a proxy pays it in two other places: construction throws when a
-recognizable credential contradicts the declared mode (P4), and a dead or
-revoked credential fails loudly at use as `auth_required` with the
-`authorize_connector` route attached (P9). Connecta never probes a downstream to
-see whether a credential is still alive — that shape is `removed` in the ethos
-([#179](https://github.com/zackbart/connecta/issues/179)). A provider that later
-does take a vault-managed secret inherits H12 whole.
+while a `headers` key arrives as deployment configuration. H12 is owed in every
+shape, and a proxy pays it in two places that do not depend on a slot:
+construction throws when a recognizable credential contradicts the declared mode
+(P4) — a check a vault-managed key cannot get, because there is nothing in the
+deployment file to read — and a dead, revoked, or absent credential fails loudly
+at use as `auth_required` with the `authorize_connector` route attached (P9).
+
+`testCredential` exists only behind the operator-pressed Test action on
+`/credentials`, and only for a declared slot. It connects with the stored value
+and reports how many tools the downstream served, which is the whole honest
+check for a proxy: which account, project, or mode a key reaches is the
+provider's answer, not Connecta's. That is not the shape
+[#179](https://github.com/zackbart/connecta/issues/179) removed. What was
+removed is the *unasked* probe — a liveness call every deployment pays on a
+schedule or at startup to answer a question only a misconfigured one has. A
+human clicking Test has asked, `api()` has had that button since the vault
+existed, and nothing here probes on its own: no timer, no warmup, no check on
+the read path.
 
 *Why:* an unasked-for liveness probe spends a call on every deployment to answer
-a question only a misconfigured one has. *Cost:* result size.
+a question only a misconfigured one has; a requested one spends a call the
+person requesting it chose. *Cost:* result size.
 
 ### P11 — Connecta classifies the transport; the downstream owns the tool error
 
@@ -666,8 +682,8 @@ than by reading:
 | P4 | endpoint or mode option exists, with the documented default (or no default, where none is safe) |
 | P5 | reads and writes are named lists; an unlisted tool resolves to not-read-only; a reviewed destructive name beats a contradictory `readOnlyHint: true` |
 | P6, P8 | the guide contains the catalog-varies note and the id-resolution rule |
-| P9 | `auth` defaults to OAuth and `requireHttps` is set |
-| P10 | no `credential`, `testCredential`, or `testCredentials` on the wrapper; the mode/key contradiction throws at construction instead |
+| P9 | `auth` defaults to OAuth and `requireHttps` is set; a credential-auth shape frames the key the way the provider's MCP documentation does |
+| P10 | a `credential` slot exactly when auth is `{ type: "credential" }`; `testCredential` runs only from the operator's Test action, never on a timer or a read path; the mode/key contradiction still throws at construction |
 | P11 | an authorization failure surfaces as `auth_required`; a downstream tool error is returned unchanged, with no code chosen from its prose |
 | P12 | a declared budget matches a citable documented limit, or the absence is justified in the guide |
 | P13 | classification lists are maintained in one place per provider and built into the manifest the wrapper classifies from, so the drift check compares against the same fact the caller is served |

package/documentation/revenuecat.md

@@ -80,6 +80,26 @@ connectors: [
 ]
 ```
 
+Neither key has to be a runtime secret. Declare the slot instead and each
+connector's key is pasted, tested, and rotated on `/credentials`:
+
+```ts
+connectors: [
+  revenuecat("bepresent_ios", {
+    purpose: "Subscription state for the BePresent iOS project",
+    auth: { type: "credential", credential: { label: "API v2 secret key" } },
+  }),
+  revenuecat("biblescroll", {
+    purpose: "Subscription state for the BibleScroll project",
+    auth: { type: "credential", credential: { label: "API v2 secret key" } },
+  }),
+]
+```
+
+Two ids, two slots, two single-project catalogs — the `credential` option is
+optional, and omitting it gives the same "API v2 secret key" label. See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 That is config-as-code doing what an account model would otherwise do: one
 credential per connector, each with its own catalog, storage namespace, health,
 and admission counters. The two share a title, because Connecta cannot know
@@ -116,7 +136,9 @@ Keys are prefixed `sk_`, are issued read-only or write-enabled, and can be
 revoked at any time by a project Admin. RevenueCat's setup guidance is to "use
 a write-enabled key if you plan to create/modify resources"; "a read-only key
 works if you only need to view data". Keep the key in the runtime's secret
-store, never in the deployment file.
+store, never in the deployment file — or declare
+`auth: { type: "credential" }` and let the operator hold it in the vault
+instead, which is the shape the two-project example above uses.
 
 **Connecta does not filter writes for a read-only key.** It has no way to tell
 which kind a key is without spending a call, so every write in the catalog is

package/documentation/storage-and-credentials.md

@@ -34,6 +34,61 @@ Credential mutation is intentionally narrower than MCP access:
 The vault is read for each call. Once an operator saves a replacement,
 the agent can retry immediately without restarting or redeploying Connecta.
 
+## A remote MCP connector's static credential
+
+`remoteMcp()` accepts a third auth shape beside OAuth and literal headers:
+
+```ts
+remoteMcp("revenuecat_bepresent", {
+  url: "https://mcp.revenuecat.ai/mcp",
+  auth: { type: "credential", credential: { label: "API v2 secret key" } },
+});
+```
+
+The connector, its endpoint, and the credential *slot* stay declared in code;
+only the secret arrives through `/credentials`. That is the same boundary
+`api()` has always had, and the reason a project-wide key no longer has to be a
+Worker secret or an environment variable
+([#439](https://github.com/zackbart/connecta/issues/439)).
+
+`header` defaults to `Authorization` and `scheme` to `Bearer`. `scheme: null`
+sends the stored value verbatim, which is what Linear's personal API keys
+expect. A scheme whose last token is `Basic` declares HTTP Basic credentials, so
+the stored `user:secret` is base64-encoded first — `"Basic"` produces
+`Basic <base64>`, and Mixpanel's documented `"Bearer Basic"` produces
+`Bearer Basic <base64>`. There is one reserved `value` field and no multi-field
+header composition: named `credential.fields` are refused at construction.
+
+A stored value is checked before anything frames it: a line break or other
+control character — what a key pasted across two lines leaves behind — is
+refused as `auth_required` with a message naming the problem and never the
+value. That check exists because the runtime that rejects such a header quotes
+the whole offending value back in its `TypeError`, and that message would
+otherwise reach the agent, the operator page, and the activity log. Behind it,
+any error whose message quotes the credential or the header it became is
+discarded whole and replaced; nothing is masked or truncated, because a
+redaction that keeps part of a secret is still a leak.
+
+An empty slot is not a boot failure and not a silently absent connector. The
+connector is present, its status reads `auth_required`, calls fail with the same
+typed error a missing OAuth grant produces, and `authorize_connector` returns
+the `/credentials` handoff. With no vault configured at all, the failure names
+`credentials.encryptionKey`, and Connecta already warned at startup.
+
+The vault is read before any cached downstream client is trusted, so a rotation
+lands on the next call rather than the next deploy. Connecta compares a SHA-256
+digest of the value the cached client connected with; a different digest closes
+that client and reconnects. The plaintext lives in the connect attempt's local
+scope, never on connector state, never in a log, and never in a status or error
+message. A cleartext `http://` destination warns at construction here exactly as
+it does for literal headers — who owns the secret changed, not what the wire
+carries.
+
+`/credentials`' Test action connects with the stored value and reports how many
+tools the downstream served. That is the whole honest check for a proxy: which
+account, project, or mode the key reaches is the provider's answer, not
+Connecta's.
+
 ## Downstream OAuth
 
 `remoteMcp()` stores dynamic client registration, tokens, PKCE material, state,

package/documentation/stripe.md

@@ -95,12 +95,32 @@ Use a restricted key, not a secret key, and scope it to the operations the
 agent actually needs; Stripe's own guidance is to "limit your agent's access to
 exactly the functionality it requires". Keep it in the runtime's secret store.
 
+The same key can come from `/credentials` instead:
+
+```ts
+stripe("stripe_sandbox", {
+  mode: "sandbox",
+  purpose: "Automated billing rehearsal",
+  auth: { type: "credential" },
+});
+```
+
+`mode` is required either way — a static key answers for exactly one
+environment and cannot report which. The literal-header form is checked against
+the key's `_live_`/`_test_` prefix at construction; an operator-managed key is
+not in the deployment file to read, so the declared mode stands alone and a key
+pointed at the other environment fails at Stripe. Declare the mode carefully:
+that check is the one guard Connecta can offer, and this shape does not get it.
+See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 Organization accounts in one OAuth session are not Stripe Connect connected
 accounts. Connect platforms can act as a connected account with
 `connectedAccount`, which adds Stripe's documented `Stripe-Account` header at
 connector construction. Stripe does not support OAuth for connected-account
-calls, so this requires a restricted key through `headers` auth and throws
-otherwise:
+calls, and `Stripe-Account` is a second header beside the credential's own,
+which the operator-managed shape does not assemble — so this requires a
+restricted key through `headers` auth and throws otherwise:
 
 ```ts
 stripe("merchant_42", {

package/documentation/upgrading.md

@@ -57,7 +57,7 @@ exist so far:
 | --- | --- | --- |
 | **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
 | **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
-| **B** | 0.16.0 – 0.18.1 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+| **B** | 0.16.0 – 0.18.2 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -106,7 +106,7 @@ know what to preserve, once to know what to re-verify at the end.
 ### Bump the pin and install
 
 ```sh
-npm pkg set dependencies.@zackbart/connecta=0.18.1
+npm pkg set dependencies.@zackbart/connecta=0.18.2
 npm install
 ```
 
@@ -130,7 +130,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.18.1 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.18.2 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +186,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.18.1 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.18.2 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -207,6 +207,23 @@ first, so cross them bottom-up: start at the oldest one still above this
 deployment's pin and work back up the page, because each boundary assumes the
 older ones are already done.
 
+### 0.18.1 → 0.18.2
+
+Nothing throws for an existing deployment, and the version bump alone crosses
+it. The release adds a third `auth` shape to `remoteMcp()` and every maintained
+hosted connection — `{ type: "credential" }` — under which the connector
+declares an operator slot on `/credentials` and reads the pasted value on each
+request. A deployment carrying a static key as a runtime secret
+(`auth: { type: "headers", headers: { Authorization: env.KEY } }`) keeps
+working unchanged; moving it behind `/credentials` is an edit to the connector's
+`auth` and one paste on the operator page, and needs `credentials.encryptionKey`
+configured — a deployment without a vault gets a startup warning and
+`recovery: "unavailable"` at use for that connector, not a boot failure. Two
+Linear notes: the `headers` example in `documentation/linear.md` now shows
+`Bearer ${key}` (Linear's MCP server documents that framing), and the credential
+shape sends `Bearer` by default; a `headers` connector already sending a bare
+key is untouched.
+
 ### 0.18.0 → 0.18.1
 
 Nothing throws, no option moves, and every deployment crosses this on the

package/examples/worker/src/index.ts

@@ -123,6 +123,11 @@ function build(env: Env) {
         auth: {
           type: "headers",
           headers: { Authorization: `Bearer ${env.DOWNSTREAM_TOKEN}` },
+          // The vault-backed alternative for a downstream that authenticates
+          // with a static key: the operator pastes it at /credentials and
+          // rotates it there, so no Worker secret holds it.
+          //   type: "credential",
+          //   credential: { label: "Notion internal integration token" },
         },
       }),
       api("echo", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.18.1",
+    "@zackbart/connecta": "0.18.2",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {