diff --git a/setup-claude-os.sh b/setup-claude-os.sh
index 1cc9cf6..112f8eb 100755
--- a/setup-claude-os.sh
+++ b/setup-claude-os.sh
@@ -971,42 +971,11 @@ setup_claude_integration() {
     done
     success "Linked ${skill_count} skills"
 
-    # Configure MCP server in settings.json
-    local settings_file="${USER_CLAUDE_DIR}/settings.json"
+    # NOTE: MCP server is configured per-project when running /claude-os-init
+    # Claude Code stores MCP configs in ~/.claude.json per-project, not in settings.json
+    # The /claude-os-init command runs: claude mcp add --transport stdio code-forge ...
 
-    if [[ ! -f "$settings_file" ]]; then
-        echo "{}" > "$settings_file"
-    fi
-
-    python3 << EOF
-import json
-import os
-
-settings_file = "$settings_file"
-claude_os_dir = "$CLAUDE_OS_DIR"
-
-try:
-    with open(settings_file, 'r') as f:
-        settings = json.load(f)
-except:
-    settings = {}
-
-if 'mcpServers' not in settings:
-    settings['mcpServers'] = {}
-
-settings['mcpServers']['code-forge'] = {
-    "command": os.path.join(claude_os_dir, "venv", "bin", "python3"),
-    "args": [os.path.join(claude_os_dir, "mcp_server", "claude_code_mcp.py")],
-    "env": {
-        "CLAUDE_OS_API": "http://localhost:8051"
-    }
-}
-
-with open(settings_file, 'w') as f:
-    json.dump(settings, f, indent=2)
-EOF
-
-    success "Configured MCP server"
+    info "MCP server will be configured per-project via /claude-os-init"
 }
 
 # ═══════════════════════════════════════════════════════════════════════════
diff --git a/templates/commands/claude-os-init.md b/templates/commands/claude-os-init.md
index f8747f9..456d9b6 100644
--- a/templates/commands/claude-os-init.md
+++ b/templates/commands/claude-os-init.md
@@ -133,6 +133,42 @@ Show success message:
    - {project_name}-knowledge_docs
 ```
 
+### Step 2.5: Configure MCP Server for This Project
+
+**IMPORTANT**: Claude Code stores MCP configs per-project in `~/.claude.json`. We need to add the `code-forge` MCP server for this project so Claude can access the knowledge bases.
+
+Run the following command:
+
+```bash
+claude mcp add --transport stdio code-forge \
+  --env CLAUDE_OS_API={claude_os_url} \
+  -- {claude_os_dir}/venv/bin/python3 {claude_os_dir}/mcp_server/claude_code_mcp.py
+```
+
+**Expected output:**
+```
+Added stdio MCP server code-forge with command: .../python3 .../claude_code_mcp.py to local config
+File modified: /Users/.../.claude.json [project: {project_path}]
+```
+
+Show success:
+```
+🔌 Configuring MCP server...
+✅ MCP server 'code-forge' added for this project
+   - Tools available: mcp__code-forge__search_knowledge_base, etc.
+   - Note: Restart Claude Code to connect
+```
+
+**If the command fails** (e.g., `claude` CLI not found):
+- Show warning but continue:
+  ```
+  ⚠️  Could not auto-configure MCP server
+     Run this manually after setup:
+     claude mcp add --transport stdio code-forge \
+       --env CLAUDE_OS_API={claude_os_url} \
+       -- {claude_os_dir}/venv/bin/python3 {claude_os_dir}/mcp_server/claude_code_mcp.py
+  ```
+
 ### Step 3: Set Up Project Directory Structure
 
 Create the following structure in the project directory:
@@ -474,10 +510,11 @@ Your project is now connected to Claude OS.
    ./.claude-os/ - Config and state files
 
 📖 Next Steps:
-   1. Review and customize CLAUDE.md for your team
-   2. Add more docs anytime via UI: {claude_os_url}
-   3. Start a session: /claude-os-session start "feature name"
-   4. Let's build something amazing!
+   1. **Restart Claude Code** to connect the MCP server (exit and run `claude` again)
+   2. Review and customize CLAUDE.md for your team
+   3. Add more docs anytime via UI: {claude_os_url}
+   4. Start a session: /claude-os-session start "feature name"
+   5. Let's build something amazing!
 
 💡 Tip: With hybrid indexing, I instantly know your entire codebase structure!
    - Structural search is INSTANT (tree-sitter)