docs(mcp): improve Claude Code setup/authorization instructions (supabase#40101)

* docs: prefer project config for Claude Code

* docs: prefer CLI for Claude Code MCP installation

* docs: authentication instructions for Claude Code

* docs: update MCP authentication admonition

Not all clients automatically prompt login, and we now preselect the correct organization for project scoped MCP servers.

* fix: disable `contentEditable` on claude code codeblocks

Author: mattrossman

apps/docs/features/ui/McpConfigPanel.tsx

@@ -294,7 +294,7 @@ export function McpConfigPanel() {
         <Admonition type="note" title="Authentication" className="mt-3">
           <p>
             {
-              "Your MCP client will automatically prompt you to login to Supabase during setup. This will open a browser window where you can login to your Supabase account and grant access to the MCP client. Be sure to choose the organization that contains the project you wish to work with. In the future, we'll offer more fine grain control over these permissions."
+              "Some MCP clients will automatically prompt you to login during setup, while others may require manual authentication steps. Either authentication method will open a browser window where you can login to your Supabase account and grant organization access to the MCP client. In the future, we'll offer more fine grain control over these permissions."
             }
           </p>
           <p>

packages/ui-patterns/src/McpUrlBuilder/components/McpConfigurationDisplay.tsx

@@ -54,9 +54,16 @@ export function McpConfigurationDisplay({
         </>
       )}
 
+      {selectedClient.primaryInstructions && selectedClient.primaryInstructions(clientConfig)}
+
       {selectedClient.configFile && (
         <div className="text-xs text-foreground-light">
-          {mcpButtonData ? 'Or add' : 'Add'} this configuration to{' '}
+          {selectedClient.primaryInstructions
+            ? 'Alternatively, add'
+            : mcpButtonData
+              ? 'Or add'
+              : 'Add'}{' '}
+          this configuration to{' '}
           <code className="px-1 py-0.5 bg-surface-200 rounded">{selectedClient.configFile}</code>:
         </div>
       )}

packages/ui-patterns/src/McpUrlBuilder/constants.tsx

@@ -119,7 +119,7 @@ export const MCP_CLIENTS: McpClient[] = [
     key: 'claude-code',
     label: 'Claude Code',
     icon: 'claude',
-    configFile: '~/.claude.json',
+    configFile: '.mcp.json',
     externalDocsUrl: 'https://docs.anthropic.com/en/docs/claude-code/mcp',
     transformConfig: (config): ClaudeCodeMcpConfig => {
       return {
@@ -131,24 +131,37 @@ export const MCP_CLIENTS: McpClient[] = [
         },
       }
     },
-    alternateInstructions: (_config) => {
+    primaryInstructions: (_config) => {
       const config = _config as ClaudeCodeMcpConfig
-      const command = `claude mcp add --transport http supabase "${config.mcpServers.supabase.url}"`
+      const command = `claude mcp add --scope project --transport http supabase "${config.mcpServers.supabase.url}"`
       return (
         <div className="space-y-2">
           <p className="text-xs text-foreground-light">
-            Alternatively, add the MCP server using the command line:
+            Add the MCP server to your project config using the command line:
           </p>
           <CodeBlock
             value={command}
             language="bash"
+            focusable={false}
             // This is a no-op but the CodeBlock component is designed to output
             // inline code if no className is given
             className="block"
           />
         </div>
       )
     },
+    alternateInstructions: () => (
+      <div className="space-y-2">
+        <p className="text-xs text-foreground-light">
+          After configuring the MCP server, you need to authenticate. In a regular terminal (not the
+          IDE extension) run:
+        </p>
+        <CodeBlock value="claude /mcp" language="bash" focusable={false} className="block" />
+        <p className="text-xs text-foreground-light">
+          Select the "supabase" server, then "Authenticate" to begin the authentication flow.
+        </p>
+      </div>
+    ),
   },
 ]
 

packages/ui-patterns/src/McpUrlBuilder/types.ts

@@ -13,6 +13,7 @@ export interface McpClient {
   configFile?: string
   generateDeepLink?: (config: McpClientConfig) => string | null
   transformConfig?: (config: McpClientBaseConfig) => McpClientConfig
+  primaryInstructions?: (config: McpClientConfig) => React.ReactNode
   alternateInstructions?: (config: McpClientConfig) => React.ReactNode
 }