store: Claude Code MCP user-scope config is ~/.claude.json, not ~/.claude/.mcp.json

graph/fixes/claude-code-mcp-user-scope-config-is-claudejson-not-claudemc-f01c17.md

@@ -0,0 +1,43 @@
+---
+id: f01c17f0-6641-4d11-98cb-1d182e7e98af
+type: fix
+title: "Claude Code MCP user-scope config is ~/.claude.json, not ~/.claude/.mcp.json"
+tags: [claude-code, mcp, configuration, fix, claude-home]
+importance: 0.8
+confidence: 0.8
+created: "2026-02-25T23:12:20.651207+00:00"
+updated: "2026-02-25T23:12:20.651207+00:00"
+---
+
+# Claude Code MCP User-Scope Config Location
+
+## Problem
+Confusion about where Claude Code stores user-scoped MCP server configurations. The file `~/.claude/.mcp.json` exists but is NOT the authoritative config for user-scoped servers.
+
+## Root Cause
+The actual user-scoped MCP config lives in `~/.claude.json` under the `"mcpServers"` key. The `~/.claude/.mcp.json` file appears to be a legacy or alternate config that may not be reliably loaded by Claude Code.
+
+## Fix
+Always use the `claude mcp` CLI to manage user-scoped MCP servers:
+```bash
+# Add a user-scoped MCP server
+claude mcp add -s user <name> <command> [args...]
+
+# Remove a user-scoped MCP server
+claude mcp remove -s user <name>
+
+# List all MCP servers
+claude mcp list
+```
+
+These commands write to `~/.claude.json`, which is the correct location.
+
+## Current User-Scoped Servers (as of 2026-02-25)
+- `cognitive-memory` — `python3 mcp_server.py` (local skill)
+- `n8n-mcp` — `npx n8n-mcp` (npm package)
+- `gitea-mcp` — `~/.local/bin/gitea-mcp` (local binary)
+
+## Key Takeaway
+- Correct file: `~/.claude.json` → `"mcpServers"` key
+- Wrong file: `~/.claude/.mcp.json` (do not use directly)
+- Always use `claude mcp add/remove -s user` for user-scope changes