From 06b4b71fb9b8a0a6d5fb04c3ca896b48711ab949 Mon Sep 17 00:00:00 2001
From: Justin Bradfield <bradfield.justin7@gmail.com>
Date: Fri, 8 May 2026 13:21:32 -0500
Subject: [PATCH 1/4] console: clean up connect modal MCP instructions

- Move MCP token generation into the MCP tab with a "Generate MCP token"
  button instead of showing it stacked below with the app password
- Restructure MCP instructions into clear steps: (1) get your token
  (generate or base64-encode existing), (2) connect your client
- Simplify client instructions to show `claude mcp add` command and link
  to docs for other clients instead of tabs for each client
- Add `wrap` prop to CopyableBox for multiline command display
- Hide the "Create app password" section when on the MCP tab
- Use tabs for App password / MCP token on the App Passwords page

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 console/src/access/AppPasswordsPage.tsx       |  60 +++---
 .../src/components/ConnectInstructions.tsx    |   8 +
 console/src/components/ConnectModal.tsx       |  41 ++--
 .../src/components/McpConnectInstructions.tsx | 185 +++++++++---------
 console/src/components/copyableComponents.tsx |   6 +-
 console/src/mz-doc-urls.json                  |   1 +
 6 files changed, 147 insertions(+), 154 deletions(-)

diff --git a/console/src/access/AppPasswordsPage.tsx b/console/src/access/AppPasswordsPage.tsx
index 8be5d53f55600..3ad93817fba39 100644
--- a/console/src/access/AppPasswordsPage.tsx
+++ b/console/src/access/AppPasswordsPage.tsx
@@ -28,7 +28,12 @@ import {
   Radio,
   RadioGroup,
   Stack,
+  Tab,
   Table,
+  TabList,
+  TabPanel,
+  TabPanels,
+  Tabs,
   Tbody,
   Td,
   Text,
@@ -495,34 +500,33 @@ const SecretBox = ({
     >
       <VStack alignItems="flex-start" width="100%">
         <AlertDescription width="100%" px={2}>
-          <VStack alignItems="start" spacing="3">
-            <VStack alignItems="start" spacing="1" width="100%">
-              <Text fontSize="md" fontWeight="500">
-                New password {`"${name}"`}:
-              </Text>
-              <SecretCopyableBox
-                label="clientId"
-                contents={password}
-                obfuscatedContent={obfuscatedContent}
-              />
-            </VStack>
-            <VStack alignItems="start" spacing="1" width="100%">
-              <Text fontSize="md" fontWeight="500">
-                MCP Token
-              </Text>
-              <SecretCopyableBox
-                label="mcpToken"
-                contents={base64Token}
-                obfuscatedContent={obfuscatedBase64Token}
-                overflow="hidden"
-                minWidth={0}
-              />
-              <Text fontSize="xs" color={colors.foreground.secondary}>
-                Base64-encoded <code>{userEmail}:&lt;password&gt;</code> for MCP
-                configuration.
-              </Text>
-            </VStack>
-          </VStack>
+          <Text fontSize="md" fontWeight="500" mb="1">
+            New password {`"${name}"`}
+          </Text>
+          <Tabs variant="line" size="sm">
+            <TabList>
+              <Tab>App password</Tab>
+              <Tab>MCP token</Tab>
+            </TabList>
+            <TabPanels>
+              <TabPanel px="0" pt="3" pb="0">
+                <SecretCopyableBox
+                  label="clientId"
+                  contents={password}
+                  obfuscatedContent={obfuscatedContent}
+                />
+              </TabPanel>
+              <TabPanel px="0" pt="3" pb="0">
+                <SecretCopyableBox
+                  label="mcpToken"
+                  contents={base64Token}
+                  obfuscatedContent={obfuscatedBase64Token}
+                  overflow="hidden"
+                  minWidth={0}
+                />
+              </TabPanel>
+            </TabPanels>
+          </Tabs>
           <Text pt={2} textStyle="text-base" color={colors.foreground.primary}>
             Write this down; you will not be able to see your credentials again
             after you reload!
diff --git a/console/src/components/ConnectInstructions.tsx b/console/src/components/ConnectInstructions.tsx
index 139a38a0df067..fef8482b6686c 100644
--- a/console/src/components/ConnectInstructions.tsx
+++ b/console/src/components/ConnectInstructions.tsx
@@ -35,12 +35,18 @@ export interface ConnectInstructionsProps extends BoxProps {
   mcpBase64Token?: string;
   /** Called when the active tab changes. */
   onTabChange?: (title: string) => void;
+  /** Callback to generate a new MCP token (creates an app password). */
+  onGenerateToken?: () => void;
+  /** Whether token generation is in progress. */
+  isGeneratingToken?: boolean;
 }
 
 const ConnectInstructions = ({
   user,
   onTabChange,
   mcpBase64Token,
+  onGenerateToken,
+  isGeneratingToken,
   ...props
 }: ConnectInstructionsProps): JSX.Element => {
   const [currentEnvironment] = useAtom(currentEnvironmentState);
@@ -129,6 +135,8 @@ const ConnectInstructions = ({
             <McpConnectInstructions
               userStr={userStr}
               mcpBase64Token={mcpBase64Token}
+              onGenerateToken={onGenerateToken}
+              isGeneratingToken={isGeneratingToken}
             />
           ),
           icon: <ConnectionIcon w="4" h="4" />,
diff --git a/console/src/components/ConnectModal.tsx b/console/src/components/ConnectModal.tsx
index 3a99ea3400283..ca2ee13bd31e4 100644
--- a/console/src/components/ConnectModal.tsx
+++ b/console/src/components/ConnectModal.tsx
@@ -31,7 +31,7 @@ import docUrls from "~/mz-doc-urls.json";
 import { useCreateApiToken } from "~/queries/frontegg";
 import { useListApiTokens } from "~/queries/frontegg";
 import { MaterializeTheme } from "~/theme";
-import { obfuscateSecret, toBase64 } from "~/utils/format";
+import { toBase64 } from "~/utils/format";
 
 import { SecretCopyableBox } from "./copyableComponents";
 import SupportLink from "./SupportLink";
@@ -69,6 +69,8 @@ const ConnectModal = ({
     ? toBase64(`${mcpUser}:${newPassword.password}`)
     : undefined;
 
+  const isMcpTab = activeTab === "MCP Server";
+
   return (
     <Modal size="3xl" isOpen={isOpen} onClose={onClose}>
       <ModalOverlay />
@@ -97,17 +99,22 @@ const ConnectModal = ({
             userStr={forAppPassword?.user}
             mcpBase64Token={mcpBase64Token}
             onTabChange={setActiveTab}
+            onGenerateToken={() =>
+              createAppPassword({
+                type: "personal",
+                description: "MCP token",
+              })
+            }
+            isGeneratingToken={createInProgress}
             mt="4"
           />
-          {showCreateAppPassword && (
+          {showCreateAppPassword && !isMcpTab && (
             <Box mt="6">
               <CreateAppPassword
                 user={user}
                 createAppPassword={createAppPassword}
                 createInProgress={createInProgress}
                 newPassword={newPassword}
-                mcpBase64Token={mcpBase64Token}
-                showMcpToken={activeTab === "MCP Server"}
               />
             </Box>
           )}
@@ -122,8 +129,6 @@ interface CreateAppPasswordProps {
   createAppPassword: ReturnType<typeof useCreateApiToken>["mutate"];
   createInProgress: boolean;
   newPassword: ReturnType<typeof useCreateApiToken>["data"];
-  mcpBase64Token?: string;
-  showMcpToken: boolean;
 }
 
 const CreateAppPassword = (props: CreateAppPasswordProps) => {
@@ -147,8 +152,6 @@ const CreateAppPasswordInner = ({
   createAppPassword,
   createInProgress,
   newPassword,
-  mcpBase64Token,
-  showMcpToken,
 }: CreateAppPasswordProps) => {
   const { data: appPasswords } = useListApiTokens({ user });
   const { colors } = useTheme<MaterializeTheme>();
@@ -165,26 +168,6 @@ const CreateAppPasswordInner = ({
   if (newPassword?.password) {
     return (
       <>
-        {showMcpToken && mcpBase64Token && (
-          <VStack alignItems="stretch" mb="3">
-            <Text
-              as="span"
-              fontSize="sm"
-              lineHeight="16px"
-              fontWeight={500}
-              color={colors.foreground.primary}
-            >
-              MCP token
-            </Text>
-            <SecretCopyableBox
-              label="mcpToken"
-              contents={mcpBase64Token}
-              obfuscatedContent={obfuscateSecret(mcpBase64Token)}
-              overflow="hidden"
-              minWidth={0}
-            />
-          </VStack>
-        )}
         <VStack alignItems="stretch">
           <Text
             as="span"
@@ -223,7 +206,7 @@ const CreateAppPasswordInner = ({
             Create an app password
           </Text>
           <Text fontSize="sm" color={colors.foreground.secondary}>
-            Create a new app password if you don’t have one accessible.
+            Create a new app password if you don&apos;t have one accessible.
           </Text>
         </Box>
         <Button
diff --git a/console/src/components/McpConnectInstructions.tsx b/console/src/components/McpConnectInstructions.tsx
index 6a3c465157115..7a34e53549ec6 100644
--- a/console/src/components/McpConnectInstructions.tsx
+++ b/console/src/components/McpConnectInstructions.tsx
@@ -7,46 +7,42 @@
 // the Business Source License, use of this software will be governed
 // by the Apache License, Version 2.0.
 
-import { BoxProps, Text, useTheme, VStack } from "@chakra-ui/react";
+import {
+  BoxProps,
+  Button,
+  Flex,
+  Spinner,
+  Text,
+  useTheme,
+  VStack,
+} from "@chakra-ui/react";
 import { useAtom } from "jotai";
 import React from "react";
 
 import { useAppConfig } from "~/config/useAppConfig";
+import docUrls from "~/mz-doc-urls.json";
 import { currentEnvironmentState } from "~/store/environments";
 import { MaterializeTheme } from "~/theme";
+import { obfuscateSecret } from "~/utils/format";
 
-import { CopyableBox, TabbedCodeBlock } from "./copyableComponents";
+import { CopyableBox, SecretCopyableBox } from "./copyableComponents";
+import TextLink from "./TextLink";
 
 interface McpConnectInstructionsProps extends BoxProps {
   userStr: string;
   /** Pre-computed Base64 token for MCP configuration (cloud only). */
   mcpBase64Token?: string;
+  /** Callback to generate a new MCP token (creates an app password). */
+  onGenerateToken?: () => void;
+  /** Whether token generation is in progress. */
+  isGeneratingToken?: boolean;
 }
 
-const mcpConfigJson = (
-  baseUrl: string,
-  endpoint: "agents" | "developer",
-  opts?: { includeType?: boolean },
-) =>
-  JSON.stringify(
-    {
-      mcpServers: {
-        [`materialize-${endpoint}`]: {
-          ...(opts?.includeType && { type: "http" }),
-          url: `${baseUrl}/api/mcp/${endpoint}`,
-          headers: {
-            Authorization: "Basic <base64-token>",
-          },
-        },
-      },
-    },
-    null,
-    2,
-  );
-
 const McpConnectInstructions = ({
   userStr,
   mcpBase64Token,
+  onGenerateToken,
+  isGeneratingToken,
   ...props
 }: McpConnectInstructionsProps) => {
   const { colors } = useTheme<MaterializeTheme>();
@@ -73,7 +69,7 @@ const McpConnectInstructions = ({
   const base64Command = `printf '${user}:<password>' | base64 -w0`;
 
   const endpointUrl = `${baseUrl}/api/mcp/${endpoint}`;
-  const claudeCodeCliCommand = `claude mcp add --transport http materialize-${endpoint} ${endpointUrl} --header "Authorization: Basic <base64-token>"`;
+  const claudeCodeCliCommand = `claude mcp add --transport http materialize-${endpoint} \\\n  ${endpointUrl} \\\n  --header "Authorization: Basic <mcp-token>"`;
 
   return (
     <VStack
@@ -89,82 +85,81 @@ const McpConnectInstructions = ({
         built-in MCP server.
       </Text>
 
-      <VStack alignItems="stretch" spacing="2">
-        <Text textStyle="heading-xs">Step 1. Get your MCP token</Text>
-        <Text fontSize="sm" color={colors.foreground.secondary}>
-          {isCloud
-            ? "Create a new app password and copy the MCP Token, or encode an existing app password by running the following in your terminal:"
-            : "Use a role with login and password attributes. Run the following in your terminal:"}
-        </Text>
-        <CopyableBox variant="default" contents={base64Command} />
-        {isCloud && mcpBase64Token && (
-          <Text fontSize="sm" color={colors.foreground.secondary}>
-            Your MCP token is available above, under the app password.
-          </Text>
+      <VStack alignItems="stretch" spacing="3">
+        <Text textStyle="heading-xs">1. Get your MCP token</Text>
+
+        {isCloud && onGenerateToken && (
+          <VStack alignItems="stretch" spacing="2">
+            <Text fontSize="sm" color={colors.foreground.secondary}>
+              Generate a new token:
+            </Text>
+            {isGeneratingToken ? (
+              <Flex alignItems="center" color={colors.foreground.secondary}>
+                <Spinner size="sm" mr={2} />
+                <Text fontSize="sm">Generating token...</Text>
+              </Flex>
+            ) : mcpBase64Token ? (
+              <VStack alignItems="stretch" spacing="1">
+                <SecretCopyableBox
+                  label="mcpToken"
+                  contents={mcpBase64Token}
+                  obfuscatedContent={obfuscateSecret(mcpBase64Token)}
+                  overflow="hidden"
+                  minWidth={0}
+                />
+                <Text
+                  fontSize="xs"
+                  color={colors.foreground.secondary}
+                  lineHeight="tall"
+                >
+                  Copy this somewhere safe. Tokens cannot be displayed after
+                  initial creation.
+                </Text>
+              </VStack>
+            ) : (
+              <Button
+                onClick={onGenerateToken}
+                variant="primary"
+                size="sm"
+                alignSelf="flex-start"
+              >
+                Generate MCP token
+              </Button>
+            )}
+          </VStack>
         )}
+
+        <VStack alignItems="stretch" spacing="2">
+          {isCloud && (
+            <Text fontSize="sm" color={colors.foreground.secondary}>
+              Or Base64-encode an existing app password:
+            </Text>
+          )}
+          {!isCloud && (
+            <Text fontSize="sm" color={colors.foreground.secondary}>
+              Base64-encode your username and password:
+            </Text>
+          )}
+          <CopyableBox variant="default" contents={base64Command} />
+        </VStack>
       </VStack>
 
-      <VStack alignItems="stretch" spacing="2">
-        <Text textStyle="heading-xs">Step 2. Connect your client</Text>
+      <VStack alignItems="stretch" spacing="3">
+        <Text textStyle="heading-xs">2. Connect your client</Text>
+        <Text fontSize="sm" color={colors.foreground.secondary}>
+          See the{" "}
+          <TextLink
+            href={docUrls["/docs/integrations/mcp-server/"]}
+            target="_blank"
+          >
+            documentation
+          </TextLink>{" "}
+          for connecting clients like Claude Desktop, Cursor, Windsurf, etc.
+        </Text>
         <Text fontSize="sm" color={colors.foreground.secondary}>
-          Replace <code>&lt;base64-token&gt;</code> with the output from Step 1.
+          Or connect to Claude Code now:
         </Text>
-        <TabbedCodeBlock
-          tabs={[
-            {
-              title: "Claude Code",
-              children: (
-                <VStack alignItems="stretch" spacing="3" p="4">
-                  <Text fontSize="xs" color={colors.foreground.secondary}>
-                    Run this command in your terminal:
-                  </Text>
-                  <CopyableBox
-                    variant="default"
-                    contents={claudeCodeCliCommand}
-                  />
-                  <Text fontSize="xs" color={colors.foreground.secondary}>
-                    Or save to <code>.mcp.json</code> in your project directory:
-                  </Text>
-                  <CopyableBox
-                    variant="default"
-                    contents={mcpConfigJson(baseUrl, endpoint, {
-                      includeType: true,
-                    })}
-                  />
-                </VStack>
-              ),
-            },
-            {
-              title: "Claude Desktop",
-              children: (
-                <VStack alignItems="stretch" spacing="3" p="4">
-                  <Text fontSize="xs" color={colors.foreground.secondary}>
-                    Save to <code>claude_desktop_config.json</code>:
-                  </Text>
-                  <CopyableBox
-                    variant="default"
-                    contents={mcpConfigJson(baseUrl, endpoint)}
-                  />
-                </VStack>
-              ),
-            },
-            {
-              title: "Cursor",
-              children: (
-                <VStack alignItems="stretch" spacing="3" p="4">
-                  <Text fontSize="xs" color={colors.foreground.secondary}>
-                    Save to <code>.cursor/mcp.json</code> in your project
-                    directory:
-                  </Text>
-                  <CopyableBox
-                    variant="default"
-                    contents={mcpConfigJson(baseUrl, endpoint)}
-                  />
-                </VStack>
-              ),
-            },
-          ]}
-        />
+        <CopyableBox variant="default" wrap contents={claudeCodeCliCommand} />
       </VStack>
     </VStack>
   );
diff --git a/console/src/components/copyableComponents.tsx b/console/src/components/copyableComponents.tsx
index 26b8790d45f6f..326f6fabefda2 100644
--- a/console/src/components/copyableComponents.tsx
+++ b/console/src/components/copyableComponents.tsx
@@ -99,6 +99,7 @@ export interface CopyableBoxProps extends BoxProps {
   contents: string;
   variant?: "default" | "compact";
   maxHeight?: string;
+  wrap?: boolean;
   onCopy?: () => void;
 }
 /** Copyable component with a bg box but no line breaks  */
@@ -106,6 +107,7 @@ export const CopyableBox: React.FC<CopyableBoxProps> = ({
   contents,
   variant = "default",
   maxHeight,
+  wrap,
   onCopy,
   ...props
 }) => {
@@ -127,9 +129,9 @@ export const CopyableBox: React.FC<CopyableBoxProps> = ({
         py={2}
         flex={1}
         lineHeight="4"
-        whiteSpace="nowrap"
+        whiteSpace={wrap ? "pre" : "nowrap"}
         overflow="hidden"
-        textOverflow="ellipsis"
+        textOverflow={wrap ? undefined : "ellipsis"}
         minWidth={0}
         {...(maxHeight && {
           maxHeight,
diff --git a/console/src/mz-doc-urls.json b/console/src/mz-doc-urls.json
index 90e47b980392e..56b01b1919e34 100644
--- a/console/src/mz-doc-urls.json
+++ b/console/src/mz-doc-urls.json
@@ -290,6 +290,7 @@
   "/docs/serve-results/sink/kafka/": "https://materialize.com/docs/serve-results/sink/kafka/",
   "/docs/transform-data/idiomatic-materialize-sql/lag/": "https://materialize.com/docs/transform-data/idiomatic-materialize-sql/lag/",
   "/docs/integrations/llm/": "https://materialize.com/docs/integrations/llm/",
+  "/docs/integrations/mcp-server/": "https://materialize.com/docs/integrations/mcp-server/",
   "/docs/transform-data/idiomatic-materialize-sql/last-value/": "https://materialize.com/docs/transform-data/idiomatic-materialize-sql/last-value/",
   "/docs/transform-data/idiomatic-materialize-sql/lead/": "https://materialize.com/docs/transform-data/idiomatic-materialize-sql/lead/",
   "/docs/sql/functions/length/": "https://materialize.com/docs/sql/functions/length/",

From ad6a6965805038c11dbff3b144504a3c8121ffd2 Mon Sep 17 00:00:00 2001
From: Justin Bradfield <bradfield.justin7@gmail.com>
Date: Sat, 9 May 2026 00:42:59 -0500
Subject: [PATCH 2/4] Update console/src/components/McpConnectInstructions.tsx

Co-authored-by: Qindeel Ishtiaq <qindeeli@gmail.com>
---
 console/src/components/McpConnectInstructions.tsx | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/console/src/components/McpConnectInstructions.tsx b/console/src/components/McpConnectInstructions.tsx
index 7a34e53549ec6..f4ebab41bc8bc 100644
--- a/console/src/components/McpConnectInstructions.tsx
+++ b/console/src/components/McpConnectInstructions.tsx
@@ -85,7 +85,14 @@ const McpConnectInstructions = ({
         built-in MCP server.
       </Text>
 
-      <VStack alignItems="stretch" spacing="3">
+    <VStack
+      alignItems="stretch"
+      spacing="6"
+      p="6"
+      overflowY="auto"
+      maxHeight="60vh"
+      {...props}
+    >
         <Text textStyle="heading-xs">1. Get your MCP token</Text>
 
         {isCloud && onGenerateToken && (

From a70be203e21dfa28fa61dbebbc3a3b1b108d7e86 Mon Sep 17 00:00:00 2001
From: Justin Bradfield <bradfield.justin7@gmail.com>
Date: Sat, 9 May 2026 00:43:12 -0500
Subject: [PATCH 3/4] Update console/src/components/McpConnectInstructions.tsx

Co-authored-by: Qindeel Ishtiaq <qindeeli@gmail.com>
---
 console/src/components/McpConnectInstructions.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/console/src/components/McpConnectInstructions.tsx b/console/src/components/McpConnectInstructions.tsx
index f4ebab41bc8bc..056f1a5d5a074 100644
--- a/console/src/components/McpConnectInstructions.tsx
+++ b/console/src/components/McpConnectInstructions.tsx
@@ -96,7 +96,7 @@ const McpConnectInstructions = ({
         <Text textStyle="heading-xs">1. Get your MCP token</Text>
 
         {isCloud && onGenerateToken && (
-          <VStack alignItems="stretch" spacing="2">
+   <VStack alignItems="stretch" spacing="4">
             <Text fontSize="sm" color={colors.foreground.secondary}>
               Generate a new token:
             </Text>

From c471887b7d51a7bc607867f49a4bd264ea9c4b1a Mon Sep 17 00:00:00 2001
From: Justin Bradfield <bradfield.justin7@gmail.com>
Date: Sat, 9 May 2026 00:44:06 -0500
Subject: [PATCH 4/4] Apply suggestions from code review

Co-authored-by: Qindeel Ishtiaq <qindeeli@gmail.com>
---
 .../src/components/McpConnectInstructions.tsx | 47 +++++++++----------
 console/src/components/copyableComponents.tsx | 10 ++--
 2 files changed, 27 insertions(+), 30 deletions(-)

diff --git a/console/src/components/McpConnectInstructions.tsx b/console/src/components/McpConnectInstructions.tsx
index 056f1a5d5a074..838033203dc69 100644
--- a/console/src/components/McpConnectInstructions.tsx
+++ b/console/src/components/McpConnectInstructions.tsx
@@ -72,31 +72,17 @@ const McpConnectInstructions = ({
   const claudeCodeCliCommand = `claude mcp add --transport http materialize-${endpoint} \\\n  ${endpointUrl} \\\n  --header "Authorization: Basic <mcp-token>"`;
 
   return (
-    <VStack
-      alignItems="stretch"
-      spacing="4"
-      p="6"
-      overflowY="auto"
-      maxHeight="60vh"
-      {...props}
-    >
+    <VStack alignItems="stretch" spacing="6" p="6" {...props}>
       <Text fontSize="sm" color={colors.foreground.secondary}>
         Connect your AI agent or coding assistant to Materialize using the
         built-in MCP server.
       </Text>
 
-    <VStack
-      alignItems="stretch"
-      spacing="6"
-      p="6"
-      overflowY="auto"
-      maxHeight="60vh"
-      {...props}
-    >
+      <VStack alignItems="stretch" spacing="4">
         <Text textStyle="heading-xs">1. Get your MCP token</Text>
 
         {isCloud && onGenerateToken && (
-   <VStack alignItems="stretch" spacing="4">
+          <VStack alignItems="stretch" spacing="4">
             <Text fontSize="sm" color={colors.foreground.secondary}>
               Generate a new token:
             </Text>
@@ -124,14 +110,23 @@ const McpConnectInstructions = ({
                 </Text>
               </VStack>
             ) : (
-              <Button
-                onClick={onGenerateToken}
-                variant="primary"
-                size="sm"
-                alignSelf="flex-start"
-              >
-                Generate MCP token
-              </Button>
+              <>
+                <Button
+                  onClick={onGenerateToken}
+                  variant="primary"
+                  size="sm"
+                  alignSelf="flex-start"
+                >
+                  Generate personal MCP token
+                </Button>
+                <Text fontSize="xs" color={colors.foreground.secondary}>
+                  For service accounts, create a{" "}
+                  <TextLink href="/access/app-passwords">
+                    service app password
+                  </TextLink>{" "}
+                  and Base64-encode it below.
+                </Text>
+              </>
             )}
           </VStack>
         )}
@@ -151,7 +146,7 @@ const McpConnectInstructions = ({
         </VStack>
       </VStack>
 
-      <VStack alignItems="stretch" spacing="3">
+      <VStack alignItems="stretch" spacing="4">
         <Text textStyle="heading-xs">2. Connect your client</Text>
         <Text fontSize="sm" color={colors.foreground.secondary}>
           See the{" "}
diff --git a/console/src/components/copyableComponents.tsx b/console/src/components/copyableComponents.tsx
index 326f6fabefda2..c4df1b9ef7540 100644
--- a/console/src/components/copyableComponents.tsx
+++ b/console/src/components/copyableComponents.tsx
@@ -126,11 +126,13 @@ export const CopyableBox: React.FC<CopyableBoxProps> = ({
         as="pre"
         fontFamily="mono"
         pl={4}
-        py={2}
+        pr={wrap ? 2 : 0}
+        py={wrap ? 3 : 2}
         flex={1}
-        lineHeight="4"
-        whiteSpace={wrap ? "pre" : "nowrap"}
-        overflow="hidden"
+        lineHeight={wrap ? "tall" : "4"}
+        whiteSpace={wrap ? "pre-wrap" : "nowrap"}
+        overflow={wrap ? "auto" : "hidden"}
+        overflowWrap={wrap ? "anywhere" : undefined}
         textOverflow={wrap ? undefined : "ellipsis"}
         minWidth={0}
         {...(maxHeight && {