@every-app/sdk 0.3.0-rc.11 → 0.3.0-rc.13

package/dist/internal/mcpOAuth.js

@@ -0,0 +1,735 @@
+import { publicHostProblem } from "./providerRegistry.js";
+import { parseProviderSpec, describeSpecProblems } from "./providerSpec.js";
+import { remoteMcpClientIdSetting, remoteMcpClientSecretSetting, remoteMcpHeaderProblem, remoteMcpProviderId, remoteMcpTokenSetting, } from "./remoteMcp.js";
+/** The largest answer a discovery or registration fetch reads: 64 KiB. */
+export const MCP_OAUTH_MAX_BODY = 64 * 1024;
+/** How long one discovery or registration fetch may take. */
+export const MCP_OAUTH_TIMEOUT_MS = 10_000;
+const TOKEN_CHAR = /[!#$%&'*+\-.^_`|~0-9A-Za-z]/;
+/**
+ * The Bearer challenge of a `WWW-Authenticate` header, or null when the
+ * header carries none. Reads several challenges in one header
+ * (`Basic realm="x", Bearer resource_metadata="…"`), quoted and bare
+ * values, and parameter names in any case.
+ */
+export function parseWwwAuthenticate(header) {
+    if (typeof header !== "string" || !header.trim())
+        return null;
+    const challenges = [];
+    let current = null;
+    let i = 0;
+    const n = header.length;
+    const skip = (chars) => {
+        while (i < n && chars.test(header[i]))
+            i++;
+    };
+    const token = () => {
+        const start = i;
+        while (i < n && TOKEN_CHAR.test(header[i]))
+            i++;
+        return header.slice(start, i);
+    };
+    while (i < n) {
+        skip(/[\s,]/);
+        if (i >= n)
+            break;
+        const name = token();
+        if (!name) {
+            // Something unreadable: skip to the next comma.
+            while (i < n && header[i] !== ",")
+                i++;
+            continue;
+        }
+        const afterName = i;
+        skip(/[ \t]/);
+        if (header[i] === "=" && header[i + 1] !== "=") {
+            i++;
+            skip(/[ \t]/);
+            let value = "";
+            if (header[i] === '"') {
+                i++;
+                while (i < n && header[i] !== '"') {
+                    if (header[i] === "\\" && i + 1 < n)
+                        i++;
+                    value += header[i];
+                    i++;
+                }
+                i++;
+            }
+            else {
+                const start = i;
+                while (i < n && header[i] !== "," && !/\s/.test(header[i]))
+                    i++;
+                value = header.slice(start, i);
+            }
+            if (current)
+                current.params[name.toLowerCase()] = value;
+            continue;
+        }
+        // A scheme: a new challenge. (A token68 after another scheme reads
+        // as a scheme of its own; only the Bearer challenge is looked at.)
+        i = afterName;
+        current = { scheme: name.toLowerCase(), params: {} };
+        challenges.push(current);
+    }
+    const bearer = challenges.find((challenge) => challenge.scheme === "bearer");
+    if (!bearer)
+        return null;
+    const out = {};
+    if (bearer.params["resource_metadata"]) {
+        out.resourceMetadata = bearer.params["resource_metadata"];
+    }
+    if (bearer.params["scope"])
+        out.scope = bearer.params["scope"];
+    if (bearer.params["error"])
+        out.error = bearer.params["error"];
+    return out;
+}
+/** Why `url` can't be fetched by discovery, or null when it can. */
+export function mcpOAuthUrlProblem(url, { query = true } = {}) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return `${url} isn't a URL`;
+    }
+    if (parsed.protocol !== "https:")
+        return `${url} isn't https`;
+    if (parsed.username || parsed.password) {
+        return `${url} carries credentials`;
+    }
+    if (parsed.hash || url.includes("#"))
+        return `${url} has a fragment`;
+    if (parsed.port) {
+        return `${url} is on port ${parsed.port}; the Gateway's OAuth requests go to port 443 only`;
+    }
+    if (!query && parsed.search)
+        return `${url} carries a query string`;
+    const host = parsed.hostname.toLowerCase().replace(/\.$/, "");
+    if (host.startsWith("[") || host.includes(":")) {
+        return `${host} is an IP address, not a host name`;
+    }
+    const problem = publicHostProblem(host);
+    if (problem)
+        return problem;
+    if (!host.includes("."))
+        return `${host} is not a public host`;
+    return null;
+}
+async function readBounded(response) {
+    const declared = Number(response.headers.get("content-length") ?? "");
+    if (Number.isFinite(declared) && declared > MCP_OAUTH_MAX_BODY)
+        return null;
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > MCP_OAUTH_MAX_BODY) {
+            await reader.cancel().catch(() => { });
+            return null;
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * One bounded fetch: a JSON object, `missing` for a 4xx or 5xx (the next
+ * candidate is tried), `failed` for anything that ends discovery (a
+ * redirect, an oversize or unreadable answer, a network error, a refused
+ * URL).
+ */
+async function fetchJson(fetcher, url, init = {}) {
+    const problem = mcpOAuthUrlProblem(url);
+    if (problem)
+        return { kind: "failed", problem };
+    let response;
+    try {
+        response = await fetcher(url, {
+            ...init,
+            redirect: "manual",
+            signal: AbortSignal.timeout(MCP_OAUTH_TIMEOUT_MS),
+            headers: { accept: "application/json", ...(init.headers ?? {}) },
+        });
+    }
+    catch (error) {
+        const timeout = error instanceof Error &&
+            (error.name === "TimeoutError" || error.name === "AbortError");
+        return {
+            kind: "failed",
+            problem: timeout
+                ? `${url} didn't answer within ${MCP_OAUTH_TIMEOUT_MS / 1000} s`
+                : `${url} couldn't be fetched (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+    if (response.type === "opaqueredirect" ||
+        (response.status >= 300 && response.status < 400)) {
+        return {
+            kind: "failed",
+            problem: `${url} answered with a redirect (${response.status || "3xx"}); discovery follows none`,
+        };
+    }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        return { kind: "missing", status: response.status };
+    }
+    const text = await readBounded(response);
+    if (text === null) {
+        return {
+            kind: "failed",
+            problem: `${url} answered with more than ${MCP_OAUTH_MAX_BODY / 1024} KiB`,
+        };
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return { kind: "failed", problem: `${url} didn't answer with JSON` };
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        return {
+            kind: "failed",
+            problem: `${url} didn't answer with a JSON object`,
+        };
+    }
+    return { kind: "json", body: body };
+}
+function stringList(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+/** `/.well-known/<name>` inserted before `url`'s path (none for a bare origin). */
+function pathInserted(url, name) {
+    const path = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
+    return `${url.origin}/.well-known/${name}${path}`;
+}
+/** Whether the metadata's `resource` is `mcpUrl` or a path prefix of it on the same origin. */
+function resourceCovers(resource, mcpUrl) {
+    let parsed;
+    try {
+        parsed = new URL(resource);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.origin !== mcpUrl.origin || parsed.hash)
+        return false;
+    if (parsed.search && parsed.search !== mcpUrl.search)
+        return false;
+    const base = parsed.pathname;
+    const path = mcpUrl.pathname;
+    if (base === path || base === "/" || base === "")
+        return true;
+    const trimmed = base.replace(/\/+$/, "");
+    return (path === trimmed || path.startsWith(`${trimmed}/`) || path === `${trimmed}/`);
+}
+function sameIssuer(a, b) {
+    return a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
+}
+/** The issuer's metadata URLs, in the MCP spec's order. */
+function metadataUrls(issuer) {
+    const path = issuer.pathname === "/" ? "" : issuer.pathname.replace(/\/+$/, "");
+    if (!path) {
+        return [
+            `${issuer.origin}/.well-known/oauth-authorization-server`,
+            `${issuer.origin}/.well-known/openid-configuration`,
+        ];
+    }
+    return [
+        `${issuer.origin}/.well-known/oauth-authorization-server${path}`,
+        `${issuer.origin}/.well-known/openid-configuration${path}`,
+        `${issuer.origin}${path}/.well-known/openid-configuration`,
+    ];
+}
+function scopeList(value) {
+    const raw = typeof value === "string" ? value.split(/\s+/) : [...(value ?? [])];
+    const out = [];
+    for (const scope of raw) {
+        // What a provider spec's scope list takes: printable, no space or comma, bounded.
+        if (!scope ||
+            scope.length > 200 ||
+            /[\s,]/.test(scope) ||
+            /[\p{Cc}\p{Cf}]/u.test(scope) ||
+            out.includes(scope)) {
+            continue;
+        }
+        out.push(scope);
+        if (out.length === 40)
+            break;
+    }
+    return out;
+}
+async function authorizationServer(fetcher, issuer) {
+    const problem = mcpOAuthUrlProblem(issuer, { query: false });
+    if (problem) {
+        return { ok: false, problem: `the authorization server: ${problem}` };
+    }
+    const tried = [];
+    for (const url of metadataUrls(new URL(issuer))) {
+        tried.push(url);
+        const fetched = await fetchJson(fetcher, url);
+        if (fetched.kind === "failed")
+            return { ok: false, problem: fetched.problem };
+        if (fetched.kind === "missing")
+            continue;
+        const said = fetched.body["issuer"];
+        if (typeof said !== "string" || !sameIssuer(said, issuer)) {
+            return {
+                ok: false,
+                problem: `${url} names the issuer ${typeof said === "string" ? said : "(none)"}, not ${issuer}; the Gateway refuses metadata for another server`,
+            };
+        }
+        return { ok: true, metadata: fetched.body, issuer: said };
+    }
+    return {
+        ok: false,
+        problem: `no authorization server metadata for ${issuer} (tried ${tried.join(", ")})`,
+    };
+}
+function endpointOf(metadata, field, { required, query }) {
+    const value = metadata[field];
+    if (value === undefined || value === null || value === "") {
+        return required
+            ? {
+                ok: false,
+                problem: `the authorization server's metadata has no ${field}`,
+            }
+            : { ok: true };
+    }
+    if (typeof value !== "string" || value.length > 500) {
+        return {
+            ok: false,
+            problem: `the authorization server's ${field} isn't a URL`,
+        };
+    }
+    const problem = mcpOAuthUrlProblem(value, { query });
+    return problem
+        ? { ok: false, problem: `the authorization server's ${field}: ${problem}` }
+        : { ok: true, url: value };
+}
+/**
+ * Find how `url`'s MCP server takes OAuth: its protected resource, its
+ * authorization server, the endpoints, the scopes to ask for and the
+ * client authentication it accepts. Refuses (with the reason) anything
+ * the Gateway would not run: no PKCE S256, a resource that isn't this
+ * server, metadata naming another issuer, an endpoint off https or on a
+ * private host, a redirect anywhere.
+ */
+export async function discoverMcpOAuth(input) {
+    const urlProblem = mcpOAuthUrlProblem(input.url);
+    if (urlProblem)
+        return { ok: false, problem: urlProblem };
+    const mcpUrl = new URL(input.url);
+    const candidates = input.resourceMetadataUrl
+        ? [input.resourceMetadataUrl]
+        : [
+            ...(mcpUrl.pathname === "/" || mcpUrl.pathname === ""
+                ? []
+                : [pathInserted(mcpUrl, "oauth-protected-resource")]),
+            `${mcpUrl.origin}/.well-known/oauth-protected-resource`,
+        ];
+    let resourceMetadata = null;
+    let resourceMetadataAt = "";
+    for (const candidate of candidates) {
+        const fetched = await fetchJson(input.fetch, candidate);
+        if (fetched.kind === "failed") {
+            return { ok: false, problem: fetched.problem };
+        }
+        if (fetched.kind === "missing")
+            continue;
+        resourceMetadata = fetched.body;
+        resourceMetadataAt = candidate;
+        break;
+    }
+    if (!resourceMetadata && input.resourceMetadataUrl) {
+        return {
+            ok: false,
+            problem: `the server named its resource metadata at ${input.resourceMetadataUrl}, which didn't answer`,
+        };
+    }
+    let issuer;
+    let resource;
+    let supported = [];
+    if (resourceMetadata) {
+        const said = resourceMetadata["resource"];
+        if (typeof said !== "string" || !resourceCovers(said, mcpUrl)) {
+            return {
+                ok: false,
+                problem: `${resourceMetadataAt} describes ${typeof said === "string" ? said : "no resource"}, not ${input.url}; the Gateway refuses metadata for another server`,
+            };
+        }
+        const servers = stringList(resourceMetadata["authorization_servers"]);
+        if (servers.length === 0) {
+            return {
+                ok: false,
+                problem: `${resourceMetadataAt} names no authorization server`,
+            };
+        }
+        issuer = servers[0];
+        resource = said;
+        supported = stringList(resourceMetadata["scopes_supported"]);
+    }
+    else {
+        // The 2025-03-26 spec: the authorization server is at the MCP origin.
+        issuer = mcpUrl.origin;
+        resource = input.url;
+    }
+    const server = await authorizationServer(input.fetch, issuer);
+    if (!server.ok) {
+        return {
+            ok: false,
+            problem: resourceMetadata
+                ? server.problem
+                : `${input.url} has no OAuth metadata: no protected resource metadata, and ${server.problem}`,
+        };
+    }
+    const metadata = server.metadata;
+    const methods = stringList(metadata["code_challenge_methods_supported"]);
+    if (!methods.includes("S256")) {
+        return {
+            ok: false,
+            problem: `${server.issuer} doesn't support PKCE with S256 (code_challenge_methods_supported), which the Gateway requires`,
+        };
+    }
+    const authorize = endpointOf(metadata, "authorization_endpoint", {
+        required: true,
+        query: true,
+    });
+    if (!authorize.ok)
+        return authorize;
+    const token = endpointOf(metadata, "token_endpoint", {
+        required: true,
+        query: false,
+    });
+    if (!token.ok)
+        return token;
+    const registration = endpointOf(metadata, "registration_endpoint", {
+        required: false,
+        query: false,
+    });
+    if (!registration.ok)
+        return registration;
+    const revocation = endpointOf(metadata, "revocation_endpoint", {
+        required: false,
+        query: false,
+    });
+    if (!revocation.ok)
+        return revocation;
+    const authMethods = stringList(metadata["token_endpoint_auth_methods_supported"]);
+    const scopes = input.scope ? scopeList(input.scope) : scopeList(supported);
+    return {
+        ok: true,
+        discovery: {
+            resource,
+            issuer: server.issuer,
+            authorizationEndpoint: authorize.url,
+            tokenEndpoint: token.url,
+            ...(registration.url ? { registrationEndpoint: registration.url } : {}),
+            ...(revocation.url ? { revocationEndpoint: revocation.url } : {}),
+            scopes,
+            ...(scopeList(supported).length > 0
+                ? { supportedScopes: scopeList(supported) }
+                : {}),
+            tokenEndpointAuthMethods: authMethods.length > 0 ? authMethods : ["client_secret_basic"],
+            resourceMetadata: resourceMetadata !== null,
+            ...(metadata["client_id_metadata_document_supported"] === true
+                ? { clientIdMetadataDocument: true }
+                : {}),
+        },
+    };
+}
+/** The token endpoint auth method to ask for: Basic when offered, else the form, else a public client. */
+export function chooseTokenEndpointAuthMethod(supported) {
+    if (supported.includes("client_secret_basic"))
+        return "client_secret_basic";
+    if (supported.includes("client_secret_post"))
+        return "client_secret_post";
+    if (supported.includes("none"))
+        return "none";
+    return null;
+}
+/**
+ * Register a client with the server's authorization server (RFC 7591
+ * dynamic client registration): the Gateway's callback as the one
+ * redirect URI, the authorization-code and refresh grants, and the token
+ * endpoint auth method {@link chooseTokenEndpointAuthMethod} picks. Reads
+ * back what the server registered: its method decides `inject`.
+ */
+export async function registerMcpClient(input) {
+    const endpoint = input.discovery.registrationEndpoint;
+    if (!endpoint) {
+        return {
+            ok: false,
+            unsupported: true,
+            problem: `${input.discovery.issuer} doesn't offer dynamic client registration; register a client with it and give its id`,
+        };
+    }
+    const method = chooseTokenEndpointAuthMethod(input.discovery.tokenEndpointAuthMethods);
+    if (!method) {
+        return {
+            ok: false,
+            problem: `${input.discovery.issuer} takes clients by ${input.discovery.tokenEndpointAuthMethods.join(", ")} only; the Gateway's clients use client_secret_basic, client_secret_post or none`,
+        };
+    }
+    const body = {
+        client_name: input.clientName.slice(0, 100),
+        redirect_uris: [input.redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: method,
+        ...(input.discovery.scopes.length > 0
+            ? { scope: input.discovery.scopes.join(" ") }
+            : {}),
+    };
+    const fetched = await fetchJson(input.fetch, endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (fetched.kind === "failed")
+        return { ok: false, problem: fetched.problem };
+    if (fetched.kind === "missing") {
+        return {
+            ok: false,
+            problem: `${endpoint} refused the registration (${fetched.status})`,
+        };
+    }
+    const answer = fetched.body;
+    const clientId = answer["client_id"];
+    if (typeof clientId !== "string" || !clientId || clientId.length > 500) {
+        return { ok: false, problem: `${endpoint} answered without a client_id` };
+    }
+    const said = answer["token_endpoint_auth_method"];
+    const authMethod = typeof said === "string" && said ? said : method;
+    if (!["client_secret_basic", "client_secret_post", "none"].includes(authMethod)) {
+        return {
+            ok: false,
+            problem: `${endpoint} registered the client for ${authMethod}, which the Gateway doesn't use`,
+        };
+    }
+    const secret = answer["client_secret"];
+    const clientSecret = typeof secret === "string" && secret.length > 0 ? secret : undefined;
+    if (authMethod !== "none" && !clientSecret) {
+        return {
+            ok: false,
+            problem: `${endpoint} registered a confidential client (${authMethod}) but returned no client_secret`,
+        };
+    }
+    return {
+        ok: true,
+        clientId,
+        ...(clientSecret === undefined ? {} : { clientSecret }),
+        inject: authMethod === "client_secret_basic" ? "basic" : "form",
+        authMethod,
+    };
+}
+/**
+ * The client metadata document the Gateway serves at `clientId` (CIMD):
+ * a public client (`token_endpoint_auth_method: none`, so PKCE is its
+ * proof) with the Gateway's callback for the app as its one redirect URI.
+ */
+export function mcpClientMetadataDocument(input) {
+    return {
+        client_id: input.clientId,
+        client_name: input.clientName.slice(0, 100),
+        client_uri: input.clientUri,
+        redirect_uris: [input.redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+    };
+}
+/**
+ * A client for the Gateway at the server: the one it registers (RFC 7591),
+ * else, when it registers none, the Gateway's client metadata document's
+ * URL (`documentUrl`, null for a Gateway not on https) where the server
+ * takes CIMD and public clients. `unsupported` when neither can be had: a
+ * client must be registered by hand and pasted.
+ */
+export async function obtainMcpClient(input) {
+    const { discovery } = input;
+    if (discovery.registrationEndpoint || !discovery.clientIdMetadataDocument) {
+        const registered = await registerMcpClient(input);
+        return registered.ok ? { ...registered, via: "dcr" } : registered;
+    }
+    if (!input.documentUrl) {
+        return {
+            ok: false,
+            unsupported: true,
+            problem: `${discovery.issuer} takes clients by metadata document only, which the Gateway serves on https alone; register a client with it and give its id`,
+        };
+    }
+    if (!discovery.tokenEndpointAuthMethods.includes("none")) {
+        return {
+            ok: false,
+            unsupported: true,
+            problem: `${discovery.issuer} takes clients by metadata document but no public clients (token_endpoint_auth_methods_supported has no "none"); register a client with it and give its id`,
+        };
+    }
+    return {
+        ok: true,
+        clientId: input.documentUrl,
+        inject: "form",
+        authMethod: "none",
+        via: "cimd",
+    };
+}
+function specName(name, suffix) {
+    const room = 64 - suffix.length;
+    const trimmed = name.trim() || "MCP";
+    return `${trimmed.length > room ? trimmed.slice(0, room).trimEnd() : trimmed}${suffix}`;
+}
+function checked(id, spec) {
+    const parsed = parseProviderSpec(spec);
+    if (!parsed.ok) {
+        return { ok: false, problem: describeSpecProblems(parsed.problems) };
+    }
+    return { ok: true, id, spec };
+}
+function hostAndOrigin(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, problem: `${url} isn't a URL` };
+    }
+    if (parsed.protocol !== "https:") {
+        return {
+            ok: false,
+            problem: `${url} isn't https: a credential goes to an https server only`,
+        };
+    }
+    return {
+        ok: true,
+        host: parsed.hostname.toLowerCase().replace(/\.$/, ""),
+        origin: parsed.origin,
+    };
+}
+/**
+ * The `oauth2-user` spec of an app's own OAuth row (`<appId>-mcp`): the
+ * MCP URL's host as its one API host (the token goes there and nowhere
+ * else), the discovered endpoints, the client in `<APPID>_MCP_CLIENT_ID`
+ * (and `_SECRET` for a confidential client), PKCE, the `resource` and
+ * `issuer`. The scopes the connect asks for are the app's (its manifest's
+ * entry, from discovery); the ones the server says it supports are
+ * tolerated on a token.
+ */
+export function mcpOAuthProviderSpec(input) {
+    const where = hostAndOrigin(input.url);
+    if (!where.ok)
+        return where;
+    const id = remoteMcpProviderId(input.appId);
+    // Bounded as a spec's scope list is (40).
+    const tolerated = [
+        ...new Set([
+            ...input.discovery.scopes,
+            ...(input.discovery.supportedScopes ?? []),
+        ]),
+    ].slice(0, 40);
+    const spec = {
+        id,
+        name: specName(input.name || input.appId, " MCP server"),
+        docs: where.origin,
+        hosts: [where.host],
+        auth: {
+            kind: "oauth2-user",
+            authorizeUrl: input.discovery.authorizationEndpoint,
+            tokenUrl: input.discovery.tokenEndpoint,
+            ...(input.discovery.revocationEndpoint
+                ? { revokeUrl: input.discovery.revocationEndpoint }
+                : {}),
+            clientId: remoteMcpClientIdSetting(input.appId),
+            ...(input.client.hasSecret
+                ? { clientSecret: remoteMcpClientSecretSetting(input.appId) }
+                : {}),
+            inject: input.client.inject,
+            pkce: true,
+            scopeSeparator: "space",
+            resource: input.discovery.resource,
+            issuer: input.discovery.issuer,
+            ...(tolerated.length > 0 ? { tolerated } : {}),
+        },
+        tags: ["mcp"],
+    };
+    return checked(id, spec);
+}
+/**
+ * The API-key spec of an app's own static credential (`<appId>-mcp`): the
+ * MCP URL's host as its one host, the value in `<APPID>_MCP_TOKEN`, placed
+ * as `kind` says: `Authorization: Bearer` (or `<prefix>` as the scheme),
+ * a header (`header`, `prefix`), a query parameter (`param`), or HTTP
+ * Basic with the value as `user:password`.
+ */
+export function mcpStaticProviderSpec(input) {
+    const where = hostAndOrigin(input.url);
+    if (!where.ok)
+        return where;
+    const id = remoteMcpProviderId(input.appId);
+    const secret = remoteMcpTokenSetting(input.appId);
+    let auth;
+    switch (input.kind) {
+        case "bearer": {
+            const scheme = (input.prefix ?? "").trim();
+            auth = {
+                kind: "bearer",
+                secret,
+                ...(scheme && scheme.toLowerCase() !== "bearer" ? { scheme } : {}),
+            };
+            break;
+        }
+        case "header": {
+            const problem = remoteMcpHeaderProblem(input.header);
+            if (problem)
+                return { ok: false, problem };
+            auth = {
+                kind: "header",
+                secret,
+                header: input.header,
+                ...(input.prefix ? { prefix: input.prefix } : {}),
+            };
+            break;
+        }
+        case "query": {
+            if (!input.param) {
+                return { ok: false, problem: "name the query parameter (--param)" };
+            }
+            auth = { kind: "query", secret, param: input.param };
+            break;
+        }
+        case "basic":
+            auth = { kind: "basic", secret, as: "pair" };
+            break;
+        default:
+            return {
+                ok: false,
+                problem: `${String(input.kind)} isn't a static credential kind`,
+            };
+    }
+    const name = input.name.trim() || input.appId;
+    const spec = {
+        id,
+        name: specName(name, " MCP server"),
+        docs: where.origin,
+        hosts: [where.host],
+        auth,
+        data: "per-call",
+        hint: `The credential ${name}'s MCP server takes${input.kind === "basic" ? ", as user:password" : ""}. The Gateway sends it to ${where.host} only.`.slice(0, 500),
+        tags: ["mcp"],
+    };
+    return checked(id, spec);
+}