refactor(registry/coder/modules/claude-code): make workdir optional and scope MCP to user

workdir is now optional. When set, the module still pre-creates the
directory and pre-accepts the Claude Code trust dialog for it. When
unset, the module installs the CLI and configures authentication only;
users accept trust dialogs interactively per project.

MCP servers are added at Claude Code's user scope via `claude mcp
add-json --scope user` so they are available across every project the
workspace owner opens, instead of being tied to a single project
directory. For project-local MCP servers, callers should commit a
`.mcp.json` to the project repository rather than passing it through
this module.

Drop primaryApiKey from the standalone-mode config writer. Claude Code
reads credentials from the ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN
env vars (which the module already exports via coder_env); writing the
key into ~/.claude.json had no effect on authentication.

Split the standalone-mode .claude.json writer into two steps: the
always-on auth/onboarding keys, and the optional `.projects[workdir]`
trust block that only runs when workdir is set.

Author: matifali

registry/coder/modules/claude-code/README.md

@@ -15,11 +15,18 @@ module "claude-code" {
   source            = "registry.coder.com/coder/claude-code/coder"
   version           = "5.0.0"
   agent_id          = coder_agent.main.id
-  workdir           = "/home/coder/project"
   anthropic_api_key = "xxxx-xxxxx-xxxx"
 }
 ```
 
+## workdir
+
+`workdir` is optional. When set, the module pre-creates the directory if it is missing and pre-accepts the Claude Code trust/onboarding prompt for it in `~/.claude.json`. Leave `workdir` unset if you only want the module to install the CLI and configure authentication; users can still open any project interactively and accept the trust dialog per project.
+
+## MCP scope
+
+Servers configured through `mcp` or `mcp_config_remote_path` are added at Claude Code's [user scope](https://docs.claude.com/en/docs/claude-code/mcp#scope), which makes them available across every project the workspace owner opens. For project-local MCP servers, commit a `.mcp.json` file to the project repository instead of passing it through this module.
+
 ## Prerequisites
 
 Provide exactly one authentication method:

registry/coder/modules/claude-code/main.test.ts

@@ -343,10 +343,10 @@ describe("claude-code", async () => {
 
     // Should contain the MCP server add command from the successful fetch.
     expect(installLog).toContain(
-      "Added stdio MCP server go-language-server to local config",
+      "Added stdio MCP server go-language-server to user config",
     );
     expect(installLog).toContain(
-      "Added stdio MCP server typescript-language-server to local config",
+      "Added stdio MCP server typescript-language-server to user config",
     );
 
     // Verify the MCP config was added to .claude.json.
@@ -380,7 +380,6 @@ describe("claude-code", async () => {
       "/home/coder/.claude.json",
     );
     const parsed = JSON.parse(claudeConfig);
-    expect(parsed.primaryApiKey).toBe(apiKey);
     expect(parsed.autoUpdaterStatus).toBe("disabled");
     expect(parsed.hasCompletedOnboarding).toBe(true);
     expect(parsed.bypassPermissionsModeAccepted).toBe(true);
@@ -405,8 +404,9 @@ describe("claude-code", async () => {
     expect(installLog).toContain("Standalone mode configured successfully");
     expect(installLog).not.toContain("skipping onboarding bypass");
 
-    // Onboarding bypass flags must be present; primaryApiKey is unused when
-    // auth happens via CLAUDE_CODE_OAUTH_TOKEN.
+    // Onboarding bypass flags must be present. Authentication happens via
+    // the ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN env vars, not via
+    // .claude.json.
     const claudeConfig = await readFileContainer(
       id,
       "/home/coder/.claude.json",

registry/coder/modules/claude-code/main.tf

@@ -26,7 +26,8 @@ variable "icon" {
 
 variable "workdir" {
   type        = string
-  description = "Project directory to pre-configure for Claude Code. The module creates this directory if it is missing, registers MCP servers against it, and pre-accepts the trust/onboarding prompts for it in ~/.claude.json."
+  description = "Optional project directory. When set, the module pre-creates it if missing and pre-accepts the Claude Code trust/onboarding prompt for it in ~/.claude.json."
+  default     = null
 }
 
 variable "pre_install_script" {
@@ -73,13 +74,13 @@ variable "model" {
 
 variable "mcp" {
   type        = string
-  description = "JSON-encoded string to configure MCP servers for Claude Code. When set, writes MCP configuration into the Claude Code local scope."
+  description = "JSON-encoded string of MCP server configurations. When set, servers are added at Claude Code's user scope so they are available across every project the workspace owner opens."
   default     = ""
 }
 
 variable "mcp_config_remote_path" {
   type        = list(string)
-  description = "List of URLs that return JSON MCP server configurations (text/plain with valid JSON)"
+  description = "List of URLs that return JSON MCP server configurations (text/plain with valid JSON). Servers are added at Claude Code's user scope."
   default     = []
 }
 
@@ -163,7 +164,7 @@ resource "coder_env" "anthropic_base_url" {
 }
 
 locals {
-  workdir = trimsuffix(var.workdir, "/")
+  workdir = var.workdir != null ? trimsuffix(var.workdir, "/") : ""
   install_script = templatefile("${path.module}/scripts/install.sh.tftpl", {
     ARG_CLAUDE_CODE_VERSION    = var.claude_code_version
     ARG_INSTALL_CLAUDE_CODE    = tostring(var.install_claude_code)

registry/coder/modules/claude-code/main.tftest.hcl

@@ -270,3 +270,16 @@ run "test_script_outputs_with_pre_and_post" {
     error_message = "scripts output should list pre_install, install, post_install in run order"
   }
 }
+
+run "test_workdir_optional" {
+  command = plan
+
+  variables {
+    agent_id = "test-agent-no-workdir"
+  }
+
+  assert {
+    condition     = var.workdir == null
+    error_message = "workdir should default to null when omitted"
+  }
+}

registry/coder/modules/claude-code/scripts/install.sh.tftpl

@@ -38,8 +38,8 @@ function add_mcp_servers() {
 
   while IFS= read -r server_name && IFS= read -r server_json; do
     echo "------------------------"
-    echo "Executing: claude mcp add-json \"$${server_name}\" '$${server_json}' ($${source_desc})"
-    claude mcp add-json "$${server_name}" "$${server_json}" || echo "Warning: Failed to add MCP server '$${server_name}', continuing..."
+    echo "Executing: claude mcp add-json --scope user \"$${server_name}\" '$${server_json}' ($${source_desc})"
+    claude mcp add-json --scope user "$${server_name}" "$${server_json}" || echo "Warning: Failed to add MCP server '$${server_name}', continuing..."
     echo "------------------------"
     echo ""
   done < <(echo "$${mcp_json}" | jq -r '.mcpServers | to_entries[] | .key, (.value | @json)')
@@ -113,7 +113,7 @@ function install_claude_code_cli() {
 }
 
 function setup_claude_configurations() {
-  if [ ! -d "$${ARG_WORKDIR}" ]; then
+  if [ -n "$${ARG_WORKDIR}" ] && [ ! -d "$${ARG_WORKDIR}" ]; then
     echo "Warning: The specified folder '$${ARG_WORKDIR}' does not exist."
     echo "Creating the folder..."
     mkdir -p "$${ARG_WORKDIR}"
@@ -124,28 +124,22 @@ function setup_claude_configurations() {
   mkdir -p "$${module_path}"
 
   if [ "$${ARG_MCP}" != "" ]; then
-    (
-      cd "$${ARG_WORKDIR}"
-      add_mcp_servers "$${ARG_MCP}" "in $${ARG_WORKDIR}"
-    )
+    add_mcp_servers "$${ARG_MCP}" "from module input"
   fi
 
   if [ -n "$${ARG_MCP_CONFIG_REMOTE_PATH}" ] && [ "$${ARG_MCP_CONFIG_REMOTE_PATH}" != "[]" ]; then
-    (
-      cd "$${ARG_WORKDIR}"
-      for url in $(echo "$${ARG_MCP_CONFIG_REMOTE_PATH}" | jq -r '.[]'); do
-        echo "Fetching MCP configuration from: $${url}"
-        mcp_json=$(curl -fsSL "$${url}") || {
-          echo "Warning: Failed to fetch MCP configuration from '$${url}', continuing..."
-          continue
-        }
-        if ! echo "$${mcp_json}" | jq -e '.mcpServers' > /dev/null 2>&1; then
-          echo "Warning: Invalid MCP configuration from '$${url}' (missing mcpServers), continuing..."
-          continue
-        fi
-        add_mcp_servers "$${mcp_json}" "from $${url}"
-      done
-    )
+    for url in $(echo "$${ARG_MCP_CONFIG_REMOTE_PATH}" | jq -r '.[]'); do
+      echo "Fetching MCP configuration from: $${url}"
+      mcp_json=$(curl -fsSL "$${url}") || {
+        echo "Warning: Failed to fetch MCP configuration from '$${url}', continuing..."
+        continue
+      }
+      if ! echo "$${mcp_json}" | jq -e '.mcpServers' > /dev/null 2>&1; then
+        echo "Warning: Invalid MCP configuration from '$${url}' (missing mcpServers), continuing..."
+        continue
+      fi
+      add_mcp_servers "$${mcp_json}" "from $${url}"
+    done
   fi
 
 }
@@ -163,15 +157,11 @@ function configure_standalone_mode() {
   if [ -f "$${claude_config}" ]; then
     echo "Updating existing Claude configuration at $${claude_config}"
 
-    jq --arg workdir "$${ARG_WORKDIR}" --arg apikey "$${ANTHROPIC_API_KEY:-}" \
-      '.autoUpdaterStatus = "disabled" |
+    jq '.autoUpdaterStatus = "disabled" |
         .autoModeAccepted = true |
         .bypassPermissionsModeAccepted = true |
         .hasAcknowledgedCostThreshold = true |
-        .hasCompletedOnboarding = true |
-        .primaryApiKey = $apikey |
-        .projects[$workdir].hasCompletedProjectOnboarding = true |
-        .projects[$workdir].hasTrustDialogAccepted = true' \
+        .hasCompletedOnboarding = true' \
       "$${claude_config}" > "$${claude_config}.tmp" && mv "$${claude_config}.tmp" "$${claude_config}"
   else
     echo "Creating new Claude configuration at $${claude_config}"
@@ -181,18 +171,19 @@ function configure_standalone_mode() {
   "autoModeAccepted": true,
   "bypassPermissionsModeAccepted": true,
   "hasAcknowledgedCostThreshold": true,
-  "hasCompletedOnboarding": true,
-  "primaryApiKey": "$${ANTHROPIC_API_KEY:-}",
-  "projects": {
-    "$${ARG_WORKDIR}": {
-      "hasCompletedProjectOnboarding": true,
-      "hasTrustDialogAccepted": true
-    }
-  }
+  "hasCompletedOnboarding": true
 }
 EOF
   fi
 
+  if [ -n "$${ARG_WORKDIR}" ]; then
+    echo "Pre-accepting trust dialog for $${ARG_WORKDIR}"
+    jq --arg workdir "$${ARG_WORKDIR}" \
+      '.projects[$workdir].hasCompletedProjectOnboarding = true |
+        .projects[$workdir].hasTrustDialogAccepted = true' \
+      "$${claude_config}" > "$${claude_config}.tmp" && mv "$${claude_config}.tmp" "$${claude_config}"
+  fi
+
   echo "Standalone mode configured successfully"
 }