@12-apps/mcp 1.20.0 → 3.0.0

package/ADOPTING.md

@@ -34,7 +34,7 @@ library updates, every host updates with **no app changes**. Same contract
    `enabled: false` authorize/token/jwks/discovery answer **404** — a probe cannot
    tell a disabled AS from an app that has none — while registration answers
    **403 `access_denied`**, because RFC 7591 has a code for "the endpoint is here,
-   registration is closed". future-pay passes
+   registration is closed". The origin host passes
    `enabled: () => process.env.MCP_BEARER_ENABLED === 'true'`, so the surface stays
    OFF until an operator opts in.
 4. **No signing key, no tokens.** `signingKey` defaults to the env-backed provider
@@ -51,7 +51,7 @@ library updates, every host updates with **no app changes**. Same contract
    the internal origin rather than to an attacker's. Issuance and verification read
    the same resolver from the same request, which is what stops "minted for A,
    verified against B" from rejecting valid tokens.
-   `trustedOriginsFromEnv('MCP_OAUTH_TRUSTED_ORIGINS')` keeps future-pay's wiring.
+   `trustedOriginsFromEnv('MCP_OAUTH_TRUSTED_ORIGINS')` keeps the origin host's wiring.
 6. **The stores are narrow ports; Prisma fills them in one line.**
    `createPrismaMcpStores(async () => prisma as unknown as McpOauthPrisma)`. A
    non-Prisma host implements `OAuthClientStore` / `RefreshTokenStore` /
@@ -104,7 +104,7 @@ library updates, every host updates with **no app changes**. Same contract
      default, and it is deliberately the inconvenient one.
 10. **Connections are per USER, not per tenant** — an MCP bearer is
     auth-passthrough. `connections.resolveUserId(email)` maps the token's email to
-    the host's user id (future-pay resolves it by email because `session.user.id` is
+    the host's user id (the origin host resolves it by email because `session.user.id` is
     the OAuth `sub`); returning `null` records nothing. Recording is best-effort and
     FENCED: a failing directory can never turn a valid grant into a 500, and nothing
     about the attempt is logged, because the only values in hand are an email and a
@@ -211,7 +211,7 @@ Two things about the gates worth knowing before you adopt them:
   committed exclusions file the moment it adopted the package, so it needs its own
   burn-down).
 
-## Phase B — adopting into a host that ALREADY has these tables (future-pay)
+## Phase B — adopting into a host that ALREADY has these tables (the origin host)
 
 **Nothing to baseline.** Every statement in the package migration is guarded
 (`CREATE TABLE IF NOT EXISTS`, `CREATE [UNIQUE] INDEX IF NOT EXISTS`, `ADD COLUMN
@@ -223,8 +223,8 @@ a host that already has `oauth_clients` / `oauth_refresh_tokens` /
 Deliberate deltas to reconcile:
 
 - **The FK from `mcp_connections.user_id` to `users` is not in the package
-  migration** — host vocabulary. future-pay keeps its `ON DELETE CASCADE`.
-- **`onboarding_states` is not here.** future-pay's migration created it beside
+  migration** — host vocabulary. The origin host keeps its `ON DELETE CASCADE`.
+- **`onboarding_states` is not here.** The origin host's migration created it beside
   `mcp_connections`; it belongs to `@12-apps/onboarding` (12-23).
 - The host's `lib/mcp/oauth/**` (~1.5k LOC) and its four route files are replaced
   by the mount plus, where a coverage gate forces the file to exist, a one-line
@@ -242,7 +242,7 @@ Deliberate deltas to reconcile:
   and redactions, is the host's catalogue. The package generates, dispatches and
   gates it.
 - **`mcp:lint`, `mcp:parity`, `mcp:smoke`, `mcp:test-coverage`** — the remaining
-  future-pay MCP scripts. Only the two the reusable CI workflows shell out to moved
+  the origin host MCP scripts. Only the two the reusable CI workflows shell out to moved
   (12-23's scope).
 - **Authorization codes as rows.** They are stateless signed blobs, so there is no
   table and nothing to sweep — only the replay store (rule 8).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/mcp",
-  "version": "1.20.0",
+  "version": "3.0.0",
   "type": "module",
   "description": "App-agnostic MCP server core: generate one MCP tool per OpenAPI operation and proxy each call carrying the caller's bearer token (permission passthrough). Also ships the OAuth 2.1 authorization server (./oauth, ./hono: register/authorize/token, JWKS and both .well-known documents), the package-owned Prisma partial + migration for its three tables, the mcp:generate/mcp:check (./generate) and mcp:coverage (./coverage) gates, and the reusable AI-connect onboarding UI (./react).",
   "exports": {
@@ -23,9 +23,9 @@
     "prisma:sync:check": "node scripts/sync-mcp-schema.mjs --check"
   },
   "dependencies": {
-    "@12-apps/onboarding": "^1.20.0",
-    "@12-apps/rbac": "^1.20.0",
-    "@12-apps/ui": "^4.0.0",
+    "@12-apps/onboarding": "^2.0.0",
+    "@12-apps/rbac": "^4.0.0",
+    "@12-apps/ui": "^5.0.0",
     "@mui/icons-material": "^6.5.0",
     "jose": "^6.1.3",
     "react": "^19.2.0"

package/prisma/mcp.prisma

@@ -11,7 +11,7 @@
 //
 // Host-agnostic by design (the entity-lifecycle / rbac doctrine): `user_id` is a
 // by-value scalar with NO relation, because this package cannot know the name of
-// the host's user model. The host's own migration may add the FK (future-pay's
+// the host's user model. The host's own migration may add the FK (the origin host's
 // is ON DELETE CASCADE). Note there is deliberately no `oauth_codes` table:
 // authorization codes are STATELESS signed blobs, so there is nothing to store
 // and nothing to sweep.

package/prisma/migrations/20260812150000_add_mcp_oauth_tables/migration.sql

@@ -18,13 +18,13 @@
 -- Authorization codes are deliberately absent: they are STATELESS signed blobs,
 -- so there is no table to create and nothing to sweep.
 --
--- The columns, defaults, indexes and CHECK are future-pay's
+-- The columns, defaults, indexes and CHECK are the origin host's
 -- `20260713120000_add_oauth_client_refresh`,
 -- `20260715180000_add_onboarding_state_mcp_connection` (the mcp_connections half
 -- — the onboarding half belongs to @12-apps/onboarding) and
 -- `20260720120000_add_mcp_connection_host` verbatim, minus the FK to `users`:
 -- this package cannot know the name of a host's user table, and a host that has
--- one keeps its own constraint (future-pay's is ON DELETE CASCADE).
+-- one keeps its own constraint (the origin host's is ON DELETE CASCADE).
 --
 -- EVERY statement is guarded (`IF NOT EXISTS`, and a conrelid-scoped DO block for
 -- the CHECK, which has no IF NOT EXISTS form). That is what makes adoption by a
@@ -35,7 +35,7 @@
 -- the difference bites exactly the host this file is written for: `CREATE TABLE IF
 -- NOT EXISTS` skips the whole table, columns included, so a host holding an OLDER
 -- shape of one of these tables silently keeps it. Each table below is therefore
--- followed by a guarded `ADD COLUMN` for every column that reached future-pay in a
+-- followed by a guarded `ADD COLUMN` for every column that reached the origin host in a
 -- LATER migration than its own CREATE. The full audit: `oauth_refresh_tokens
 -- .user_sub` (`20260713150000_add_oauth_refresh_user_sub`) and `mcp_connections
 -- .host` (`20260720120000_add_mcp_connection_host`). `oauth_clients` needs none —
@@ -112,10 +112,10 @@ CREATE INDEX IF NOT EXISTS "oauth_refresh_tokens_user_email_client_id_idx"
 -- `CREATE TABLE IF NOT EXISTS` skips the WHOLE table, so a host that already holds
 -- `oauth_refresh_tokens` in an OLDER SHAPE gets none of the columns declared above
 -- — statement-level guarding is not the same as column-level guarding. That is
--- precisely how future-pay's own history ran: `user_sub` arrived in a SECOND
+-- precisely how the origin host's own history ran: `user_sub` arrived in a SECOND
 -- migration (FUT-105, `20260713150000_add_oauth_refresh_user_sub`), so a host
 -- frozen before it would adopt this file, skip the CREATE, never get the column,
--- and then fail on every refresh the package serves. Mirror future-pay's pair
+-- and then fail on every refresh the package serves. Mirror the origin host's pair
 -- verbatim — guarded add with a backfill default to satisfy NOT NULL, then drop
 -- the default so the column matches the Prisma schema (`String`, no default).
 -- Both statements are no-ops on a fresh host and on a replay.
@@ -147,6 +147,6 @@ CREATE INDEX IF NOT EXISTS "mcp_connections_last_active_at_idx"
   ON "mcp_connections"("last_active_at");
 
 -- A host adopting this migration where `mcp_connections` predates the `host`
--- column (future-pay added it in a later migration) gets it here; a fresh host
+-- column (the origin host added it in a later migration) gets it here; a fresh host
 -- already has it from the CREATE above, so the guard makes both cases a no-op.
 ALTER TABLE "mcp_connections" ADD COLUMN IF NOT EXISTS "host" TEXT;

package/scripts/sync-mcp-schema.mjs

@@ -14,14 +14,14 @@
  *
  * Only the schema partial. MIGRATIONS ARE NOT HANDLED HERE — the host
  * discovers and copies them structurally, by looking for a `prisma/migrations`
- * directory inside every installed `@12-apps/*` package (see future-pay's
+ * directory inside every installed `@12-apps/*` package (see the origin host's
  * packages/prisma/scripts/sync-prisma-plugins.mjs).
  *
  * The host package that owns the schema folder MUST also declare this package
  * as a dependency, so the source of the copy is present in every build
  * context.
  *
- * Default host path follows the future-pay layout
+ * Default host path follows the origin host layout
  * (`packages/prisma/prisma/schema/`); another repo passes its own schema
  * folder as the positional argument, or sets MCP_HOST_SCHEMA_DIR.
  */

package/src/coverage-gate/index.ts

@@ -6,7 +6,7 @@ import { collectRouteMethods } from "./route-methods";
 
 /**
  * `@12-apps/mcp/coverage` — the MCP route/action coverage gate (12-23), moved out
- * of future-pay's `apps/web/scripts/mcp/coverage.ts` so a host's own script is a
+ * of the origin host's `apps/web/scripts/mcp/coverage.ts` so a host's own script is a
  * one-line re-export and the CI workflow that shells out to the consumer's
  * `mcp:coverage` package script (`12-apps/ci`'s `mcp-contract.yml`) keeps working
  * unchanged.

package/src/coverage-gate/route-methods.ts

@@ -11,7 +11,7 @@ import { exportedNamesOf, urlPathOf, walkRouteFiles } from "@12-apps/rbac/covera
  * walk (`walkRouteFiles`), the URL mapping (`urlPathOf`) AND the export-head
  * parser (`exportedNamesOf`) — and that is deliberate: both gates assert a
  * COMPLETENESS property over the same two surfaces (`app/**` route files and
- * `*actions.ts` modules), and future-pay's own comment on the shared scanner says
+ * `*actions.ts` modules), and the origin host's own comment on the shared scanner says
  * why they must share it — "so the two gates can never disagree about what the
  * surface is". Two copies would agree on the day they were written and drift
  * silently after, in the direction of not looking. What is left here is the one

package/src/generate/index.ts

@@ -13,7 +13,7 @@ import type { ToolManifest } from "../types";
 
 /**
  * `@12-apps/mcp/generate` — the `mcp:generate` / `mcp:check` gate (12-23), moved
- * out of future-pay's `apps/web/scripts/mcp/generate.ts` so a host's own script is
+ * out of the origin host's `apps/web/scripts/mcp/generate.ts` so a host's own script is
  * a one-line call and `12-apps/ci`'s `mcp-contract.yml`, which shells out to the
  * consumer's `mcp:check` package script, keeps working unchanged.
  *

package/src/guide.ts

@@ -99,104 +99,125 @@ const CONNECTOR_TAIL: readonly string[] = [
  * stage 2 creates the connector and signs in — which registers the connection on
  * the store side, so no prompt needs to be pasted afterwards.
  */
-const CHATGPT_CONFIGURE_STAGES: readonly AiHostConfigureStage[] = [
-  {
-    id: "enable-dev-mode",
-    label: "enable developer mode",
-    link: {
-      url: "https://chatgpt.com/plugins#settings/Security",
-      label: "Abrir Segurança e login",
+function chatgptConfigureStages(
+  platformName: string,
+): readonly AiHostConfigureStage[] {
+  return [
+    {
+      id: "enable-dev-mode",
+      label: "enable developer mode",
+      link: {
+        url: "https://chatgpt.com/plugins#settings/Security",
+        label: "Abrir Segurança e login",
+      },
+      steps: [
+        "Ative o Modo desenvolvedor em Settings › Security and login (Segurança e login).",
+      ],
     },
-    steps: [
-      "Ative o Modo desenvolvedor em Settings › Security and login (Segurança e login).",
-    ],
-  },
-  {
-    id: "configurar",
-    label: "configurar",
-    link: {
-      url: "https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins",
-      label: "Criar o conector",
+    {
+      id: "configurar",
+      label: "configurar",
+      link: {
+        url: "https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins",
+        label: "Criar o conector",
+      },
+      steps: [
+        "Isso vai abrir um popup para você criar um plugin novo. Coloque como nome o nome da sua loja e, no campo MCP, o link copiado no passo anterior.",
+        'Marque a caixa "I understand and want to continue" — a OpenAI não revisou este servidor MCP; ela avisa que sites podem tentar roubar seus dados ou induzir o modelo a ações indevidas, incluindo destruir dados.',
+        `Clique em "Sign in with ${platformName}" e entre com a sua conta de lojista para autorizar o acesso. Pronto: a conexão é registrada automaticamente.`,
+      ],
     },
-    steps: [
-      "Isso vai abrir um popup para você criar um plugin novo. Coloque como nome o nome da sua loja e, no campo MCP, o link copiado no passo anterior.",
-      'Marque a caixa "I understand and want to continue" — a OpenAI não revisou este servidor MCP; ela avisa que sites podem tentar roubar seus dados ou induzir o modelo a ações indevidas, incluindo destruir dados.',
-      'Clique em "Sign in with Future Drink" e entre com a sua conta de lojista para autorizar o acesso. Pronto: a conexão é registrada automaticamente.',
-    ],
-  },
-];
+  ];
+}
 
 /**
  * The AI hosts a store owner can connect, in recommended order. Same OAuth flow
  * everywhere (the host drives it) — only the menu path differs per app.
+ *
+ * A FUNCTION of the platform's name, because one step is not generic: the
+ * ChatGPT connector's consent screen shows an OAuth button labelled with
+ * whoever operates the server, and the owner is told which button to click. It
+ * used to name one particular STORE on one particular deployment — not even the
+ * product, a tenant of it — so every other adopter instructed its owners to
+ * click a button that does not exist.
  */
-export const AI_HOST_GUIDES: readonly AiHostGuide[] = [
-  {
-    id: "claude",
-    label: "Claude.ai",
-    brand: "claude",
-    kind: "No navegador",
-    link: {
-      url: "https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors",
-      label: "Abrir os conectores do Claude",
-    },
-    docs: {
-      url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
-      label: "documentação oficial da Anthropic — conectores personalizados",
+export function aiHostGuides(platformName: string): readonly AiHostGuide[] {
+  const chatgptStages = chatgptConfigureStages(platformName);
+  return [
+    {
+      id: "claude",
+      label: "Claude.ai",
+      brand: "claude",
+      kind: "No navegador",
+      link: {
+        url: "https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors",
+        label: "Abrir os conectores do Claude",
+      },
+      docs: {
+        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+        label: "documentação oficial da Anthropic — conectores personalizados",
+      },
+      steps: [
+        "Clique no botão acima (ou vá em Settings › Customize › Connectors) e escolha Add custom connector.",
+        "Dê um nome ao conector (ex.: o nome da sua loja) e cole a URL do servidor MCP da sua loja (copie acima) no campo de URL.",
+        ...CONNECTOR_TAIL,
+      ],
     },
-    steps: [
-      "Clique no botão acima (ou vá em Settings › Customize › Connectors) e escolha Add custom connector.",
-      "Dê um nome ao conector (ex.: o nome da sua loja) e cole a URL do servidor MCP da sua loja (copie acima) no campo de URL.",
-      ...CONNECTOR_TAIL,
-    ],
-  },
-  {
-    id: "claude-desktop",
-    label: "Claude Desktop",
-    brand: "claude",
-    kind: "Aplicativo (Windows/Mac)",
-    docs: {
-      url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
-      label: "documentação oficial da Anthropic — conectores personalizados",
+    {
+      id: "claude-desktop",
+      label: "Claude Desktop",
+      brand: "claude",
+      kind: "Aplicativo (Windows/Mac)",
+      docs: {
+        url: "https://support.anthropic.com/en/articles/11175166-how-do-i-connect-mcp-servers-to-claude-ai",
+        label: "documentação oficial da Anthropic — conectores personalizados",
+      },
+      steps: [
+        "Abra o Claude Desktop e vá em Settings (⚙️) › Connectors.",
+        "Clique em Add custom connector e cole a URL do servidor MCP da sua loja (copie acima).",
+        ...CONNECTOR_TAIL,
+      ],
     },
-    steps: [
-      "Abra o Claude Desktop e vá em Settings (⚙️) › Connectors.",
-      "Clique em Add custom connector e cole a URL do servidor MCP da sua loja (copie acima).",
-      ...CONNECTOR_TAIL,
-    ],
-  },
-  {
-    id: "chatgpt",
-    label: "ChatGPT",
-    brand: "openai",
-    kind: "No navegador",
-    link: { url: "https://chatgpt.com/plugins", label: "Abrir os plugins do ChatGPT" },
-    docs: {
-      url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
-      label: "documentação oficial da OpenAI — conectar um servidor MCP ao ChatGPT",
+    {
+      id: "chatgpt",
+      label: "ChatGPT",
+      brand: "openai",
+      kind: "No navegador",
+      link: {
+        url: "https://chatgpt.com/plugins",
+        label: "Abrir os plugins do ChatGPT",
+      },
+      docs: {
+        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+        label:
+          "documentação oficial da OpenAI — conectar um servidor MCP ao ChatGPT",
+      },
+      configureStages: chatgptStages,
+      // Mirrors the flattened stage instructions so the MCP connect guide
+      // (`connectToChatGpt`) can never drift from what owners see in the wizard.
+      steps: chatgptStages.flatMap((stage) => stage.steps),
     },
-    configureStages: CHATGPT_CONFIGURE_STAGES,
-    // Mirrors the flattened stage instructions so the MCP connect guide
-    // (`connectToChatGpt`) can never drift from what owners see in the wizard.
-    steps: CHATGPT_CONFIGURE_STAGES.flatMap((stage) => stage.steps),
-  },
-  {
-    id: "codex",
-    label: "Codex",
-    brand: "openai",
-    kind: "App / CLI de desenvolvedor",
-    link: { url: "https://developers.openai.com/codex", label: "Documentação do Codex" },
-    docs: {
-      url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
-      label: "documentação oficial da OpenAI — conectar um servidor MCP",
+    {
+      id: "codex",
+      label: "Codex",
+      brand: "openai",
+      kind: "App / CLI de desenvolvedor",
+      link: {
+        url: "https://developers.openai.com/codex",
+        label: "Documentação do Codex",
+      },
+      docs: {
+        url: "https://developers.openai.com/apps-sdk/deploy/connect-chatgpt",
+        label: "documentação oficial da OpenAI — conectar um servidor MCP",
+      },
+      steps: [
+        "No Codex, abra as configurações de MCP (Settings › MCP no app, ou o arquivo de configuração na CLI).",
+        "Adicione um servidor MCP e cole a URL do servidor MCP da sua loja (copie acima) como um conector remoto (HTTP).",
+        ...CONNECTOR_TAIL,
+      ],
     },
-    steps: [
-      "No Codex, abra as configurações de MCP (Settings › MCP no app, ou o arquivo de configuração na CLI).",
-      "Adicione um servidor MCP e cole a URL do servidor MCP da sua loja (copie acima) como um conector remoto (HTTP).",
-      ...CONNECTOR_TAIL,
-    ],
-  },
-];
+  ];
+}
 
 export interface AiCapability {
   /** Stable id — maps to an icon in the component. */
@@ -217,7 +238,8 @@ export const AI_CAPABILITIES: readonly AiCapability[] = [
   {
     id: "inventory",
     title: "Controle o estoque",
-    detail: '"Quanto ainda tenho do produto X? Registre a entrada de 20 unidades."',
+    detail:
+      '"Quanto ainda tenho do produto X? Registre a entrada de 20 unidades."',
   },
   {
     id: "catalog",
@@ -239,15 +261,39 @@ export const AI_CAPABILITIES: readonly AiCapability[] = [
 export const AI_PERMISSION_MODEL =
   "O assistente age em seu nome, com exatamente as suas permissões: ele pode fazer o que você pode fazer na sua loja — nada além disso. Não é preciso criar nenhuma chave ou credencial extra; a autorização usa o seu próprio login.";
 
+/** The two tools the paste-in prompt drives, and what to call the store id. */
+export interface AiConnectPromptSpec {
+  /**
+   * The tool that REGISTERS the connection server-side, so the store learns
+   * which assistant connected.
+   */
+  announceTool: string;
+  /** A real READ tool, called straight after, to prove the access works. */
+  probeTool: string;
+  /** What that read returns, in the owner's own words ("o estoque da loja"). */
+  probeSubject: string;
+  /** What the assistant should ask for if it needs to identify the store. */
+  identifierName: string;
+}
+
 /**
- * The message the owner pastes into the assistant's chat right after connecting.
- * It makes the assistant (1) call `announceAiConnection` reporting which host it
- * is (chatgpt / claude / codex) — the tool that registers the connection on the
- * server side so the store learns which assistant connected — and (2) call a
- * real read tool to confirm access. The owner types nothing.
+ * The message the owner pastes into the assistant's chat right after
+ * connecting: announce the connection, then read something real to prove it
+ * works. The owner types nothing.
+ *
+ * BUILT from the host's tool names rather than shipped with them. This was a
+ * constant naming two tools — `announceAiConnection` and `listInventory` — that
+ * THIS PACKAGE does not define or serve; they belong to one adopter's surface.
+ * Any other host handed its owner a prompt instructing the assistant to call
+ * two tools that do not exist, and because nothing registered the connection,
+ * the wizard's confirm step then waited forever for a state that could never
+ * arrive.
  */
-export const AI_CONNECT_PROMPT =
-  "Você agora tem acesso ao conector MCP da minha loja. Faça, nesta ordem:\n" +
-  '1) Execute a ferramenta announceAiConnection informando qual assistente você é (host: "chatgpt", "claude" ou "codex") para registrar a conexão com a minha loja.\n' +
-  "2) Execute a ferramenta listInventory para confirmar o acesso ao estoque da minha loja.\n" +
-  "Se precisar do identificador da loja, me pergunte o tenantSlug.";
+export function aiConnectPrompt(spec: AiConnectPromptSpec): string {
+  return (
+    "Você agora tem acesso ao conector MCP da minha loja. Faça, nesta ordem:\n" +
+    `1) Execute a ferramenta ${spec.announceTool} informando qual assistente você é (host: "chatgpt", "claude" ou "codex") para registrar a conexão com a minha loja.\n` +
+    `2) Execute a ferramenta ${spec.probeTool} para confirmar o acesso a ${spec.probeSubject}.\n` +
+    `Se precisar do identificador da loja, me pergunte o ${spec.identifierName}.`
+  );
+}

package/src/index.ts

@@ -13,10 +13,11 @@ export * from "./types";
 // truth for BOTH the `@12-apps/mcp/react` onboarding UI and the server-side connect
 // tools, so what an agent reads via MCP cannot drift from what owners see.
 export {
-  AI_HOST_GUIDES,
+  aiHostGuides,
   AI_CAPABILITIES,
   AI_PERMISSION_MODEL,
-  AI_CONNECT_PROMPT,
+  aiConnectPrompt,
+  type AiConnectPromptSpec,
   providerForHostId,
   type AiHostBrand,
   type AiHostLink,

package/src/oauth/access-token.ts

@@ -4,7 +4,7 @@ import { issuer, resourceAudience, DEFAULT_MCP_RESOURCE_PATH, type McpScope } fr
 import { SIGNING_ALG, type McpSigningKeyProvider } from "./keys";
 
 /**
- * JWT access-token issuer + verifier (12-23, ported from future-pay's
+ * JWT access-token issuer + verifier (12-23, ported from the origin host's
  * `lib/mcp/oauth/jwt.ts` — behaviour unchanged; the signing key arrives through a
  * provider and the resource path is config).
  *

package/src/oauth/authorization-code.ts

@@ -4,7 +4,7 @@ import { issuer } from "./config";
 import { SIGNING_ALG, type McpSigningKeyProvider } from "./keys";
 
 /**
- * Stateless authorization-code mint/verify (12-23, ported from future-pay's
+ * Stateless authorization-code mint/verify (12-23, ported from the origin host's
  * `lib/mcp/oauth/authorization-code.ts` — behaviour unchanged; the signing key
  * arrives through a provider instead of an env read).
  *

package/src/oauth/authorize.ts

@@ -6,7 +6,7 @@ import type { StoredOAuthClient } from "./stores";
 
 /**
  * The OAuth 2.1 Authorization Code + PKCE authorization endpoint (12-23, ported
- * from future-pay's `app/api/oauth/authorize/route.ts`).
+ * from the origin host's `app/api/oauth/authorize/route.ts`).
  *
  * It renders no UI: it authenticates the caller against the host's cookie session
  * (through `resolveSession`), validates the request, and either 302-redirects an

package/src/oauth/clients.ts

@@ -8,7 +8,7 @@ import type {
 
 /**
  * Client registration and the open-redirect guard (12-23, ported from
- * future-pay's `lib/mcp/oauth/clients.ts`).
+ * the origin host's `lib/mcp/oauth/clients.ts`).
  *
  * A registered client is an external host (a Claude.ai / ChatGPT connector) from
  * RFC 7591 dynamic client registration, or a static registration an operator
@@ -122,7 +122,7 @@ export interface ProviderAttributionRule {
   provider: string;
 }
 
-/** future-pay's rules, and a sane default for any host talking to the same two. */
+/** The origin host's rules, and a sane default for any host talking to the same two. */
 export const DEFAULT_PROVIDER_ROOTS: readonly ProviderAttributionRule[] = [
   { roots: ["claude.ai", "anthropic.com"], provider: "claude" },
   { roots: ["chatgpt.com", "openai.com"], provider: "chatgpt" },

package/src/oauth/code-replay.ts

@@ -1,6 +1,6 @@
 /**
  * Single-use guard for the stateless authorization codes (12-23, ported from
- * future-pay's `lib/mcp/oauth/token-replay.ts`).
+ * the origin host's `lib/mcp/oauth/token-replay.ts`).
  *
  * A code is a signed blob with a `jti`, so "already redeemed" has to be remembered
  * somewhere. The in-process option remembers it IN THIS PROCESS: a small map of

package/src/oauth/config.ts

@@ -1,7 +1,7 @@
 /**
  * The OAuth 2.1 authorization-server foundation: the shared scope source, the
  * issuer/audience derivation, and the trusted-origin resolver every URL in the
- * surface is built from (12-23, ported from future-pay's
+ * surface is built from (12-23, ported from the origin host's
  * `lib/mcp/oauth/config.ts`).
  *
  * Keeping the scopes and the origin resolution in ONE place is what stops the
@@ -11,7 +11,7 @@
  *
  * What was env-reading in the host is CONFIG here (the package must not learn a
  * host's variable names); `trustedOriginsFromEnv` is the one-line helper that
- * keeps future-pay's wiring identical.
+ * keeps the origin host's wiring identical.
  */
 
 /** Scopes advertised by both discovery documents. `mcp:write` gates mutating tools. */
@@ -66,7 +66,7 @@ function normalizeOrigins(origins: readonly string[]): string[] {
 }
 
 /**
- * Read a comma-separated allowlist out of an environment variable — future-pay
+ * Read a comma-separated allowlist out of an environment variable — the origin host
  * passes `trustedOriginsFromEnv('MCP_OAUTH_TRUSTED_ORIGINS')`, so the behaviour
  * is identical while the variable's NAME stays the host's.
  */

package/src/oauth/context.ts

@@ -25,7 +25,7 @@ import type { McpOauthStores, StoredOAuthClient } from "./stores";
 /** The identity an authorize request binds a code to. From the SESSION only. */
 export interface McpOauthSession {
   /**
-   * The OAuth subject (future-pay passes the Google `sub`, falling back to the
+   * The OAuth subject (the origin host passes the Google `sub`, falling back to the
    * email). Carried through every rotation so a refreshed token keeps the same
    * stable `sub`.
    */
@@ -45,7 +45,7 @@ export interface McpOauthPaths {
 }
 
 export const DEFAULT_OAUTH_PATHS: McpOauthPaths = {
-  // future-pay's paths, and the ones the RFC 8414 document has always advertised.
+  // the origin host's paths, and the ones the RFC 8414 document has always advertised.
   authorize: "/api/oauth/authorize",
   token: "/api/oauth/token",
   register: "/api/oauth/register",
@@ -78,12 +78,12 @@ export interface McpOauthConfig {
   resolveSession: (request: Request) => Promise<McpOauthSession | null> | McpOauthSession | null;
   /**
    * The operator gate. `false` makes the whole surface inert — authorize/token/jwks
-   * answer 404 and registration answers 403 — which is how future-pay ships it OFF
+   * answer 404 and registration answers 403 — which is how the origin host ships it OFF
    * by default (`MCP_BEARER_ENABLED`). Default: enabled (mounting is the opt-in).
    */
   enabled?: boolean | (() => boolean);
   /**
-   * Signing material. Default: the env-backed provider with future-pay's variable
+   * Signing material. Default: the env-backed provider with the origin host's variable
    * names. `null` from the provider means "not provisioned": nothing is minted and
    * the JWKS answers 503 rather than falling back to a weaker mode.
    */
@@ -216,7 +216,7 @@ export function resolveMcpOauthConfig(config: McpOauthConfig): McpOauthContext {
     stores: config.stores,
     resolveSession: config.resolveSession,
     // Mounting is the opt-in, so the gate defaults to ON; a host that ships the
-    // surface dark passes its own flag (future-pay: `MCP_BEARER_ENABLED`).
+    // surface dark passes its own flag (the origin host: `MCP_BEARER_ENABLED`).
     enabled: typeof enabled === "function" ? enabled : () => enabled,
     // `null` from the provider means "not provisioned": nothing is minted and the
     // JWKS answers 503 rather than falling back to a weaker mode.

package/src/oauth/keys.ts

@@ -2,7 +2,7 @@ import { exportJWK, importPKCS8, type CryptoKey, type JWK } from "jose";
 
 /**
  * Signing-key / JWK loading for the OAuth authorization server (12-23, ported
- * from future-pay's `lib/mcp/oauth/keys.ts`).
+ * from the origin host's `lib/mcp/oauth/keys.ts`).
  *
  * ES256 (P-256) from PEM material, the published public JWK (with `kid` for
  * rotation), and a safe-by-default absence signal (`null`) when no key is
@@ -10,7 +10,7 @@ import { exportJWK, importPKCS8, type CryptoKey, type JWK } from "jose";
  * rather than falling back to a weaker mode while the surface is mounted.
  *
  * WHERE the PEM comes from is the host's business: `loadSigningKeyFromEnv` keeps
- * future-pay's env-var wiring, and any other provider (a secrets manager, a KMS
+ * the origin host's env-var wiring, and any other provider (a secrets manager, a KMS
  * export) satisfies the same `McpSigningKeyProvider` shape.
  */
 
@@ -87,13 +87,13 @@ export function signingKeyProvider(
   };
 }
 
-/** Env var carrying the ES256 private key as a PKCS#8 PEM (future-pay's name). */
+/** Env var carrying the ES256 private key as a PKCS#8 PEM (the origin host's name). */
 export const DEFAULT_SIGNING_KEY_ENV = "MCP_OAUTH_SIGNING_KEY";
 /** Env var carrying the key id (`kid`) used to select the key during rotation. */
 export const DEFAULT_SIGNING_KEY_ID_ENV = "MCP_OAUTH_SIGNING_KEY_ID";
 
 /**
- * The env-backed provider — future-pay's wiring, kept identical, with the
+ * The env-backed provider — the origin host's wiring, kept identical, with the
  * variable names as arguments so the package states no host's vocabulary.
  */
 export function loadSigningKeyFromEnv(

package/src/oauth/pkce.ts

@@ -1,6 +1,6 @@
 /**
  * PKCE (RFC 7636) S256 challenge helpers for the OAuth authorization server
- * (12-23, ported verbatim from future-pay's `lib/mcp/oauth/pkce.ts`).
+ * (12-23, ported verbatim from the origin host's `lib/mcp/oauth/pkce.ts`).
  *
  * OAuth 2.1 mandates the `S256` code-challenge method and forbids `plain`, so
  * this module computes `BASE64URL(SHA-256(code_verifier))` and compares it to

package/src/oauth/refresh.ts

@@ -3,7 +3,7 @@ import { createHash, randomBytes } from "node:crypto";
 import type { NewRefreshToken, RefreshTokenStore, StoredRefreshToken } from "./stores";
 
 /**
- * Refresh-token issue + rotation (12-23, ported from future-pay's
+ * Refresh-token issue + rotation (12-23, ported from the origin host's
  * `lib/mcp/oauth/refresh.ts` — behaviour unchanged; Prisma calls became the
  * `RefreshTokenStore` port).
  *

package/src/oauth/register.ts

@@ -3,7 +3,7 @@ import type { McpOauthContext } from "./context";
 import type { TokenEndpointAuthMethod } from "./stores";
 
 /**
- * RFC 7591 Dynamic Client Registration (12-23, ported from future-pay's
+ * RFC 7591 Dynamic Client Registration (12-23, ported from the origin host's
  * `app/api/oauth/register/route.ts`).
  *
  * An external host (a Claude.ai / ChatGPT connector) self-registers by POSTing RFC

package/src/oauth/token-grants.ts

@@ -19,7 +19,7 @@ import {
 } from "./token-response";
 
 /**
- * The two grant handlers of the token endpoint (12-23, ported from future-pay's
+ * The two grant handlers of the token endpoint (12-23, ported from the origin host's
  * `lib/mcp/oauth/token-grants.ts`).
  *
  * Security invariants enforced here, unchanged:
@@ -123,7 +123,7 @@ function readAuthorizationCodeParams(form: URLSearchParams): AuthorizationCodePa
 /**
  * Redeem a presented code, or refuse.
  *
- * The ORDER is the security contract, and it is the order future-pay established:
+ * The ORDER is the security contract, and it is the order the origin host established:
  * verify the code's signature, authenticate the presenting client against the
  * client the code was bound to, check the bound `redirect_uri`, check PKCE — and
  * only THEN consume the single-use `jti`. Consuming earlier would let a failed

package/src/oauth/token-response.ts

@@ -5,7 +5,7 @@ import type { OAuthClientStore } from "./stores";
 /**
  * The token endpoint's wire helpers: the RFC 6749 §5.1/§5.2 bodies and client
  * authentication (12-23, split out of the grant handlers so each file stays under
- * the size gate — the same split future-pay made).
+ * the size gate — the same split the origin host made).
  *
  * These bodies are NOT the house `{ data }` envelope, deliberately: they are read
  * by OAuth clients that expect the RFC shapes at the top level, and `Cache-Control:

package/src/react/ai-onboarding.tsx

@@ -10,8 +10,7 @@ import {
 
 import {
   AI_CAPABILITIES,
-  AI_CONNECT_PROMPT,
-  AI_HOST_GUIDES,
+  aiHostGuides,
   AI_PERMISSION_MODEL,
   type AiCapability,
   type AiHostGuide,
@@ -44,14 +43,33 @@ export interface AiIntegrationOnboardingProps {
   featureKey?: string;
   /** Show the dev-only "reset onboarding" button. @default false */
   devReset?: boolean;
-  /** Assistants offered in the flow. @default the shared AI_HOST_GUIDES */
+  /**
+   * The platform operating this MCP server, as its OAuth consent button names
+   * it. REQUIRED, and it is the reason `hosts` can have a default at all: one
+   * ChatGPT step tells the owner which "Sign in with …" button to click, and
+   * that button carries whoever runs the server. It used to be a hard-coded
+   * name — of a single STORE on one deployment, not even the product — so every
+   * other adopter pointed its owners at a button that does not exist.
+   */
+  platformName: string;
+  /** Assistants offered in the flow. @default aiHostGuides(platformName) */
   hosts?: readonly AiHostGuide[];
   /** Capability cards on the landing. @default the shared AI_CAPABILITIES */
   capabilities?: readonly AiCapability[];
   /** Permission reassurance copy on the landing. @default AI_PERMISSION_MODEL */
   permissionModel?: string;
-  /** Message pasted into the assistant on the Conectar step. @default AI_CONNECT_PROMPT */
-  connectPrompt?: string;
+  /**
+   * Message the owner pastes into the assistant on the Conectar step.
+   *
+   * REQUIRED, with no default, because the useful version of it names TOOLS —
+   * one to register the connection, one to read something real — and this
+   * package neither defines nor serves any. It shipped a constant naming two
+   * tools from one adopter's surface, so another host handed its owner a prompt
+   * that called two things that did not exist, and the confirm step then waited
+   * forever for a registration that could never happen. Build it with
+   * `aiConnectPrompt({ … })`.
+   */
+  connectPrompt: string;
   /**
    * Re-check the live connection on the verify step's "Testar conexão" button —
    * apps pass a router refresh (e.g. Next's `router.refresh`). @default a full
@@ -100,10 +118,19 @@ function AiOnboardingFlow(props: FlowProps): React.JSX.Element {
     devReset,
   } = props;
   const { state } = useOnboarding();
-  const selectedHost = hosts.find((h) => h.id === state.data.selectedHost) ?? hosts[0]!;
+  const selectedHost =
+    hosts.find((h) => h.id === state.data.selectedHost) ?? hosts[0]!;
 
-  const steps = buildFlowSteps({ host: selectedHost, hosts, endpointUrl, connectPrompt, connections, onRetest });
-  const connectedHostId = (state.data.connectedHost ?? state.data.selectedHost) as string | undefined;
+  const steps = buildFlowSteps({
+    host: selectedHost,
+    hosts,
+    endpointUrl,
+    connectPrompt,
+    connections,
+    onRetest,
+  });
+  const connectedHostId = (state.data.connectedHost ??
+    state.data.selectedHost) as string | undefined;
 
   return (
     <GuidedSection
@@ -111,13 +138,22 @@ function AiOnboardingFlow(props: FlowProps): React.JSX.Element {
       title="Conecte assistentes de IA à sua loja"
       startLabel="Ver como conectar"
       renderLanding={(start) => (
-        <AiLanding onStart={start} permissionModel={permissionModel} capabilities={capabilities} />
+        <AiLanding
+          onStart={start}
+          permissionModel={permissionModel}
+          capabilities={capabilities}
+        />
       )}
       configuredTitle={connectedTitle(connections, hosts, connectedHostId)}
       configuredSummary={connectedSummary(connections)}
       editLabel="Conectar IA"
       completedContent={(nav) => (
-        <StatusBoard nav={nav} connections={connections} hosts={hosts} onDisconnect={onDisconnect} />
+        <StatusBoard
+          nav={nav}
+          connections={connections}
+          hosts={hosts}
+          onDisconnect={onDisconnect}
+        />
       )}
       devReset={devReset}
       dataTestId="ai-onboarding"
@@ -143,17 +179,22 @@ export function AiIntegrationOnboarding({
   connections,
   featureKey = DEFAULT_FEATURE_KEY,
   devReset = false,
-  hosts = AI_HOST_GUIDES,
+  platformName,
+  hosts = aiHostGuides(platformName),
   capabilities = AI_CAPABILITIES,
   permissionModel = AI_PERMISSION_MODEL,
-  connectPrompt = AI_CONNECT_PROMPT,
+  connectPrompt,
   onRetest = () => {
     if (typeof window !== "undefined") window.location.reload();
   },
   onDisconnect,
 }: AiIntegrationOnboardingProps): React.JSX.Element {
   return (
-    <OnboardingProvider featureKey={featureKey} store={store} initialState={initialState}>
+    <OnboardingProvider
+      featureKey={featureKey}
+      store={store}
+      initialState={initialState}
+    >
       <AiOnboardingFlow
         endpointUrl={endpointUrl}
         connections={connections}

package/src/react/index.ts

@@ -29,10 +29,11 @@ export { McpEndpointUrl } from "./mcp-endpoint-url";
 export { HostBrandAvatar, CapabilityIcon } from "./ai-icons";
 export { FeatureBadge, type FeatureBadgeItem } from "./feature-badge";
 export {
-  AI_HOST_GUIDES,
+  aiHostGuides,
   AI_CAPABILITIES,
   AI_PERMISSION_MODEL,
-  AI_CONNECT_PROMPT,
+  aiConnectPrompt,
+  type AiConnectPromptSpec,
   providerForHostId,
   type AiHostBrand,
   type AiHostLink,

package/src/server/manifest.ts

@@ -11,7 +11,7 @@ import type { GeneratedTool, ToolManifest } from "../types";
 export interface BuildManifestOptions {
   /** Bumped intentionally on any tool-shape change (mirrors the golden catalog). */
   version: number;
-  /** Human label for the spec, e.g. "future-pay web @ openapi.json". */
+  /** Human label for the spec, e.g. "acme web @ openapi.json". */
   source: string;
 }
 

package/src/server/surface-lock.ts

@@ -16,7 +16,7 @@ import type { GeneratedTool } from "../types";
  * ask again: a tool that shipped stays invisible to every ALREADY CONNECTED
  * client for as long as that connection lives.
  *
- * That is not a hypothetical. In `future-pay` a new tool reached production,
+ * That is not a hypothetical. In the origin host a new tool reached production,
  * answered on its route, and did not appear in a live connector — behind a
  * `serverInfo.version` frozen at its initial value while ~280 tools were added
  * underneath it. Nothing was broken; the only thing asking anyone to bump it was