diff --git a/.changeset/agent-key-bearer.md b/.changeset/agent-key-bearer.md
new file mode 100644
index 00000000..3b720bd7
--- /dev/null
+++ b/.changeset/agent-key-bearer.md
@@ -0,0 +1,5 @@
+---
+"@cloudhal/api": minor
+---
+
+Agent keys are also accepted as `Authorization: Bearer <key>` (what most MCP clients and Codex's `bearer_token_env_var` send), on `/mcp` and wherever `x-api-key` was. `/api/admin/*` keeps its deployment-token bearer and never reads it as an agent key.
diff --git a/apps/studio/src/components/CreateAgentKeyDialog.tsx b/apps/studio/src/components/CreateAgentKeyDialog.tsx
index 1d894ab8..e9927c60 100644
--- a/apps/studio/src/components/CreateAgentKeyDialog.tsx
+++ b/apps/studio/src/components/CreateAgentKeyDialog.tsx
@@ -8,26 +8,23 @@ import {
   Input,
   InsetPanel,
   LayerDialog,
-  Tabs,
   Text,
 } from "@cloudhal/ui";
-import { CodeHighlighted } from "@cloudhal/ui/code";
 import { ArrowCounterClockwise, Info, Warning } from "@phosphor-icons/react";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useEffect, useState } from "react";
 import { listOf, useT } from "../i18n/index.tsx";
 import {
   type GrantableScope,
-  mcpSnippet,
   SCOPE_GROUPS,
   type ScopeGroup,
-  type SnippetKind,
   sameScopes,
   scopeOptions,
 } from "../lib/agents.ts";
 import { api, type CreatedAgentKey, errorCode, type KeyMode } from "../lib/api.ts";
 import { apiErrorText } from "../lib/api-errors.ts";
 import { AutoModeConfirm, BypassHint, ModeBadge, ModePicker } from "./AgentModes.tsx";
+import { McpClientSetup } from "./McpClientSetup.tsx";
 import { useAgentModeRules } from "./useAgentModeRules.ts";
 
 type Step = "mode" | "details";
@@ -61,7 +58,6 @@ export function CreateAgentKeyDialog({
   const [advancedOpen, setAdvancedOpen] = useState(false);
   const [submitted, setSubmitted] = useState(false);
   const [created, setCreated] = useState<CreatedAgentKey | undefined>();
-  const [snippet, setSnippet] = useState<SnippetKind>("json");
 
   const modeScopes = rules.scopesFor(mode);
   const customised = !sameScopes(scopes, modeScopes);
@@ -89,7 +85,6 @@ export function CreateAgentKeyDialog({
       setScopes(rules.scopesFor(rules.defaultMode));
       setAdvancedOpen(false);
       setSubmitted(false);
-      setSnippet("json");
       create.reset();
     } else {
       setCreated(undefined);
@@ -160,30 +155,11 @@ export function CreateAgentKeyDialog({
                   tooltip={{ text: t("common.copy"), copiedText: t("common.copied") }}
                 />
               </div>
-              <div className="grid min-w-0 gap-2">
-                <div className="flex flex-wrap items-center justify-between gap-2">
-                  <Text size="sm" bold as="span">
-                    {t("agents.reveal.config")}
-                  </Text>
-                  <Tabs
-                    variant="segmented"
-                    size="sm"
-                    value={snippet}
-                    onValueChange={(v) => setSnippet(v as SnippetKind)}
-                    tabs={(["json", "claude"] as const).map((k) => ({
-                      value: k,
-                      label: t(`agents.connect.tabs.${k}`),
-                    }))}
-                  />
-                </div>
-                <div className="min-w-0 overflow-x-auto">
-                  <CodeHighlighted
-                    code={mcpSnippet(snippet, endpoint, created.key)}
-                    lang={snippet === "json" ? "json" : "bash"}
-                    showCopyButton
-                  />
-                </div>
-              </div>
+              <McpClientSetup
+                endpoint={endpoint}
+                agentKey={created.key}
+                label={t("agents.reveal.config")}
+              />
             </div>
           ) : step === "mode" ? (
             <div className="grid gap-5" data-testid="create-step-mode">
diff --git a/apps/studio/src/components/McpClientSetup.tsx b/apps/studio/src/components/McpClientSetup.tsx
new file mode 100644
index 00000000..57a6a91f
--- /dev/null
+++ b/apps/studio/src/components/McpClientSetup.tsx
@@ -0,0 +1,48 @@
+import { Select, Text } from "@cloudhal/ui";
+import { CodeHighlighted } from "@cloudhal/ui/code";
+import { useState } from "react";
+import { useT } from "../i18n/index.tsx";
+import { type McpClient, mcpSnippet, REMOTE_CLIENTS, snippetLang } from "../lib/agents.ts";
+
+/**
+ * Ready-to-copy setup for one MCP client at a time (docs/agents/clients.md): a client picker, the
+ * snippet for this deployment's `/mcp`, and where it goes. With `agentKey` (the one-time reveal)
+ * the key is filled in; `local` adds the stdio server for the person's own machine.
+ */
+export function McpClientSetup({
+  endpoint,
+  agentKey,
+  local = false,
+  label,
+}: {
+  endpoint: string;
+  agentKey?: string;
+  local?: boolean;
+  /** The picker's label; "Client" by default. */
+  label?: string;
+}) {
+  const t = useT();
+  const [client, setClient] = useState<McpClient>("claude");
+  const clients: McpClient[] = local ? [...REMOTE_CLIENTS, "stdio"] : [...REMOTE_CLIENTS];
+  return (
+    <div className="grid min-w-0 gap-3" data-testid="mcp-client-setup" data-client={client}>
+      <Select
+        className="w-full"
+        label={label ?? t("agents.connect.client")}
+        value={client}
+        onValueChange={(v) => setClient(v as McpClient)}
+        items={Object.fromEntries(clients.map((c) => [c, t(`agents.connect.clients.${c}`)]))}
+      />
+      <div className="min-w-0 overflow-x-auto">
+        <CodeHighlighted
+          code={mcpSnippet(client, endpoint, agentKey)}
+          lang={snippetLang(client)}
+          showCopyButton
+        />
+      </div>
+      <Text variant="secondary" size="sm">
+        {t(`agents.connect.hints.${client}`)}
+      </Text>
+    </div>
+  );
+}
diff --git a/apps/studio/src/i18n/ar.ts b/apps/studio/src/i18n/ar.ts
index 4f6ab7a4..07a8a218 100644
--- a/apps/studio/src/i18n/ar.ts
+++ b/apps/studio/src/i18n/ar.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): ar core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 586c8d46bd63e844
+// hash: 46a568922c0a4e81
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -930,7 +930,7 @@ export const messages: Messages = {
     },
     reveal: {
       title: "انسخ مفتاحك الجديد",
-      description: "«{name}» جاهز. يرسله وكيلك في الترويسة x-api-key.",
+      description: "«{name}» جاهز. يرسله وكيلك كرمز Bearer أو في الترويسة x-api-key.",
       warningTitle: "لن ترى هذا المفتاح مجددًا",
       warning:
         "احفظه الآن في مدير كلمات المرور لديك أو في مخزن أسرار الوكيل. إذا فُقد، فألغِه وأنشئ مفتاحًا جديدًا.",
@@ -944,13 +944,28 @@ export const messages: Messages = {
         "يصل الوكلاء إلى Studio عبر MCP على هذا العنوان ويرسلون مفتاحهم في ترويسة. عند الاتصال يُبلَّغ الوكيل بوضع مفتاحه، فيعرف ما ينتظرك.",
       endpoint: "نقطة نهاية MCP",
       header: "الترويسة",
-      tabs: {
-        json: "JSON",
+      client: "العميل",
+      clients: {
         claude: "Claude Code",
-        stdio: "محلي",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "عميل آخر",
+        stdio: "محلي (stdio)",
+      },
+      hints: {
+        claude: "شغّله في الطرفية، ثم تحقّق من الاتصال بالأمر ‎/mcp داخل Claude Code.",
+        codex:
+          "يقرأ Codex المفتاح من CLOUDHAL_API_KEY ويرسله كرمز Bearer. أضف سطر export إلى ملف تعريف الصدفة لديك ليكون المفتاح معيّنًا كلما بدأ Codex.",
+        cursor:
+          "الصقه في ‎~/.cursor/mcp.json أو في ‎.cursor/mcp.json داخل مشروع. يحتوي الملف على المفتاح، فأبقِه خارج نظام التحكم في الإصدارات.",
+        vscode:
+          "احفظه باسم ‎.vscode/mcp.json في مشروعك. يطلب VS Code المفتاح مرة واحدة ويحفظه في مخزن الأسرار لديه.",
+        generic:
+          "أي عميل يدعم Streamable HTTP: هذا العنوان، مع المفتاح في الترويسة Authorization كرمز Bearer. تعمل الترويسة x-api-key أيضًا.",
+        stdio:
+          "على جهازك الخاص، شغّل خادم stdio داخل مجلد الموقع؛ لا حاجة إلى مفتاح. يحدّد --mode طريقة عمله، وهنا فقط يمكن أن يكون bypass.",
       },
-      stdioHint:
-        "على جهازك الخاص، شغّل خادم stdio داخل مجلد الموقع؛ لا حاجة إلى مفتاح. يحدّد --mode طريقة عمله، وهنا فقط يمكن أن يكون bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/de.ts b/apps/studio/src/i18n/de.ts
index 2baba968..8df371f3 100644
--- a/apps/studio/src/i18n/de.ts
+++ b/apps/studio/src/i18n/de.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): de core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 8a6fa48d080c8dcb
+// hash: d5dca37f709f1733
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -964,7 +964,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Kopiere deinen neuen Schlüssel",
-      description: "„{name}“ ist bereit. Dein Agent sendet ihn im Header x-api-key.",
+      description:
+        "„{name}“ ist bereit. Dein Agent sendet ihn als Bearer-Token oder im Header x-api-key.",
       warningTitle: "Du wirst diesen Schlüssel nicht wieder sehen",
       warning:
         "Speichere ihn jetzt in deinem Passwortmanager oder im Secret Store des Agents. Geht er verloren, widerrufe ihn und erstelle einen neuen.",
@@ -978,13 +979,29 @@ export const messages: Messages = {
         "Agents erreichen Studio über MCP unter dieser Adresse und senden ihren Schlüssel in einem Header. Beim Verbinden erfährt der Agent den Modus seines Schlüssels und weiß so, was auf dich wartet.",
       endpoint: "MCP-Endpunkt",
       header: "Header",
-      tabs: {
-        json: "JSON",
+      client: "Client",
+      clients: {
         claude: "Claude Code",
-        stdio: "Lokal",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Anderer Client",
+        stdio: "Lokal (stdio)",
+      },
+      hints: {
+        claude:
+          "Führe es in einem Terminal aus und prüfe die Verbindung dann mit /mcp in Claude Code.",
+        codex:
+          "Codex liest den Schlüssel aus CLOUDHAL_API_KEY und sendet ihn als Bearer-Token. Trag die export-Zeile in dein Shell-Profil ein, damit der Schlüssel bei jedem Start von Codex gesetzt ist.",
+        cursor:
+          "Füge es in ~/.cursor/mcp.json ein oder in .cursor/mcp.json in einem Projekt. Die Datei enthält den Schlüssel, halte sie also aus der Versionsverwaltung heraus.",
+        vscode:
+          "Speichere es als .vscode/mcp.json in deinem Projekt. VS Code fragt einmal nach dem Schlüssel und bewahrt ihn in seinem Geheimnisspeicher auf.",
+        generic:
+          "Jeder Client, der Streamable HTTP spricht: diese URL, mit dem Schlüssel als Bearer-Token im Authorization-Header. Der Header x-api-key funktioniert auch.",
+        stdio:
+          "Starte auf deinem eigenen Rechner den stdio-Server im Website-Ordner; kein Schlüssel nötig. --mode legt fest, wie er arbeitet, und nur hier kann er bypass sein.",
       },
-      stdioHint:
-        "Starte auf deinem eigenen Rechner den stdio-Server im Website-Ordner; kein Schlüssel nötig. --mode legt fest, wie er arbeitet, und nur hier kann er bypass sein.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/en.ts b/apps/studio/src/i18n/en.ts
index f39b63b7..8e10e73e 100644
--- a/apps/studio/src/i18n/en.ts
+++ b/apps/studio/src/i18n/en.ts
@@ -899,7 +899,8 @@ export const en = {
     },
     reveal: {
       title: "Copy your new key",
-      description: "“{name}” is ready. Your agent sends it in the x-api-key header.",
+      description:
+        "“{name}” is ready. Your agent sends it as a bearer token or in the x-api-key header.",
       warningTitle: "You won't see this key again",
       warning:
         "Store it now in your password manager or the agent's secret store. If it's lost, revoke it and create a new one.",
@@ -913,9 +914,28 @@ export const en = {
         "Agents reach Studio over MCP at this address and send their key in a header. When it connects, the agent is told its key's mode, so it knows what waits for you.",
       endpoint: "MCP endpoint",
       header: "Header",
-      tabs: { json: "JSON", claude: "Claude Code", stdio: "Local" },
-      stdioHint:
-        "On your own machine, run the stdio server inside the site folder; no key needed. --mode sets how it works, and only here can it be bypass.",
+      client: "Client",
+      clients: {
+        claude: "Claude Code",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Other client",
+        stdio: "Local (stdio)",
+      },
+      hints: {
+        claude: "Run it in a terminal, then check the connection with /mcp inside Claude Code.",
+        codex:
+          "Codex reads the key from CLOUDHAL_API_KEY and sends it as a bearer token. Put the export line in your shell profile so the key is set whenever Codex starts.",
+        cursor:
+          "Paste it into ~/.cursor/mcp.json, or .cursor/mcp.json in a project. The file holds the key, so keep it out of version control.",
+        vscode:
+          "Save it as .vscode/mcp.json in your project. VS Code asks for the key once and keeps it in its secret storage.",
+        generic:
+          "Any client that speaks streamable HTTP: this URL, with the key in the Authorization header as a bearer token. The x-api-key header works too.",
+        stdio:
+          "On your own machine, run the stdio server inside the site folder; no key needed. --mode sets how it works, and only here can it be bypass.",
+      },
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/es.ts b/apps/studio/src/i18n/es.ts
index e447357b..2534f2f5 100644
--- a/apps/studio/src/i18n/es.ts
+++ b/apps/studio/src/i18n/es.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): es core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: b279cd0e5ba1d754
+// hash: d29c27e165ec3375
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -962,7 +962,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Copia tu nueva clave",
-      description: "“{name}” está lista. Tu agente la envía en el encabezado x-api-key.",
+      description:
+        "“{name}” está lista. Tu agente la envía como token bearer o en el encabezado x-api-key.",
       warningTitle: "No volverás a ver esta clave",
       warning:
         "Guárdala ahora en tu gestor de contraseñas o en el almacén de secretos del agente. Si se pierde, revócala y crea una nueva.",
@@ -976,13 +977,28 @@ export const messages: Messages = {
         "Los agentes acceden a Studio por MCP en esta dirección y envían su clave en un encabezado. Al conectarse, se le indica al agente el modo de su clave, para que sepa qué espera por ti.",
       endpoint: "Endpoint MCP",
       header: "Encabezado",
-      tabs: {
-        json: "JSON",
+      client: "Cliente",
+      clients: {
         claude: "Claude Code",
-        stdio: "Local",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Otro cliente",
+        stdio: "Local (stdio)",
+      },
+      hints: {
+        claude: "Ejecútalo en una terminal y comprueba la conexión con /mcp dentro de Claude Code.",
+        codex:
+          "Codex lee la clave de CLOUDHAL_API_KEY y la envía como token bearer. Pon la línea export en el perfil de tu shell para que la clave esté definida cada vez que se inicie Codex.",
+        cursor:
+          "Pégalo en ~/.cursor/mcp.json, o en .cursor/mcp.json dentro de un proyecto. El archivo contiene la clave, así que mantenlo fuera del control de versiones.",
+        vscode:
+          "Guárdalo como .vscode/mcp.json en tu proyecto. VS Code pide la clave una vez y la guarda en su almacenamiento de secretos.",
+        generic:
+          "Cualquier cliente que hable HTTP transmisible: esta URL, con la clave en el encabezado Authorization como token bearer. El encabezado x-api-key también funciona.",
+        stdio:
+          "En tu propio equipo, ejecuta el servidor stdio dentro de la carpeta del sitio; no hace falta clave. --mode define cómo funciona, y solo aquí puede ser bypass.",
       },
-      stdioHint:
-        "En tu propio equipo, ejecuta el servidor stdio dentro de la carpeta del sitio; no hace falta clave. --mode define cómo funciona, y solo aquí puede ser bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/fa.ts b/apps/studio/src/i18n/fa.ts
index 994bfc0a..39b2d870 100644
--- a/apps/studio/src/i18n/fa.ts
+++ b/apps/studio/src/i18n/fa.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): fa core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 090d022080bd43f1
+// hash: cb94d2968657f128
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -944,7 +944,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "کلید جدید خود را کپی کنید",
-      description: "«{name}» آماده است. عامل شما آن را در سرآیند x-api-key می‌فرستد.",
+      description:
+        "«{name}» آماده است. عامل شما آن را به‌صورت توکن Bearer یا در سرآیند x-api-key می‌فرستد.",
       warningTitle: "این کلید را دوباره نخواهید دید",
       warning:
         "همین حالا آن را در مدیر رمز عبور یا انبار اسرار عامل ذخیره کنید. اگر گم شد، آن را باطل کنید و کلید جدیدی بسازید.",
@@ -958,13 +959,28 @@ export const messages: Messages = {
         "عامل‌ها از طریق MCP در این نشانی به Studio می‌رسند و کلید خود را در یک سرآیند می‌فرستند. هنگام اتصال، حالت کلید به عامل گفته می‌شود تا بداند چه چیزی منتظر شما می‌ماند.",
       endpoint: "نقطهٔ پایانی MCP",
       header: "سرآیند",
-      tabs: {
-        json: "JSON",
+      client: "کلاینت",
+      clients: {
         claude: "Claude Code",
-        stdio: "محلی",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "کلاینت دیگر",
+        stdio: "محلی (stdio)",
+      },
+      hints: {
+        claude: "آن را در ترمینال اجرا کنید، سپس اتصال را با ‎/mcp در Claude Code بررسی کنید.",
+        codex:
+          "‏Codex کلید را از CLOUDHAL_API_KEY می‌خواند و به‌صورت توکن Bearer می‌فرستد. خط export را به پروفایل پوستهٔ خود اضافه کنید تا هر بار که Codex شروع می‌شود کلید تنظیم باشد.",
+        cursor:
+          "آن را در ‎~/.cursor/mcp.json یا در ‎.cursor/mcp.json یک پروژه بچسبانید. این فایل کلید را دارد، پس آن را از کنترل نسخه بیرون نگه دارید.",
+        vscode:
+          "آن را با نام ‎.vscode/mcp.json در پروژه‌تان ذخیره کنید. ‏VS Code یک بار کلید را می‌پرسد و در فضای ذخیرهٔ رازهایش نگه می‌دارد.",
+        generic:
+          "هر کلاینتی که Streamable HTTP را پشتیبانی می‌کند: این نشانی، با کلید در سرآیند Authorization به‌صورت توکن Bearer. سرآیند x-api-key هم کار می‌کند.",
+        stdio:
+          "روی دستگاه خودتان، سرور stdio را درون پوشهٔ سایت اجرا کنید؛ کلیدی لازم نیست. --mode نحوهٔ کار آن را تعیین می‌کند و فقط اینجا می‌تواند bypass باشد.",
       },
-      stdioHint:
-        "روی دستگاه خودتان، سرور stdio را درون پوشهٔ سایت اجرا کنید؛ کلیدی لازم نیست. --mode نحوهٔ کار آن را تعیین می‌کند و فقط اینجا می‌تواند bypass باشد.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/fr.ts b/apps/studio/src/i18n/fr.ts
index ee48e6bc..83675aae 100644
--- a/apps/studio/src/i18n/fr.ts
+++ b/apps/studio/src/i18n/fr.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): fr core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 30ea644215e0e3d3
+// hash: fc52ec12db474138
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -974,7 +974,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Copiez votre nouvelle clé",
-      description: "« {name} » est prête. Votre agent l’envoie dans l’en-tête x-api-key.",
+      description:
+        "« {name} » est prête. Votre agent l'envoie comme jeton bearer ou dans l'en-tête x-api-key.",
       warningTitle: "Vous ne reverrez plus cette clé",
       warning:
         "Conservez-la dès maintenant dans votre gestionnaire de mots de passe ou dans le coffre de secrets de l’agent. En cas de perte, révoquez-la et créez-en une nouvelle.",
@@ -988,13 +989,29 @@ export const messages: Messages = {
         "Les agents accèdent à Studio via MCP à cette adresse et envoient leur clé dans un en-tête. À la connexion, l’agent est informé du mode de sa clé et sait donc ce qui vous attend.",
       endpoint: "Point de terminaison MCP",
       header: "En-tête",
-      tabs: {
-        json: "JSON",
+      client: "Client",
+      clients: {
         claude: "Claude Code",
-        stdio: "Local",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Autre client",
+        stdio: "Local (stdio)",
+      },
+      hints: {
+        claude:
+          "Exécutez-la dans un terminal, puis vérifiez la connexion avec /mcp dans Claude Code.",
+        codex:
+          "Codex lit la clé dans CLOUDHAL_API_KEY et l'envoie comme jeton bearer. Ajoutez la ligne export à votre profil de shell pour que la clé soit définie à chaque démarrage de Codex.",
+        cursor:
+          "Collez-le dans ~/.cursor/mcp.json, ou dans .cursor/mcp.json d'un projet. Le fichier contient la clé : gardez-le hors du contrôle de version.",
+        vscode:
+          "Enregistrez-le sous .vscode/mcp.json dans votre projet. VS Code demande la clé une fois et la conserve dans son stockage de secrets.",
+        generic:
+          "Tout client qui parle HTTP streamable : cette URL, avec la clé dans l'en-tête Authorization comme jeton bearer. L'en-tête x-api-key fonctionne aussi.",
+        stdio:
+          "Sur votre propre machine, lancez le serveur stdio dans le dossier du site ; aucune clé n’est nécessaire. --mode définit son fonctionnement, et c’est seulement ici qu’il peut valoir bypass.",
       },
-      stdioHint:
-        "Sur votre propre machine, lancez le serveur stdio dans le dossier du site ; aucune clé n’est nécessaire. --mode définit son fonctionnement, et c’est seulement ici qu’il peut valoir bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/he.ts b/apps/studio/src/i18n/he.ts
index 490ee800..bbe0796e 100644
--- a/apps/studio/src/i18n/he.ts
+++ b/apps/studio/src/i18n/he.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): he core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 1806f4748c6597c1
+// hash: a3fbc3dfc533431e
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -928,7 +928,7 @@ export const messages: Messages = {
     },
     reveal: {
       title: "העתקת המפתח החדש",
-      description: "“{name}” מוכן. הסוכן שולח אותו בכותרת x-api-key.",
+      description: "“{name}” מוכן. הסוכן שולח אותו כאסימון Bearer או בכותרת x-api-key.",
       warningTitle: "המפתח הזה לא יוצג שוב",
       warning:
         "כדאי לשמור אותו עכשיו במנהל הסיסמאות או באחסון הסודות של הסוכן. אם הוא אבד, יש לבטל אותו וליצור חדש.",
@@ -942,13 +942,28 @@ export const messages: Messages = {
         "סוכנים מגיעים ל-Studio דרך MCP בכתובת הזו ושולחים את המפתח שלהם בכותרת. בעת החיבור, הסוכן מקבל את מצב המפתח, כך שהוא יודע מה ממתין לאישור.",
       endpoint: "נקודת קצה של MCP",
       header: "כותרת",
-      tabs: {
-        json: "JSON",
+      client: "לקוח",
+      clients: {
         claude: "Claude Code",
-        stdio: "מקומי",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "לקוח אחר",
+        stdio: "מקומי (stdio)",
+      },
+      hints: {
+        claude: "הריצו בטרמינל, ואז בדקו את החיבור עם ‎/mcp בתוך Claude Code.",
+        codex:
+          "‏Codex קורא את המפתח מ-CLOUDHAL_API_KEY ושולח אותו כאסימון Bearer. הוסיפו את שורת ה-export לפרופיל המעטפת כדי שהמפתח יוגדר בכל הפעלה של Codex.",
+        cursor:
+          "הדביקו ב-‎~/.cursor/mcp.json, או ב-‎.cursor/mcp.json בתוך פרויקט. הקובץ מכיל את המפתח, לכן השאירו אותו מחוץ לבקרת הגרסאות.",
+        vscode:
+          "שמרו בשם ‎.vscode/mcp.json בפרויקט. ‏VS Code מבקש את המפתח פעם אחת ושומר אותו באחסון הסודות שלו.",
+        generic:
+          "כל לקוח שתומך ב-Streamable HTTP: הכתובת הזו, עם המפתח בכותרת Authorization כאסימון Bearer. גם הכותרת x-api-key עובדת.",
+        stdio:
+          "במחשב המקומי, יש להריץ את שרת ה-stdio בתוך תיקיית האתר; לא נדרש מפתח. ‎--mode קובע את אופן העבודה, ורק כאן הוא יכול להיות bypass.",
       },
-      stdioHint:
-        "במחשב המקומי, יש להריץ את שרת ה-stdio בתוך תיקיית האתר; לא נדרש מפתח. ‎--mode קובע את אופן העבודה, ורק כאן הוא יכול להיות bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/hi.ts b/apps/studio/src/i18n/hi.ts
index c21f71be..d9610548 100644
--- a/apps/studio/src/i18n/hi.ts
+++ b/apps/studio/src/i18n/hi.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): hi core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: fade4988bcfe031b
+// hash: 737592cf146bb7a3
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -926,7 +926,7 @@ export const messages: Messages = {
     },
     reveal: {
       title: "अपनी नई कुंजी कॉपी करें",
-      description: "“{name}” तैयार है। आपका एजेंट इसे x-api-key हेडर में भेजता है।",
+      description: "“{name}” तैयार है। आपका एजेंट इसे bearer टोकन के रूप में या x-api-key हेडर में भेजता है।",
       warningTitle: "आप यह कुंजी फिर नहीं देख पाएँगे",
       warning: "इसे अभी अपने पासवर्ड मैनेजर या एजेंट के सीक्रेट स्टोर में सहेजें। खो जाने पर इसे रद्द करें और नई बनाएँ।",
       key: "एजेंट कुंजी",
@@ -939,13 +939,28 @@ export const messages: Messages = {
         "एजेंट इस पते पर MCP के ज़रिए Studio तक पहुँचते हैं और अपनी कुंजी एक हेडर में भेजते हैं। कनेक्ट होने पर एजेंट को उसकी कुंजी का मोड बताया जाता है, ताकि उसे पता रहे कि क्या आपका इंतज़ार करता है।",
       endpoint: "MCP एंडपॉइंट",
       header: "हेडर",
-      tabs: {
-        json: "JSON",
+      client: "क्लाइंट",
+      clients: {
         claude: "Claude Code",
-        stdio: "लोकल",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "दूसरा क्लाइंट",
+        stdio: "लोकल (stdio)",
+      },
+      hints: {
+        claude: "इसे टर्मिनल में चलाएँ, फिर Claude Code में /mcp से कनेक्शन जाँचें।",
+        codex:
+          "Codex कुंजी CLOUDHAL_API_KEY से पढ़ता है और उसे bearer टोकन के रूप में भेजता है। export वाली पंक्ति अपनी शेल प्रोफ़ाइल में जोड़ें ताकि Codex हर बार शुरू होने पर कुंजी सेट रहे।",
+        cursor:
+          "इसे ~/.cursor/mcp.json में, या किसी प्रोजेक्ट की .cursor/mcp.json में चिपकाएँ। फ़ाइल में कुंजी है, इसलिए इसे वर्शन कंट्रोल से बाहर रखें।",
+        vscode:
+          "इसे अपने प्रोजेक्ट में .vscode/mcp.json के रूप में सहेजें। VS Code एक बार कुंजी माँगता है और उसे अपने सीक्रेट स्टोरेज में रखता है।",
+        generic:
+          "streamable HTTP बोलने वाला कोई भी क्लाइंट: यह URL, और Authorization हेडर में bearer टोकन के रूप में कुंजी। x-api-key हेडर भी काम करता है।",
+        stdio:
+          "अपनी मशीन पर, साइट फ़ोल्डर के अंदर stdio सर्वर चलाएँ; कुंजी की ज़रूरत नहीं। --mode तय करता है कि यह कैसे काम करे, और केवल यहीं यह bypass हो सकता है।",
       },
-      stdioHint:
-        "अपनी मशीन पर, साइट फ़ोल्डर के अंदर stdio सर्वर चलाएँ; कुंजी की ज़रूरत नहीं। --mode तय करता है कि यह कैसे काम करे, और केवल यहीं यह bypass हो सकता है।",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/id.ts b/apps/studio/src/i18n/id.ts
index a125022d..fbc7719f 100644
--- a/apps/studio/src/i18n/id.ts
+++ b/apps/studio/src/i18n/id.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): id core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: d2f9677c3a8222ad
+// hash: dff29bcb0c59552a
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -956,7 +956,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Salin kunci baru Anda",
-      description: "“{name}” sudah siap. Agen Anda mengirimkannya di header x-api-key.",
+      description:
+        "“{name}” sudah siap. Agen Anda mengirimkannya sebagai token bearer atau di header x-api-key.",
       warningTitle: "Anda tidak akan melihat kunci ini lagi",
       warning:
         "Simpan sekarang di pengelola kata sandi Anda atau penyimpanan rahasia agen. Jika hilang, cabut lalu buat yang baru.",
@@ -970,13 +971,28 @@ export const messages: Messages = {
         "Agen menjangkau Studio melalui MCP di alamat ini dan mengirim kuncinya di header. Saat terhubung, agen diberi tahu mode kuncinya, sehingga tahu apa yang menunggu Anda.",
       endpoint: "Endpoint MCP",
       header: "Header",
-      tabs: {
-        json: "JSON",
+      client: "Klien",
+      clients: {
         claude: "Claude Code",
-        stdio: "Lokal",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Klien lain",
+        stdio: "Lokal (stdio)",
+      },
+      hints: {
+        claude: "Jalankan di terminal, lalu periksa koneksinya dengan /mcp di Claude Code.",
+        codex:
+          "Codex membaca kunci dari CLOUDHAL_API_KEY dan mengirimkannya sebagai token bearer. Tambahkan baris export ke profil shell Anda agar kunci selalu tersedia saat Codex dimulai.",
+        cursor:
+          "Tempelkan ke ~/.cursor/mcp.json, atau .cursor/mcp.json di sebuah proyek. Berkas ini berisi kunci, jadi jangan masukkan ke kontrol versi.",
+        vscode:
+          "Simpan sebagai .vscode/mcp.json di proyek Anda. VS Code meminta kunci sekali dan menyimpannya di penyimpanan rahasianya.",
+        generic:
+          "Klien apa pun yang mendukung streamable HTTP: URL ini, dengan kunci di header Authorization sebagai token bearer. Header x-api-key juga bisa.",
+        stdio:
+          "Di mesin Anda sendiri, jalankan server stdio di dalam folder situs; tidak perlu kunci. --mode menentukan cara kerjanya, dan hanya di sini mode bisa bypass.",
       },
-      stdioHint:
-        "Di mesin Anda sendiri, jalankan server stdio di dalam folder situs; tidak perlu kunci. --mode menentukan cara kerjanya, dan hanya di sini mode bisa bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/it.ts b/apps/studio/src/i18n/it.ts
index 0611fa73..269ca17d 100644
--- a/apps/studio/src/i18n/it.ts
+++ b/apps/studio/src/i18n/it.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): it core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 5b7a60035eb6f4d8
+// hash: 86b834295ccf9ee0
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -958,7 +958,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Copia la tua nuova chiave",
-      description: "“{name}” è pronta. Il tuo agente la invia nell’header x-api-key.",
+      description:
+        "“{name}” è pronta. Il tuo agente la invia come token bearer o nell'header x-api-key.",
       warningTitle: "Non vedrai più questa chiave",
       warning:
         "Salvala ora nel tuo password manager o nell’archivio dei segreti dell’agente. Se la perdi, revocala e creane una nuova.",
@@ -972,13 +973,28 @@ export const messages: Messages = {
         "Gli agenti raggiungono Studio via MCP a questo indirizzo e inviano la loro chiave in un header. Quando si collega, all’agente viene comunicata la modalità della chiave, così sa cosa aspetta te.",
       endpoint: "Endpoint MCP",
       header: "Header",
-      tabs: {
-        json: "JSON",
+      client: "Client",
+      clients: {
         claude: "Claude Code",
-        stdio: "Locale",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Altro client",
+        stdio: "Locale (stdio)",
+      },
+      hints: {
+        claude: "Eseguilo in un terminale, poi verifica la connessione con /mcp in Claude Code.",
+        codex:
+          "Codex legge la chiave da CLOUDHAL_API_KEY e la invia come token bearer. Metti la riga export nel profilo della tua shell, così la chiave è impostata ogni volta che Codex si avvia.",
+        cursor:
+          "Incollalo in ~/.cursor/mcp.json, oppure in .cursor/mcp.json in un progetto. Il file contiene la chiave: tienilo fuori dal controllo di versione.",
+        vscode:
+          "Salvalo come .vscode/mcp.json nel tuo progetto. VS Code chiede la chiave una volta e la conserva nel suo archivio segreto.",
+        generic:
+          "Qualsiasi client che parli HTTP streamable: questo URL, con la chiave nell'header Authorization come token bearer. Funziona anche l'header x-api-key.",
+        stdio:
+          "Sulla tua macchina, esegui il server stdio dentro la cartella del sito; nessuna chiave necessaria. --mode imposta come funziona, e solo qui può essere bypass.",
       },
-      stdioHint:
-        "Sulla tua macchina, esegui il server stdio dentro la cartella del sito; nessuna chiave necessaria. --mode imposta come funziona, e solo qui può essere bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/ja.ts b/apps/studio/src/i18n/ja.ts
index 7d227ab4..8b53aee3 100644
--- a/apps/studio/src/i18n/ja.ts
+++ b/apps/studio/src/i18n/ja.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): ja core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 30de2a7a9b1d4ea3
+// hash: 957c688122ebaca0
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -951,7 +951,7 @@ export const messages: Messages = {
     reveal: {
       title: "新しいキーをコピー",
       description:
-        "「{name}」の準備ができました。エージェントはこれをx-api-keyヘッダーで送信します。",
+        "「{name}」の準備ができました。エージェントはこのキーを Bearer トークンとして、または x-api-key ヘッダーで送信します。",
       warningTitle: "このキーは二度と表示されません",
       warning:
         "今すぐパスワードマネージャーやエージェントのシークレットストアに保存してください。紛失した場合は、取り消して新しいキーを作成してください。",
@@ -965,13 +965,28 @@ export const messages: Messages = {
         "エージェントはこのアドレスでMCP経由でStudioに接続し、キーをヘッダーで送信します。接続するとエージェントにキーのモードが伝えられるため、何があなたの判断を待つのかを把握できます。",
       endpoint: "MCPエンドポイント",
       header: "ヘッダー",
-      tabs: {
-        json: "JSON",
+      client: "クライアント",
+      clients: {
         claude: "Claude Code",
-        stdio: "ローカル",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "その他のクライアント",
+        stdio: "ローカル (stdio)",
+      },
+      hints: {
+        claude: "ターミナルで実行し、Claude Code 内の /mcp で接続を確認します。",
+        codex:
+          "Codex は CLOUDHAL_API_KEY からキーを読み取り、Bearer トークンとして送信します。Codex の起動時に毎回キーが設定されるよう、export 行をシェルのプロファイルに追加してください。",
+        cursor:
+          "~/.cursor/mcp.json、またはプロジェクトの .cursor/mcp.json に貼り付けます。ファイルにキーが含まれるため、バージョン管理に含めないでください。",
+        vscode:
+          "プロジェクトに .vscode/mcp.json として保存します。VS Code はキーを一度だけ尋ね、シークレットストレージに保管します。",
+        generic:
+          "Streamable HTTP に対応したクライアント: この URL を使い、キーを Bearer トークンとして Authorization ヘッダーで送ります。x-api-key ヘッダーも使えます。",
+        stdio:
+          "お使いのマシンでは、サイトのフォルダー内でstdioサーバーを実行します。キーは不要です。--modeで動作方法を設定でき、bypassにできるのはここだけです。",
       },
-      stdioHint:
-        "お使いのマシンでは、サイトのフォルダー内でstdioサーバーを実行します。キーは不要です。--modeで動作方法を設定でき、bypassにできるのはここだけです。",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/ko.ts b/apps/studio/src/i18n/ko.ts
index c40f63cf..0b9800b5 100644
--- a/apps/studio/src/i18n/ko.ts
+++ b/apps/studio/src/i18n/ko.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): ko core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: b1e4ce942e6ee0af
+// hash: bfe3acc7ecbda94b
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -926,7 +926,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "새 키 복사",
-      description: "“{name}”이(가) 준비됐어요. 에이전트는 x-api-key 헤더로 키를 보내요.",
+      description:
+        "“{name}” 키가 준비되었습니다. 에이전트는 이 키를 Bearer 토큰 또는 x-api-key 헤더로 보냅니다.",
       warningTitle: "이 키는 다시 볼 수 없어요",
       warning:
         "지금 비밀번호 관리자나 에이전트의 시크릿 저장소에 보관하세요. 잃어버리면 폐기하고 새로 만드세요.",
@@ -940,13 +941,28 @@ export const messages: Messages = {
         "에이전트는 이 주소의 MCP로 Studio에 접근하고 헤더로 키를 보내요. 연결되면 에이전트에게 키의 모드가 전달되어 무엇이 내 승인을 기다리는지 알게 돼요.",
       endpoint: "MCP 엔드포인트",
       header: "헤더",
-      tabs: {
-        json: "JSON",
+      client: "클라이언트",
+      clients: {
         claude: "Claude Code",
-        stdio: "로컬",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "다른 클라이언트",
+        stdio: "로컬 (stdio)",
+      },
+      hints: {
+        claude: "터미널에서 실행한 다음 Claude Code에서 /mcp로 연결을 확인하세요.",
+        codex:
+          "Codex는 CLOUDHAL_API_KEY에서 키를 읽어 Bearer 토큰으로 보냅니다. Codex가 시작될 때마다 키가 설정되도록 export 줄을 셸 프로필에 넣으세요.",
+        cursor:
+          "~/.cursor/mcp.json 또는 프로젝트의 .cursor/mcp.json에 붙여 넣으세요. 파일에 키가 들어 있으므로 버전 관리에서 제외하세요.",
+        vscode:
+          "프로젝트에 .vscode/mcp.json으로 저장하세요. VS Code가 키를 한 번 묻고 보안 저장소에 보관합니다.",
+        generic:
+          "Streamable HTTP를 지원하는 모든 클라이언트: 이 URL과 Authorization 헤더의 Bearer 토큰으로 키를 사용합니다. x-api-key 헤더도 작동합니다.",
+        stdio:
+          "내 컴퓨터에서는 사이트 폴더 안에서 stdio 서버를 실행하세요. 키는 필요 없어요. --mode로 작동 방식을 정하며, 여기에서만 bypass를 쓸 수 있어요.",
       },
-      stdioHint:
-        "내 컴퓨터에서는 사이트 폴더 안에서 stdio 서버를 실행하세요. 키는 필요 없어요. --mode로 작동 방식을 정하며, 여기에서만 bypass를 쓸 수 있어요.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/nl.ts b/apps/studio/src/i18n/nl.ts
index b04a1cca..ce13936a 100644
--- a/apps/studio/src/i18n/nl.ts
+++ b/apps/studio/src/i18n/nl.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): nl core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 8be96f549bf56662
+// hash: d697fbb570059445
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -958,7 +958,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Kopieer je nieuwe sleutel",
-      description: "“{name}” is klaar. Je agent stuurt hem mee in de header x-api-key.",
+      description:
+        "“{name}” is klaar. Je agent stuurt hem als bearer-token of in de header x-api-key.",
       warningTitle: "Je ziet deze sleutel niet nog eens",
       warning:
         "Bewaar hem nu in je wachtwoordmanager of in de geheimenopslag van de agent. Ben je hem kwijt, trek hem dan in en maak een nieuwe.",
@@ -972,13 +973,29 @@ export const messages: Messages = {
         "Agents bereiken Studio via MCP op dit adres en sturen hun sleutel mee in een header. Bij het verbinden krijgt de agent de modus van zijn sleutel te horen, zodat hij weet wat op jou wacht.",
       endpoint: "MCP-endpoint",
       header: "Header",
-      tabs: {
-        json: "JSON",
+      client: "Client",
+      clients: {
         claude: "Claude Code",
-        stdio: "Lokaal",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Andere client",
+        stdio: "Lokaal (stdio)",
+      },
+      hints: {
+        claude:
+          "Voer het uit in een terminal en controleer daarna de verbinding met /mcp in Claude Code.",
+        codex:
+          "Codex leest de sleutel uit CLOUDHAL_API_KEY en stuurt hem als bearer-token. Zet de export-regel in je shellprofiel, zodat de sleutel bij elke start van Codex is ingesteld.",
+        cursor:
+          "Plak het in ~/.cursor/mcp.json, of in .cursor/mcp.json in een project. Het bestand bevat de sleutel, dus houd het buiten versiebeheer.",
+        vscode:
+          "Sla het op als .vscode/mcp.json in je project. VS Code vraagt één keer om de sleutel en bewaart hem in de geheime opslag.",
+        generic:
+          "Elke client die streamable HTTP spreekt: deze URL, met de sleutel als bearer-token in de Authorization-header. De header x-api-key werkt ook.",
+        stdio:
+          "Op je eigen machine draai je de stdio-server in de sitemap; geen sleutel nodig. --mode bepaalt hoe hij werkt, en alleen hier kan dat bypass zijn.",
       },
-      stdioHint:
-        "Op je eigen machine draai je de stdio-server in de sitemap; geen sleutel nodig. --mode bepaalt hoe hij werkt, en alleen hier kan dat bypass zijn.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/pl.ts b/apps/studio/src/i18n/pl.ts
index 892c6271..ed78ddc4 100644
--- a/apps/studio/src/i18n/pl.ts
+++ b/apps/studio/src/i18n/pl.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): pl core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 4e2f6e3f2cddb1f5
+// hash: f3746cd7722de2ac
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -945,7 +945,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Skopiuj nowy klucz",
-      description: "„{name}” jest gotowy. Agent wysyła go w nagłówku x-api-key.",
+      description:
+        "„{name}” jest gotowy. Twój agent wysyła go jako token bearer lub w nagłówku x-api-key.",
       warningTitle: "Nie zobaczysz już tego klucza",
       warning:
         "Zapisz go teraz w menedżerze haseł lub magazynie sekretów agenta. Jeśli go zgubisz, unieważnij go i utwórz nowy.",
@@ -959,13 +960,28 @@ export const messages: Messages = {
         "Agenci łączą się ze Studio przez MCP pod tym adresem i wysyłają klucz w nagłówku. Po połączeniu agent poznaje tryb swojego klucza, więc wie, co czeka na ciebie.",
       endpoint: "Punkt końcowy MCP",
       header: "Nagłówek",
-      tabs: {
-        json: "JSON",
+      client: "Klient",
+      clients: {
         claude: "Claude Code",
-        stdio: "Lokalnie",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Inny klient",
+        stdio: "Lokalnie (stdio)",
+      },
+      hints: {
+        claude: "Uruchom to w terminalu, a potem sprawdź połączenie poleceniem /mcp w Claude Code.",
+        codex:
+          "Codex odczytuje klucz z CLOUDHAL_API_KEY i wysyła go jako token bearer. Dodaj wiersz export do profilu powłoki, aby klucz był ustawiony przy każdym uruchomieniu Codex.",
+        cursor:
+          "Wklej to do ~/.cursor/mcp.json albo do .cursor/mcp.json w projekcie. Plik zawiera klucz, więc nie dodawaj go do systemu kontroli wersji.",
+        vscode:
+          "Zapisz to jako .vscode/mcp.json w projekcie. VS Code raz poprosi o klucz i przechowa go w swoim magazynie sekretów.",
+        generic:
+          "Dowolny klient obsługujący streamable HTTP: ten URL, z kluczem w nagłówku Authorization jako token bearer. Nagłówek x-api-key też działa.",
+        stdio:
+          "Na własnym komputerze uruchom serwer stdio w folderze witryny; klucz nie jest potrzebny. --mode ustawia sposób działania i tylko tutaj może to być bypass.",
       },
-      stdioHint:
-        "Na własnym komputerze uruchom serwer stdio w folderze witryny; klucz nie jest potrzebny. --mode ustawia sposób działania i tylko tutaj może to być bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/pt-BR.ts b/apps/studio/src/i18n/pt-BR.ts
index eee417f5..5130260c 100644
--- a/apps/studio/src/i18n/pt-BR.ts
+++ b/apps/studio/src/i18n/pt-BR.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): pt-BR core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 74a4e5832d3dfe6a
+// hash: ea5c4aa9b29fe750
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -950,7 +950,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Copie sua nova chave",
-      description: "“{name}” está pronta. Seu agente a envia no cabeçalho x-api-key.",
+      description:
+        "“{name}” está pronta. Seu agente a envia como token bearer ou no cabeçalho x-api-key.",
       warningTitle: "Você não verá esta chave de novo",
       warning:
         "Guarde-a agora no seu gerenciador de senhas ou no cofre de segredos do agente. Se ela se perder, revogue-a e crie uma nova.",
@@ -964,13 +965,28 @@ export const messages: Messages = {
         "Os agentes acessam o Studio via MCP neste endereço e enviam a chave em um cabeçalho. Ao se conectar, o agente é informado do modo da chave, então sabe o que aguarda você.",
       endpoint: "Endpoint MCP",
       header: "Cabeçalho",
-      tabs: {
-        json: "JSON",
+      client: "Cliente",
+      clients: {
         claude: "Claude Code",
-        stdio: "Local",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Outro cliente",
+        stdio: "Local (stdio)",
+      },
+      hints: {
+        claude: "Execute em um terminal e depois verifique a conexão com /mcp no Claude Code.",
+        codex:
+          "O Codex lê a chave de CLOUDHAL_API_KEY e a envia como token bearer. Coloque a linha export no perfil do seu shell para que a chave esteja definida sempre que o Codex iniciar.",
+        cursor:
+          "Cole em ~/.cursor/mcp.json, ou em .cursor/mcp.json em um projeto. O arquivo contém a chave, então mantenha-o fora do controle de versão.",
+        vscode:
+          "Salve como .vscode/mcp.json no seu projeto. O VS Code pede a chave uma vez e a guarda no armazenamento de segredos.",
+        generic:
+          "Qualquer cliente que fale HTTP streamable: esta URL, com a chave no cabeçalho Authorization como token bearer. O cabeçalho x-api-key também funciona.",
+        stdio:
+          "Na sua própria máquina, rode o servidor stdio dentro da pasta do site; não precisa de chave. --mode define como ele trabalha, e só aqui pode ser bypass.",
       },
-      stdioHint:
-        "Na sua própria máquina, rode o servidor stdio dentro da pasta do site; não precisa de chave. --mode define como ele trabalha, e só aqui pode ser bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/ru.ts b/apps/studio/src/i18n/ru.ts
index 4bed824c..fe5cc146 100644
--- a/apps/studio/src/i18n/ru.ts
+++ b/apps/studio/src/i18n/ru.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): ru core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: a973027c41496944
+// hash: 8f3c67fcb371fe34
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -961,7 +961,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Скопируйте новый ключ",
-      description: "«{name}» готов. Ваш агент передаёт его в заголовке x-api-key.",
+      description:
+        "«{name}» готов. Ваш агент отправляет его как bearer-токен или в заголовке x-api-key.",
       warningTitle: "Вы больше не увидите этот ключ",
       warning:
         "Сохраните его сейчас в менеджере паролей или хранилище секретов агента. Если ключ потерян, отзовите его и создайте новый.",
@@ -975,13 +976,29 @@ export const messages: Messages = {
         "Агенты подключаются к Studio по MCP по этому адресу и передают ключ в заголовке. При подключении агенту сообщается режим его ключа, чтобы он знал, что ждёт вас.",
       endpoint: "Эндпоинт MCP",
       header: "Заголовок",
-      tabs: {
-        json: "JSON",
+      client: "Клиент",
+      clients: {
         claude: "Claude Code",
-        stdio: "Локально",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Другой клиент",
+        stdio: "Локально (stdio)",
+      },
+      hints: {
+        claude:
+          "Выполните это в терминале, затем проверьте подключение командой /mcp в Claude Code.",
+        codex:
+          "Codex берёт ключ из CLOUDHAL_API_KEY и отправляет его как bearer-токен. Добавьте строку export в профиль оболочки, чтобы ключ был задан при каждом запуске Codex.",
+        cursor:
+          "Вставьте это в ~/.cursor/mcp.json или в .cursor/mcp.json проекта. Файл содержит ключ, поэтому не добавляйте его в систему контроля версий.",
+        vscode:
+          "Сохраните это как .vscode/mcp.json в проекте. VS Code один раз запросит ключ и сохранит его в своём хранилище секретов.",
+        generic:
+          "Любой клиент с поддержкой streamable HTTP: этот URL и ключ в заголовке Authorization как bearer-токен. Заголовок x-api-key тоже работает.",
+        stdio:
+          "На своём компьютере запустите stdio-сервер в папке сайта; ключ не нужен. --mode задаёт режим работы, и только здесь он может быть bypass.",
       },
-      stdioHint:
-        "На своём компьютере запустите stdio-сервер в папке сайта; ключ не нужен. --mode задаёт режим работы, и только здесь он может быть bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/tr.ts b/apps/studio/src/i18n/tr.ts
index 3248d19c..5dd30b7f 100644
--- a/apps/studio/src/i18n/tr.ts
+++ b/apps/studio/src/i18n/tr.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): tr core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 9bc83d36add9c08f
+// hash: a4c27f8e742ff095
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -944,7 +944,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Yeni anahtarını kopyala",
-      description: "“{name}” hazır. Agent'ın bu anahtarı x-api-key başlığında gönderir.",
+      description:
+        "“{name}” hazır. Agent'ın bu anahtarı bearer token olarak ya da x-api-key başlığında gönderir.",
       warningTitle: "Bu anahtarı bir daha göremeyeceksin",
       warning:
         "Şimdi parola yöneticine ya da agent'ın gizli anahtar deposuna kaydet. Kaybedersen iptal edip yenisini oluştur.",
@@ -958,13 +959,28 @@ export const messages: Messages = {
         "Agent'lar Studio'ya bu adresteki MCP üzerinden ulaşır ve anahtarlarını bir başlıkta gönderir. Bağlandığında agent'a anahtarının modu bildirilir; böylece neyin senin onayını bekleyeceğini bilir.",
       endpoint: "MCP adresi",
       header: "Başlık",
-      tabs: {
-        json: "JSON",
+      client: "İstemci",
+      clients: {
         claude: "Claude Code",
-        stdio: "Yerel",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Diğer istemci",
+        stdio: "Yerel (stdio)",
+      },
+      hints: {
+        claude: "Bir terminalde çalıştır, sonra bağlantıyı Claude Code içinde /mcp ile kontrol et.",
+        codex:
+          "Codex anahtarı CLOUDHAL_API_KEY değişkeninden okur ve bearer token olarak gönderir. export satırını kabuk profiline ekle ki Codex her başladığında anahtar tanımlı olsun.",
+        cursor:
+          "~/.cursor/mcp.json dosyasına ya da bir projede .cursor/mcp.json dosyasına yapıştır. Dosya anahtarı içerir; sürüm kontrolünün dışında tut.",
+        vscode:
+          "Projende .vscode/mcp.json olarak kaydet. VS Code anahtarı bir kez sorar ve gizli deposunda saklar.",
+        generic:
+          "Streamable HTTP konuşan her istemci: bu URL ve Authorization başlığında bearer token olarak anahtar. x-api-key başlığı da çalışır.",
+        stdio:
+          "Kendi bilgisayarında stdio sunucusunu site klasörünün içinde çalıştır; anahtar gerekmez. --mode nasıl çalışacağını belirler; bypass yalnızca burada mümkündür.",
       },
-      stdioHint:
-        "Kendi bilgisayarında stdio sunucusunu site klasörünün içinde çalıştır; anahtar gerekmez. --mode nasıl çalışacağını belirler; bypass yalnızca burada mümkündür.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/uk.ts b/apps/studio/src/i18n/uk.ts
index 704bf7a6..28975935 100644
--- a/apps/studio/src/i18n/uk.ts
+++ b/apps/studio/src/i18n/uk.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): uk core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: 0c806ebbb11d1657
+// hash: cca2e874252f6006
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -953,7 +953,8 @@ export const messages: Messages = {
     },
     reveal: {
       title: "Скопіюйте новий ключ",
-      description: "«{name}» готовий. Ваш агент надсилає його в заголовку x-api-key.",
+      description:
+        "«{name}» готовий. Ваш агент надсилає його як bearer-токен або в заголовку x-api-key.",
       warningTitle: "Ви більше не побачите цей ключ",
       warning:
         "Збережіть його зараз у менеджері паролів або в сховищі секретів агента. Якщо його буде втрачено, відкличте його й створіть новий.",
@@ -967,13 +968,28 @@ export const messages: Messages = {
         "Агенти звертаються до Studio через MCP за цією адресою й надсилають свій ключ у заголовку. Під час під’єднання агент дізнається режим свого ключа, тож знає, що чекає на вас.",
       endpoint: "Кінцева точка MCP",
       header: "Заголовок",
-      tabs: {
-        json: "JSON",
+      client: "Клієнт",
+      clients: {
         claude: "Claude Code",
-        stdio: "Локально",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "Інший клієнт",
+        stdio: "Локально (stdio)",
+      },
+      hints: {
+        claude: "Виконайте це в терміналі, потім перевірте з’єднання командою /mcp у Claude Code.",
+        codex:
+          "Codex бере ключ із CLOUDHAL_API_KEY і надсилає його як bearer-токен. Додайте рядок export до профілю оболонки, щоб ключ був заданий під час кожного запуску Codex.",
+        cursor:
+          "Вставте це в ~/.cursor/mcp.json або в .cursor/mcp.json проєкту. Файл містить ключ, тож не додавайте його до системи контролю версій.",
+        vscode:
+          "Збережіть це як .vscode/mcp.json у проєкті. VS Code один раз попросить ключ і збереже його у своєму сховищі секретів.",
+        generic:
+          "Будь-який клієнт із підтримкою streamable HTTP: ця URL-адреса і ключ у заголовку Authorization як bearer-токен. Заголовок x-api-key теж працює.",
+        stdio:
+          "На власному комп’ютері запустіть сервер stdio у папці сайту; ключ не потрібен. --mode задає режим роботи, і лише тут він може бути bypass.",
       },
-      stdioHint:
-        "На власному комп’ютері запустіть сервер stdio у папці сайту; ключ не потрібен. --mode задає режим роботи, і лише тут він може бути bypass.",
     },
   },
   activity: {
diff --git a/apps/studio/src/i18n/zh-Hans.ts b/apps/studio/src/i18n/zh-Hans.ts
index 379bf7b3..4de0ec5a 100644
--- a/apps/studio/src/i18n/zh-Hans.ts
+++ b/apps/studio/src/i18n/zh-Hans.ts
@@ -1,6 +1,6 @@
 // Generated by `pnpm i18n:import` (ADR-0034): zh-Hans core messages.
 // Do not edit: change the translation file and import it; only English is edited here.
-// hash: b8ca4c457ba0bf27
+// hash: 472b7197a3624bca
 import type { Messages } from "./en.ts";
 
 export const messages: Messages = {
@@ -903,7 +903,7 @@ export const messages: Messages = {
     },
     reveal: {
       title: "复制你的新密钥",
-      description: "“{name}”已就绪。你的智能体通过 x-api-key 请求头发送它。",
+      description: "“{name}”已就绪。你的智能体以 Bearer 令牌或 x-api-key 请求头发送它。",
       warningTitle: "你将无法再次看到此密钥",
       warning: "请立即将它保存在你的密码管理器或智能体的密钥存储中。如果丢失，请吊销并创建新密钥。",
       key: "智能体密钥",
@@ -916,13 +916,28 @@ export const messages: Messages = {
         "智能体通过此地址以 MCP 访问 Studio，并在请求头中发送密钥。连接时，智能体会得知其密钥的模式，从而知道哪些需要等你处理。",
       endpoint: "MCP 端点",
       header: "请求头",
-      tabs: {
-        json: "JSON",
+      client: "客户端",
+      clients: {
         claude: "Claude Code",
-        stdio: "本地",
+        codex: "Codex",
+        cursor: "Cursor",
+        vscode: "VS Code",
+        generic: "其他客户端",
+        stdio: "本地 (stdio)",
+      },
+      hints: {
+        claude: "在终端中运行，然后在 Claude Code 中用 /mcp 检查连接。",
+        codex:
+          "Codex 从 CLOUDHAL_API_KEY 读取密钥，并以 Bearer 令牌发送。把 export 这一行加入 shell 配置文件，这样每次启动 Codex 时密钥都已设置。",
+        cursor:
+          "粘贴到 ~/.cursor/mcp.json，或项目中的 .cursor/mcp.json。该文件包含密钥，请不要纳入版本控制。",
+        vscode:
+          "在项目中保存为 .vscode/mcp.json。VS Code 只会询问一次密钥，并将其保存在其密钥存储中。",
+        generic:
+          "任何支持 Streamable HTTP 的客户端：使用此 URL，并在 Authorization 请求头中以 Bearer 令牌发送密钥。x-api-key 请求头同样可用。",
+        stdio:
+          "在你自己的机器上，于站点文件夹中运行 stdio 服务器；无需密钥。--mode 设置其工作方式，且只有在这里才能使用 bypass。",
       },
-      stdioHint:
-        "在你自己的机器上，于站点文件夹中运行 stdio 服务器；无需密钥。--mode 设置其工作方式，且只有在这里才能使用 bypass。",
     },
   },
   activity: {
diff --git a/apps/studio/src/lib/agents.ts b/apps/studio/src/lib/agents.ts
index 0950c57d..9464ad64 100644
--- a/apps/studio/src/lib/agents.ts
+++ b/apps/studio/src/lib/agents.ts
@@ -323,24 +323,66 @@ export function sortScopes(scopes: readonly AgentScope[]): AgentScope[] {
  */
 export const ALWAYS_GATED_TOOLS = ["rollback", "delete_page", "delete_entry"] as const;
 
-export type SnippetKind = "json" | "claude" | "stdio";
-
-/** Client configuration for this Studio's MCP endpoint; `key` fills in a freshly created key. */
-export function mcpSnippet(kind: SnippetKind, endpoint: string, key?: string): string {
-  const secret = key ?? "<your agent key>";
-  if (kind === "json") {
-    return JSON.stringify(
-      {
-        mcpServers: {
-          cloudhal: { type: "http", url: endpoint, headers: { "x-api-key": secret } },
+/**
+ * MCP clients Studio shows setup for (docs/agents/clients.md); `stdio` is the local server. Every
+ * remote snippet sends the key as `Authorization: Bearer` (the server also takes `x-api-key`).
+ */
+export const REMOTE_CLIENTS = ["claude", "codex", "cursor", "vscode", "generic"] as const;
+export type McpClient = (typeof REMOTE_CLIENTS)[number] | "stdio";
+
+/** The environment variable the snippets read the key from where a client takes one. */
+const KEY_ENV = "CLOUDHAL_API_KEY";
+
+const json = (value: unknown) => JSON.stringify(value, null, 2);
+
+/** Setup per client, in the formats of docs/agents/clients.md; `key` fills in a fresh key. */
+const SNIPPETS: Record<McpClient, (endpoint: string, key: string) => string> = {
+  claude: (endpoint, key) =>
+    `claude mcp add --transport http cloudhal ${endpoint} \\\n  --header "Authorization: Bearer ${key}"`,
+  // Codex reads the key from the environment and sends it as `Authorization: Bearer`.
+  codex: (endpoint, key) =>
+    `export ${KEY_ENV}="${key}"\ncodex mcp add cloudhal --url ${endpoint} \\\n  --bearer-token-env-var ${KEY_ENV}`,
+  cursor: (endpoint, key) =>
+    json({
+      mcpServers: { cloudhal: { url: endpoint, headers: { Authorization: `Bearer ${key}` } } },
+    }),
+  // VS Code asks for the key once and keeps it in its secret storage, so the file holds none.
+  vscode: (endpoint) =>
+    json({
+      inputs: [
+        {
+          type: "promptString",
+          id: "cloudhal-key",
+          // i18n-ignore: written into the person's .vscode/mcp.json, as in docs/agents/clients.md
+          description: "Cloudhal agent key",
+          password: true,
+        },
+      ],
+      servers: {
+        cloudhal: {
+          type: "http",
+          url: endpoint,
+          // biome-ignore lint/suspicious/noTemplateCurlyInString: VS Code's own input variable
+          headers: { Authorization: "Bearer ${input:cloudhal-key}" },
         },
       },
-      null,
-      2,
-    );
-  }
-  if (kind === "claude") {
-    return `claude mcp add --transport http cloudhal ${endpoint} \\\n  --header "x-api-key: ${secret}"`;
-  }
-  return "# Run inside the site project; no key needed on your own machine\ncd my-site\nclaude mcp add cloudhal -- npx cloudhal mcp --mode edits";
+    }),
+  generic: (endpoint, key) =>
+    json({
+      mcpServers: {
+        cloudhal: { type: "http", url: endpoint, headers: { Authorization: `Bearer ${key}` } },
+      },
+    }),
+  stdio: () =>
+    "# Run inside the site project; no key needed on your own machine\ncd my-site\nclaude mcp add cloudhal -- npx cloudhal mcp --mode edits",
+};
+
+/** Client configuration for this Studio's MCP endpoint; `key` fills in a freshly created key. */
+export function mcpSnippet(client: McpClient, endpoint: string, key?: string): string {
+  return SNIPPETS[client](endpoint, key ?? "<your agent key>");
+}
+
+/** The highlighter language of a client's snippet. */
+export function snippetLang(client: McpClient): "json" | "bash" {
+  return client === "cursor" || client === "vscode" || client === "generic" ? "json" : "bash";
 }
diff --git a/apps/studio/src/routes/AgentsPage.tsx b/apps/studio/src/routes/AgentsPage.tsx
index 914aacb1..7075a3d9 100644
--- a/apps/studio/src/routes/AgentsPage.tsx
+++ b/apps/studio/src/routes/AgentsPage.tsx
@@ -14,11 +14,9 @@ import {
   SectionCard,
   SectionEmpty,
   Table,
-  Tabs,
   Text,
   Tooltip,
 } from "@cloudhal/ui";
-import { CodeHighlighted } from "@cloudhal/ui/code";
 import {
   ArrowsInSimple,
   ClockCountdown,
@@ -53,6 +51,7 @@ import {
 } from "../components/Elevation.tsx";
 import { ErrorBanner } from "../components/ErrorBanner.tsx";
 import { ListToolbar } from "../components/ListToolbar.tsx";
+import { McpClientSetup } from "../components/McpClientSetup.tsx";
 import { RelativeTime } from "../components/RelativeTime.tsx";
 import { RoleBadge } from "../components/Roles.tsx";
 import { ScopeBadge } from "../components/ScopeBadge.tsx";
@@ -65,7 +64,7 @@ import { type Fold, usePaging } from "../components/usePaging.ts";
 import { usePendingElevations } from "../components/usePendingApprovals.ts";
 import { listOf, useI18n, useT } from "../i18n/index.tsx";
 import { initials } from "../lib/account.ts";
-import { mcpSnippet, ownModeOf, type SnippetKind, sameScopes, sortScopes } from "../lib/agents.ts";
+import { ownModeOf, sameScopes, sortScopes } from "../lib/agents.ts";
 import { type AgentKeySummary, api, isNotEnabled, mcpEndpoint } from "../lib/api.ts";
 import { apiErrorText } from "../lib/api-errors.ts";
 import { activeElevation, modesAbove } from "../lib/elevation.ts";
@@ -150,7 +149,6 @@ function KeyScopes({ agentKey }: { agentKey: AgentKeySummary }) {
 /** The "Connect an MCP client" card: endpoint, header and ready-to-paste client config. */
 export function ConnectMcpCard({ endpoint }: { endpoint: string }) {
   const t = useT();
-  const [kind, setKind] = useState<SnippetKind>("json");
   return (
     <SectionCard
       title={t("agents.connect.title")}
@@ -181,36 +179,13 @@ export function ConnectMcpCard({ endpoint }: { endpoint: string }) {
           <dd className="min-w-0">
             <ClipboardText
               size="base"
-              text="x-api-key"
+              text="Authorization: Bearer"
               tooltip={{ text: t("common.copy"), copiedText: t("common.copied") }}
             />
           </dd>
         </div>
       </dl>
-      <div className="grid min-w-0 gap-3">
-        <Tabs
-          variant="segmented"
-          size="sm"
-          value={kind}
-          onValueChange={(v) => setKind(v as SnippetKind)}
-          tabs={(["json", "claude", "stdio"] as const).map((k) => ({
-            value: k,
-            label: t(`agents.connect.tabs.${k}`),
-          }))}
-        />
-        <div className="min-w-0 overflow-x-auto">
-          <CodeHighlighted
-            code={mcpSnippet(kind, endpoint)}
-            lang={kind === "json" ? "json" : "bash"}
-            showCopyButton
-          />
-        </div>
-        {kind === "stdio" && (
-          <Text variant="secondary" size="sm">
-            {t("agents.connect.stdioHint")}
-          </Text>
-        )}
-      </div>
+      <McpClientSetup endpoint={endpoint} local />
     </SectionCard>
   );
 }
diff --git a/apps/studio/test/agents.test.tsx b/apps/studio/test/agents.test.tsx
index 157cfa00..3fdeb38a 100644
--- a/apps/studio/test/agents.test.tsx
+++ b/apps/studio/test/agents.test.tsx
@@ -160,6 +160,8 @@ describe("CreateAgentKeyDialog", () => {
     const reveal = await screen.findByTestId("key-reveal");
     expect(reveal).toHaveTextContent("You won't see this key again");
     expect(reveal.innerHTML).toContain("abc123_secret_value");
+    // Ready-to-copy setup for each client, starting with Claude Code.
+    expect(within(reveal).getByTestId("mcp-client-setup")).toHaveAttribute("data-client", "claude");
     fireEvent.click(screen.getByRole("button", { name: "I've stored the key" }));
     expect(onOpenChange).toHaveBeenCalledWith(false);
   });
diff --git a/apps/studio/test/design-rules.test.ts b/apps/studio/test/design-rules.test.ts
index fe814064..6d760c38 100644
--- a/apps/studio/test/design-rules.test.ts
+++ b/apps/studio/test/design-rules.test.ts
@@ -152,9 +152,11 @@ const REQUIRED_IMPORTS: Record<string, string[]> = {
     "Pagination",
     "DeleteResource",
     "ClipboardText",
-    "CodeHighlighted",
+    "McpClientSetup",
     "CreateAgentKeyDialog",
   ],
+  // Per-client MCP setup (docs/agents/clients.md), on the page and in the one-time key reveal.
+  "components/McpClientSetup.tsx": ["Select", "CodeHighlighted"],
   // Navigation menus (§2t, RFC-0003 §8): the MenuTree editor with its preview, picker and delta.
   "routes/NavigationPage.tsx": [
     "PageLayout",
@@ -216,7 +218,7 @@ const REQUIRED_IMPORTS: Record<string, string[]> = {
     "Checkbox",
     "ClipboardText",
     "Banner",
-    "CodeHighlighted",
+    "McpClientSetup",
     "Collapsible",
   ],
   // Agent modes (§2g, ADR-0015): mode-first create flow, change-mode dialog, badges, explainer.
diff --git a/apps/studio/test/lib.test.ts b/apps/studio/test/lib.test.ts
index 4b00bf9d..d5c2acf3 100644
--- a/apps/studio/test/lib.test.ts
+++ b/apps/studio/test/lib.test.ts
@@ -25,6 +25,7 @@ import {
   sameScopes,
   scopesForMode,
   scopeVariant,
+  snippetLang,
   sortScopes,
 } from "../src/lib/agents.ts";
 import type { AuditRow } from "../src/lib/api.ts";
@@ -222,15 +223,30 @@ describe("agent scopes", () => {
     expect(scopeVariant("site:rollback")).toBe("warning");
   });
 
-  it("fills a fresh key into the client config, placeholder otherwise", () => {
-    const json = JSON.parse(mcpSnippet("json", "https://x.dev/mcp", "k_123"));
-    expect(json.mcpServers.cloudhal).toEqual({
+  it("fills a fresh key into each client's setup, placeholder otherwise", () => {
+    const url = "https://x.dev/mcp";
+    const cursor = JSON.parse(mcpSnippet("cursor", url, "k_123"));
+    expect(cursor.mcpServers.cloudhal).toEqual({ url, headers: { Authorization: "Bearer k_123" } });
+    const generic = JSON.parse(mcpSnippet("generic", url, "k_123"));
+    expect(generic.mcpServers.cloudhal).toEqual({
       type: "http",
-      url: "https://x.dev/mcp",
-      headers: { "x-api-key": "k_123" },
+      url,
+      headers: { Authorization: "Bearer k_123" },
     });
-    expect(mcpSnippet("claude", "https://x.dev/mcp")).toContain('"x-api-key: <your agent key>"');
-    expect(mcpSnippet("stdio", "https://x.dev/mcp")).toContain("cloudhal mcp --mode edits");
+    // VS Code prompts for the key: the file never holds it.
+    const vscode = mcpSnippet("vscode", url, "k_123");
+    expect(vscode).not.toContain("k_123");
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: VS Code's own input variable
+    expect(JSON.parse(vscode).servers.cloudhal.headers.Authorization).toBe(
+      "Bearer ${input:cloudhal-key}",
+    );
+    expect(mcpSnippet("codex", url, "k_123")).toBe(
+      'export CLOUDHAL_API_KEY="k_123"\ncodex mcp add cloudhal --url https://x.dev/mcp \\\n  --bearer-token-env-var CLOUDHAL_API_KEY',
+    );
+    expect(mcpSnippet("claude", url)).toContain('"Authorization: Bearer <your agent key>"');
+    expect(mcpSnippet("stdio", url)).toContain("cloudhal mcp --mode edits");
+    expect(snippetLang("codex")).toBe("bash");
+    expect(snippetLang("vscode")).toBe("json");
   });
 });
 
diff --git a/docs/adr/0011-agent-layer.md b/docs/adr/0011-agent-layer.md
index 828b6ea4..fe07754e 100644
--- a/docs/adr/0011-agent-layer.md
+++ b/docs/adr/0011-agent-layer.md
@@ -12,7 +12,7 @@ Sprint 5 makes Cloudhal usable *by agents*: an MCP client must be able to create
 2. **Tools are defined once, independently of the SDK** (`packages/mcp-server/src/tools.ts`): JSON Schema in/out built from the contract schemas, honest annotations, scopes, handler over `SiteGraphStore`. `runTool` is the only execution path: policy → audit → handler. Every mutation auto-snapshots (`reason: "agentMutation"`, label = tool name). The 18 tools are listed deterministically.
 3. **The MCP server is a thin wrapper** (`createCloudhalMcpServer`): one instance per principal, `fromJsonSchema` for schemas (no zod in our code), `structuredContent` on every result, skills exposed as `skill://<name>/SKILL.md` (+ `references/`) resources, and a declared skill via `_meta["cloudhal.skill"]` narrowing the call to that skill's scopes.
 4. **Approval = multi-round-trip elicitation, with a signed token as fallback.** `approval-required` returns `input_required` carrying an elicitation (the prompt shows the diff summary) and an HMAC-signed `requestState` bound to the tool, the argument hash and the principal. The client retries with the answer; only `accept` + `confirm: true` runs the handler; `decline`/`cancel` is audited as a denial. Clients that cannot elicit (2025-era over stateless HTTP, hosts without elicitation) receive a `confirmToken` to pass on a second identical call — same HMAC state, same binding, 10-minute TTL; can be disabled with `confirmTokenFallback: false`.
-5. **Transports:** `cloudhal mcp` (stdio, local developer, default scopes `*`, `--scopes` to narrow) and `/mcp` inside the Hono API (`createMcpHandler`, stateless per request, 2025-era served statelessly). Authentication stays outside the SDK: the API resolves a `Principal` (session cookie → human with all scopes; `x-api-key` → `agent` actor with the key's `cloudhal` permissions as scopes) and passes it via `authInfo.extra`.
+5. **Transports:** `cloudhal mcp` (stdio, local developer, default scopes `*`, `--scopes` to narrow) and `/mcp` inside the Hono API (`createMcpHandler`, stateless per request, 2025-era served statelessly). Authentication stays outside the SDK: the API resolves a `Principal` (session cookie → human with all scopes; `x-api-key`, or `Authorization: Bearer <key>` outside `/api/admin/*` → `agent` actor with the key's `cloudhal` permissions as scopes) and passes it via `authInfo.extra`.
 6. **Agent credentials are Better Auth API keys** (`@better-auth/api-key`, table in migration `0003_agent`). Keys are minted server-side through `POST /api/agent-keys {name, scopes}` by a signed-in human (permissions are a server-only property in the plugin), listed and revoked under the same route.
 7. **Skills extension (SEP-2640) is not implemented yet.** The TypeScript SDK has no `skills/list`/`skills/get` support in 2.3.1 (PR #2818 open); resources cover discovery for now. Revisit when the SDK ships it.
 
diff --git a/docs/agents/README.md b/docs/agents/README.md
index 9940f1dc..25358c39 100644
--- a/docs/agents/README.md
+++ b/docs/agents/README.md
@@ -9,7 +9,7 @@ Cloudhal is built for agents to work on sites, with people in charge. Agents con
 | Server | `cloudhal mcp`, started by your client over stdio | `https://<studio-host>/mcp` on a deployment (streamable HTTP) |
 | Works on | The project folder it runs in (`.cloudhal/` store) | The deployment's sites |
 | Who the agent is | You, the local developer | An agent key created in Studio |
-| Authentication | None (a local process) | `x-api-key: <key>` header |
+| Authentication | None (a local process) | `Authorization: Bearer <key>` or `x-api-key: <key>` header |
 | Approvals | Asked in your MCP client | Asked in your client, or wait in Studio's **Approvals** |
 | Set up | [Connect an agent](/docs/agents/clients) | [Remote agents](#remote-agents-on-a-deployment) below |
 
@@ -54,7 +54,7 @@ The server publishes skills as MCP resources: `skill://<name>/SKILL.md` and its
 ## Remote agents on a deployment
 
 1. In Studio, open **Agents** and create a key. Choose its mode and scopes; they can never exceed your own role. The secret is shown once.
-2. Point your client at `https://<studio-host>/mcp` with the header `x-api-key: <key>`. See [Connect an agent](/docs/agents/clients#remote-server) for each client's format.
+2. Point your client at `https://<studio-host>/mcp` with the header `Authorization: Bearer <key>` (or `x-api-key: <key>`). See [Connect an agent](/docs/agents/clients#remote-server) for each client's format.
 3. The agent's calls run as that key: Studio's **Activity** shows them, **Approvals** collects what waits, and you can change the key's mode or revoke it at any time.
 
 Keep keys narrow. A key that reads reader comments should not also publish: comment text is written by strangers and reaches the agent. The [comments guide](/docs/guides/comments) and the [schedules guide](/docs/guides/schedules) (agent tasks with their own keys and budgets) go further.
diff --git a/docs/agents/clients.md b/docs/agents/clients.md
index 761daed3..8def7a7d 100644
--- a/docs/agents/clients.md
+++ b/docs/agents/clients.md
@@ -3,7 +3,7 @@
 Every MCP client connects to Cloudhal in one of two ways ([which one?](/docs/agents#two-ways-to-connect)):
 
 - **Local server:** the client starts `cloudhal mcp` in your project folder. Nothing to authenticate; the agent works on the project's local store.
-- **Remote server:** the client calls `https://<studio-host>/mcp` on a deployment, sending an agent key created in Studio under **Agents** in the `x-api-key` header.
+- **Remote server:** the client calls `https://<studio-host>/mcp` on a deployment, sending an agent key created in Studio under **Agents** as `Authorization: Bearer <key>` or in the `x-api-key` header. Both work; use whichever your client supports. Studio shows each client's setup with the key filled in right after you create it.
 
 `cloudhal mcp` serves the project folder it starts in. Configure local servers **per project** (the project-scoped files below), or start the client from the project folder.
 
@@ -40,7 +40,7 @@ Remote:
 
 ```sh
 claude mcp add --transport http cloudhal https://studio.example.com/mcp \
-  --header "x-api-key: $CLOUDHAL_API_KEY"
+  --header "Authorization: Bearer $CLOUDHAL_API_KEY"
 ```
 
 Or in `.mcp.json`, with the key read from the environment when Claude Code starts:
@@ -51,7 +51,7 @@ Or in `.mcp.json`, with the key read from the environment when Claude Code start
     "cloudhal": {
       "type": "http",
       "url": "https://studio.example.com/mcp",
-      "headers": { "x-api-key": "${CLOUDHAL_API_KEY}" }
+      "headers": { "Authorization": "Bearer ${CLOUDHAL_API_KEY}" }
     }
   }
 }
@@ -75,12 +75,18 @@ command = "npx"
 args = ["cloudhal", "mcp", "--mode", "edits"]
 ```
 
-Remote, with the key taken from the environment:
+Remote, with the key taken from the environment and sent as `Authorization: Bearer`:
+
+```sh
+codex mcp add cloudhal --url https://studio.example.com/mcp --bearer-token-env-var CLOUDHAL_API_KEY
+```
+
+Or in `config.toml`:
 
 ```toml
 [mcp_servers.cloudhal]
 url = "https://studio.example.com/mcp"
-env_http_headers = { "x-api-key" = "CLOUDHAL_API_KEY" }
+bearer_token_env_var = "CLOUDHAL_API_KEY"
 ```
 
 ## Cursor
@@ -105,7 +111,7 @@ Remote:
   "mcpServers": {
     "cloudhal": {
       "url": "https://studio.example.com/mcp",
-      "headers": { "x-api-key": "${env:CLOUDHAL_API_KEY}" }
+      "headers": { "Authorization": "Bearer ${env:CLOUDHAL_API_KEY}" }
     }
   }
 }
@@ -138,7 +144,7 @@ Remote. VS Code asks for the key once and stores it securely:
     "cloudhal": {
       "type": "http",
       "url": "https://studio.example.com/mcp",
-      "headers": { "x-api-key": "${input:cloudhal-key}" }
+      "headers": { "Authorization": "Bearer ${input:cloudhal-key}" }
     }
   }
 }
@@ -146,7 +152,7 @@ Remote. VS Code asks for the key once and stores it securely:
 
 ## Claude Desktop and claude.ai
 
-Use the remote server: **Settings › Connectors › Add custom connector**, the URL `https://studio.example.com/mcp`, and a request header `x-api-key` with your key. Claude connects from Anthropic's cloud, so this needs a deployment; `localhost` is not reachable. For a local project, use Claude Code.
+Use the remote server: **Settings › Connectors › Add custom connector**, the URL `https://studio.example.com/mcp`, and a request header `Authorization` with the value `Bearer <your key>`. Claude connects from Anthropic's cloud, so this needs a deployment; `localhost` is not reachable. For a local project, use Claude Code.
 
 ## Windsurf
 
@@ -157,7 +163,7 @@ Remote, in `mcp_config.json` (global, so prefer the remote server):
   "mcpServers": {
     "cloudhal": {
       "serverUrl": "https://studio.example.com/mcp",
-      "headers": { "x-api-key": "${env:CLOUDHAL_API_KEY}" }
+      "headers": { "Authorization": "Bearer ${env:CLOUDHAL_API_KEY}" }
     }
   }
 }
@@ -178,7 +184,7 @@ In the project's `.zed/settings.json`:
 }
 ```
 
-Remote: `{ "url": "https://studio.example.com/mcp", "headers": { "x-api-key": "…" } }` in place of `command` and `args`.
+Remote: `{ "url": "https://studio.example.com/mcp", "headers": { "Authorization": "Bearer …" } }` in place of `command` and `args`.
 
 ## Gemini CLI
 
@@ -195,20 +201,20 @@ Local, in the project's `.gemini/settings.json`:
 Remote (Gemini uses `httpUrl` for streamable HTTP):
 
 ```sh
-gemini mcp add --transport http -H "x-api-key: $CLOUDHAL_API_KEY" cloudhal https://studio.example.com/mcp
+gemini mcp add --transport http -H "Authorization: Bearer $CLOUDHAL_API_KEY" cloudhal https://studio.example.com/mcp
 ```
 
 ## Any other client
 
 - **stdio:** command `npx`, arguments `cloudhal mcp --mode edits`, working directory: your project.
-- **Streamable HTTP:** URL `https://<studio-host>/mcp`, header `x-api-key: <key>`.
+- **Streamable HTTP:** URL `https://<studio-host>/mcp`, header `Authorization: Bearer <key>` (or `x-api-key: <key>`).
 
-A client that cannot send headers can reach the remote server through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a local stdio command: `npx -y mcp-remote https://studio.example.com/mcp --header "x-api-key:${CLOUDHAL_API_KEY}"`.
+A client that cannot send headers can reach the remote server through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a local stdio command: `npx -y mcp-remote https://studio.example.com/mcp --header "Authorization:Bearer ${CLOUDHAL_API_KEY}"`.
 
 ## Troubleshooting
 
 - **The client lists no tools.** Run the command yourself in the project folder: `npx cloudhal mcp` should start and keep running (it waits for a client on stdin). An error there (Node older than 24, not a Cloudhal project) is what the client sees.
 - **The agent edits a different site.** The local server serves the folder it started in. Use a project-scoped config, or start the client from the project.
-- **`401 unauthorized` remotely.** The key is missing, revoked, or sent in another header. Cloudhal reads `x-api-key`.
+- **`401 unauthorized` remotely.** The key is missing, revoked, or sent in another header. Cloudhal reads `Authorization: Bearer <key>` and `x-api-key`; on `/mcp` a bearer must be an agent key, not the deployment token.
 - **`403 not_a_member`.** The key's owner no longer belongs to the deployment; create a new key.
 - **A call says it is waiting for approval.** Accept it in your client, or in Studio under **Approvals** on a deployment.
diff --git a/docs/security/threat-model.md b/docs/security/threat-model.md
index c2da910a..5dbf1dfd 100644
--- a/docs/security/threat-model.md
+++ b/docs/security/threat-model.md
@@ -12,9 +12,9 @@ Staff roles are named sets of scopes (RFC-0005, ADR-0018). A person's role is re
 | Editor | Session cookie | Content, pages, taxonomies, redirects, publish, rollback, all Activity; invites Contributors and Authors |
 | Author | Session cookie | Own articles in any status; publishes own-only change sets (anything wider becomes a request an Editor decides) |
 | Contributor | Session cookie | Own never-published drafts (draft/review); proposes tags; never publishes |
-| Agent | API key (`x-api-key`) with explicit scopes | MCP tools only, within its scopes narrowed to its creator's current role; publish/rollback/delete wait for a person |
+| Agent | API key (`x-api-key` or `Authorization: Bearer`) with explicit scopes | MCP tools only, within its scopes narrowed to its creator's current role; publish/rollback/delete wait for a person |
 | Local developer's agent | `cloudhal mcp` over stdio | All scopes on the local project; gated tools ask in the MCP client |
-| Automation key | API key (`x-api-key`) minted for one automation by the person who created it (RFC-0008) | An agent key that works only inside its automation's run windows (outside them only `begin_run`, `get_mode` and `pause_automation` answer); narrowed to its owner's current role, capped by the automation's mode cap, never `bypass`; within budgets; read, label and hide only once its run reads visitor-supplied text |
+| Automation key | API key (`x-api-key` or `Authorization: Bearer`) minted for one automation by the person who created it (RFC-0008) | An agent key that works only inside its automation's run windows (outside them only `begin_run`, `get_mode` and `pause_automation` answer); narrowed to its owner's current role, capped by the automation's mode cap, never `bypass`; within budgets; read, label and hide only once its run reads visitor-supplied text |
 | Scheduler | System actor (`sys_scheduler`) inside the admin Worker or the Node process; no credential | Publishes releases on behalf of the person who approved them, runs built-in jobs, opens and closes run windows (RFC-0008) |
 | Operator | Deployment token (bearer) | Export/import whole sites (`cloudhal push/pull`); recover ownership (`cloudhal owner transfer`); export/import reader comments, with commenters' emails (`cloudhal comments export|import --remote`, RFC-0007); read the scheduler's status and run a tick (`cloudhal schedules status|list|run-due --remote`, RFC-0008) |
 | Site visitor | — | Published pages; drafts only with a signed preview link; sends analytics beacons, which count only for published pages (RFC-0006); sends comments and reports, which are held for moderation (RFC-0007) |
diff --git a/packages/api/src/auth/instance.ts b/packages/api/src/auth/instance.ts
index edec91dc..89d8f81f 100644
--- a/packages/api/src/auth/instance.ts
+++ b/packages/api/src/auth/instance.ts
@@ -129,7 +129,8 @@ export function createInstance(options: AuthOptions, staff: StaffStore): Auth {
         schema: { invitation: { additionalFields: INVITATION_FIELDS } },
       }),
       admin(),
-      // Non-interactive credentials for agents/CI: `x-api-key` → `agent` actor (ADR-0011).
+      // Non-interactive credentials for agents/CI: `x-api-key` or `Authorization: Bearer` → `agent`
+      // actor (ADR-0011); `resolvePrincipal` reads them (`agentKeyFrom`).
       apiKey({
         apiKeyHeaders: API_KEY_HEADER,
         enableMetadata: true,
diff --git a/packages/api/src/auth/principal.ts b/packages/api/src/auth/principal.ts
index e7133fdd..7d3e9b2a 100644
--- a/packages/api/src/auth/principal.ts
+++ b/packages/api/src/auth/principal.ts
@@ -20,14 +20,14 @@ import {
   personRef,
   storedScopes,
 } from "./key-rows.ts";
-import { API_KEY_HEADER } from "./types.ts";
+import { agentKeyFrom } from "./types.ts";
 
 export function createPrincipalResolver(d: AuthDeps): PrincipalResolver {
   const { now, staffStore, keyLimit, instance, api } = d;
   const resolvePrincipal: PrincipalResolver = async (
     c: Context,
   ): Promise<Principal | undefined> => {
-    const key = c.req.header(API_KEY_HEADER);
+    const key = agentKeyFrom(c.req.raw.headers, c.req.path);
     if (key) {
       const verified = await api.verifyApiKey({ body: { key } });
       if (!verified.valid || !verified.key) return undefined;
diff --git a/packages/api/src/auth/types.ts b/packages/api/src/auth/types.ts
index 4a67812c..89a90826 100644
--- a/packages/api/src/auth/types.ts
+++ b/packages/api/src/auth/types.ts
@@ -202,6 +202,22 @@ export const NOT_A_MEMBER_MESSAGE =
   "Your access was removed. Ask an administrator for a new invite.";
 
 export const API_KEY_HEADER = "x-api-key";
+
+/** `/api/admin/*` takes `Authorization: Bearer <CLOUDHAL_DEPLOY_TOKEN>`, never an agent key. */
+const DEPLOY_TOKEN_PATHS = /^\/api\/admin(\/|$)/;
+
+/**
+ * The agent key a request carries: `x-api-key`, else `Authorization: Bearer <key>` (what most MCP
+ * clients and Codex's `bearer_token_env_var` send). On the deployment-token routes the bearer is the
+ * deploy token, so it is not read as a key there.
+ */
+export function agentKeyFrom(headers: Headers, path: string): string | undefined {
+  const key = headers.get(API_KEY_HEADER);
+  if (key) return key;
+  if (DEPLOY_TOKEN_PATHS.test(path)) return undefined;
+  const bearer = /^Bearer\s+(\S+)\s*$/i.exec(headers.get("authorization") ?? "")?.[1];
+  return bearer || undefined;
+}
 export const SETUP_TOKEN_HEADER = "x-cloudhal-setup-token";
 
 /**
diff --git a/packages/api/src/testing-agent-key-auth.ts b/packages/api/src/testing-agent-key-auth.ts
new file mode 100644
index 00000000..365d132a
--- /dev/null
+++ b/packages/api/src/testing-agent-key-auth.ts
@@ -0,0 +1,151 @@
+/**
+ * Shared suite for how an agent key reaches the API: `x-api-key` or `Authorization: Bearer <key>`
+ * (what most MCP clients and Codex's `bearer_token_env_var` send), on REST and `/mcp`, next to the
+ * deployment-token bearer of `/api/admin/*` and browser sessions. Runs on better-sqlite3 and
+ * Miniflare D1.
+ */
+import { AuditLog } from "@cloudhal/agent-runtime";
+import { seedStarterSite } from "@cloudhal/core-ts";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { afterAll, describe, expect, it } from "vitest";
+import { createApi } from "./app.ts";
+import { createAuth } from "./auth.ts";
+import type { RolesBackend } from "./testing-roles.ts";
+
+type Json = Record<string, unknown>;
+const ORIGIN = "http://studio.test";
+const DEPLOY_TOKEN = "key-auth-deploy-token-0123456789abcdefghij";
+
+export function describeAgentKeyAuthApi(label: string, backend: RolesBackend): void {
+  describe(`agent key headers: ${label}`, { timeout: 180_000 }, () => {
+    afterAll(async () => {
+      await backend.dispose?.();
+    });
+
+    const setup = async () => {
+      const b = await backend.create();
+      await seedStarterSite(b.store, { name: "Blog", slug: "blog" });
+      const auth = createAuth({
+        database: b.database,
+        sql: b.sql,
+        baseURL: ORIGIN,
+        secret: "key-auth-secret-0123456789abcdefghijkl",
+        signUp: "first-user",
+      });
+      const audit = new AuditLog(b.sql);
+      const app = createApi({
+        store: b.store,
+        resolvePrincipal: auth.resolvePrincipal,
+        authHandler: auth.handler,
+        agentKeys: auth.agentKeys,
+        staff: auth.staff,
+        signUp: auth.signUp,
+        audit,
+        mcp: { stateKey: "key-auth-state-key-0123456789abcdefghi", audit },
+        admin: { deployToken: DEPLOY_TOKEN, storage: { sql: b.sql, blobs: b.blobs } },
+      });
+      let ip = 0;
+      const call = async (method: string, path: string, headers: Record<string, string> = {}) => {
+        const res = await app.request(`${ORIGIN}${path}`, {
+          method,
+          headers: {
+            "content-type": "application/json",
+            "x-forwarded-for": `10.2.0.${ip++ % 250}`,
+            ...headers,
+          },
+        });
+        const text = await res.text();
+        return { status: res.status, body: (text ? JSON.parse(text) : {}) as Json, res };
+      };
+      const signUp = await app.request(`${ORIGIN}/api/auth/sign-up/email`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          name: "Olive Owner",
+          email: "owner@example.com",
+          password: "correct horse battery staple",
+        }),
+      });
+      const cookie =
+        (signUp.headers.getSetCookie?.() ?? [])
+          .map((c) => c.split(";")[0] as string)
+          .find((c) => c.startsWith("better-auth.session_token=")) ?? "";
+      const created = await app.request(`${ORIGIN}/api/agent-keys`, {
+        method: "POST",
+        headers: { "content-type": "application/json", cookie },
+        body: JSON.stringify({ name: "bearer agent" }),
+      });
+      expect(created.status).toBe(201);
+      const key = ((await created.json()) as { key: string }).key;
+      const connect = async (headers: Record<string, string>) => {
+        const client = new Client(
+          { name: "key-auth-agent", version: "1.0.0" },
+          { capabilities: {}, versionNegotiation: { mode: "auto" } },
+        );
+        await client.connect(
+          new StreamableHTTPClientTransport(new URL(`${ORIGIN}/mcp`), {
+            requestInit: { headers },
+            fetch: async (input, init) => app.fetch(new Request(input, init as RequestInit)),
+          }),
+        );
+        return client;
+      };
+      return { call, cookie, key, connect };
+    };
+
+    it("accepts the key as x-api-key or as Authorization: Bearer on REST", async () => {
+      const { call, key } = await setup();
+      for (const headers of [
+        { "x-api-key": key },
+        { authorization: `Bearer ${key}` },
+        { authorization: `bearer  ${key}` },
+      ]) {
+        const me = await call("GET", "/api/me", headers);
+        expect(me.status, JSON.stringify(me.body)).toBe(200);
+        expect(me.body.actor).toMatchObject({ kind: "agent", name: "bearer agent" });
+      }
+      // Bearer is only another header: REST still sends agents to /mcp (ADR-0011).
+      const sites = await call("GET", "/api/sites", { authorization: `Bearer ${key}` });
+      expect(sites.body.message).toMatch(/\/mcp/);
+    });
+
+    it("refuses an unknown bearer and does not fall back to the session", async () => {
+      const { call, cookie } = await setup();
+      expect((await call("GET", "/api/me", { authorization: "Bearer not-a-key" })).status).toBe(
+        401,
+      );
+      expect(
+        (await call("GET", "/api/me", { authorization: "Bearer not-a-key", cookie })).status,
+      ).toBe(401);
+      // A browser session without a bearer still answers as the person.
+      const me = await call("GET", "/api/me", { cookie });
+      expect(me.status).toBe(200);
+      expect(me.body.actor).toMatchObject({ kind: "human" });
+    });
+
+    it("connects an MCP client with Authorization: Bearer", async () => {
+      const { key, connect } = await setup();
+      const client = await connect({ authorization: `Bearer ${key}` });
+      const tools = await client.listTools();
+      expect(tools.tools.map((t) => t.name)).toContain("get_mode");
+      await client.close();
+      await expect(connect({ authorization: "Bearer not-a-key" })).rejects.toThrow();
+    });
+
+    it("keeps /api/admin on the deployment token; an agent key is not one", async () => {
+      const { call, key } = await setup();
+      const sites = await call("GET", "/api/admin/sites", {
+        authorization: `Bearer ${DEPLOY_TOKEN}`,
+      });
+      expect(sites.status, JSON.stringify(sites.body)).toBe(200);
+      expect(
+        (await call("GET", "/api/admin/sites", { authorization: `Bearer ${key}` })).status,
+      ).toBe(401);
+      expect((await call("GET", "/api/admin/sites", { "x-api-key": key })).status).toBe(401);
+      // The deployment token is not an agent key elsewhere either.
+      expect(
+        (await call("GET", "/api/me", { authorization: `Bearer ${DEPLOY_TOKEN}` })).status,
+      ).toBe(401);
+    });
+  });
+}
diff --git a/packages/api/test/agent-key-auth.test.ts b/packages/api/test/agent-key-auth.test.ts
new file mode 100644
index 00000000..e4f10934
--- /dev/null
+++ b/packages/api/test/agent-key-auth.test.ts
@@ -0,0 +1,34 @@
+import { SiteGraphStore } from "@cloudhal/core-ts";
+import { MemoryBlobStore } from "@cloudhal/storage";
+import { D1Driver } from "@cloudhal/storage/d1";
+import { BetterSqlite3Driver } from "@cloudhal/storage/sqlite";
+import { createMiniflareD1, createTableReset } from "@cloudhal/storage/testing";
+import Database from "better-sqlite3";
+import { describeAgentKeyAuthApi } from "../src/testing-agent-key-auth.ts";
+
+describeAgentKeyAuthApi("better-sqlite3", {
+  async create() {
+    const database = new Database(":memory:");
+    const sql = new BetterSqlite3Driver(database);
+    const blobs = new MemoryBlobStore();
+    const store = new SiteGraphStore({ sql, blobs });
+    await store.init();
+    return { store, sql, blobs, database };
+  },
+});
+
+let d1: Awaited<ReturnType<typeof createMiniflareD1>> | undefined;
+const reset = createTableReset();
+describeAgentKeyAuthApi("Cloudflare D1 (Miniflare)", {
+  async create() {
+    d1 ??= await createMiniflareD1();
+    const sql = new D1Driver(d1.db);
+    const blobs = new MemoryBlobStore();
+    const store = new SiteGraphStore({ sql, blobs });
+    await reset(sql, () => store.init());
+    return { store, sql, blobs, database: d1.db };
+  },
+  async dispose() {
+    await d1?.dispose();
+  },
+});
diff --git a/scripts/size-baseline.json b/scripts/size-baseline.json
index b6922d1a..114962bf 100644
--- a/scripts/size-baseline.json
+++ b/scripts/size-baseline.json
@@ -88,7 +88,7 @@
       "lines": 350
     },
     "apps/studio/src/components/CreateAgentKeyDialog.tsx::CreateAgentKeyDialog": {
-      "lines": 338
+      "lines": 317
     },
     "apps/studio/src/components/CreateTermDialog.tsx::CreateTermDialog": {
       "lines": 173