From 8b441c17b7a161a47bd48e18f73fca097d99209e Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Mon, 2 Mar 2026 21:31:22 -0600
Subject: [PATCH] fix: MCP servers belong in ~/.claude.json not settings.json

Claude Code reads mcpServers from ~/.claude.json (global state file),
NOT from ~/.claude/settings.json. The settings.json mcpServers key is
silently ignored for MCP loading. Using claude mcp add --scope user
writes to the correct file.

Also document correct registration commands and scope semantics in
RUNTIME.md so agents and users know how to add MCPs that actually load.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 runtime/claude/RUNTIME.md    | 23 +++++++++++++++++++++--
 runtime/claude/settings.json | 11 +----------
 2 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/runtime/claude/RUNTIME.md b/runtime/claude/RUNTIME.md
index dda6ebf..e5503ad 100644
--- a/runtime/claude/RUNTIME.md
+++ b/runtime/claude/RUNTIME.md
@@ -78,6 +78,25 @@ capture("The thing you learned", source="project/context", metadata={"type": "go
 
 Instructions in RUNTIME.md, CLAUDE.md, and MEMORY.md are insufficient — agents default to writing local MEMORY.md regardless of written rules. The PreToolUse hook is a hard technical gate that makes the correct behavior the only possible behavior.
 
-## MCP Requirement
+## MCP Configuration
 
-Claude config MUST include sequential-thinking MCP configuration managed by Mosaic runtime linking.
+**MCPs are configured in `~/.claude.json` — NOT `~/.claude/settings.json`.**
+
+`settings.json` controls hooks, model, plugins, and allowed commands.
+`~/.claude.json` is the global Claude Code state file where `mcpServers` lives.
+
+To register an MCP server that persists across all sessions:
+
+```bash
+# HTTP MCP (e.g. OpenBrain)
+claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
+
+# stdio MCP
+claude mcp add --scope user <name> -- npx -y <package>
+```
+
+`--scope user` = writes to `~/.claude.json` (global, all projects).
+`--scope project` = writes to `.claude/settings.json` in project root.
+`--scope local` = default, local-only (not committed).
+
+Do NOT add `mcpServers` to `~/.claude/settings.json` — that key is ignored for MCP loading.
diff --git a/runtime/claude/settings.json b/runtime/claude/settings.json
index 93b7ad4..4978675 100644
--- a/runtime/claude/settings.json
+++ b/runtime/claude/settings.json
@@ -236,14 +236,5 @@
     "cpan",
     "nohup"
   ],
-  "enableAllMcpTools": true,
-  "mcpServers": {
-    "sequential-thinking": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-sequential-thinking"
-      ]
-    }
-  }
+  "enableAllMcpTools": true
 }