docs: add MCP registration section with Claude Code config gotchas

Documents the correct MCP registration flow: claude mcp add --scope user
writes to ~/.claude.json (not settings.json, which silently ignores
mcpServers). Covers scope semantics, http vs sse transport requirement
for FastMCP, sequential-thinking hard requirement, and OpenBrain setup.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -228,17 +228,57 @@ Re-sync manually:
 ~/.config/mosaic/bin/mosaic-link-runtime-assets
 ```
 
-## sequential-thinking MCP Requirement
+## MCP Registration
 
-sequential-thinking MCP is a hard requirement for Mosaic Stack.
+### How MCPs Are Configured in Claude Code
 
-Use:
+**MCPs must be registered via `claude mcp add` — not by hand-editing `~/.claude/settings.json`.**
+
+`settings.json` controls hooks, model, plugins, and allowed commands. The `mcpServers` key in
+`settings.json` is silently ignored by Claude Code's MCP loader. The correct file is `~/.claude.json`,
+which is managed by the `claude mcp` CLI.
+
+```bash
+# Register a stdio MCP (user scope = all projects, persists across sessions)
+claude mcp add --scope user <name> -- npx -y <package>
+
+# Register an HTTP MCP (e.g. OpenBrain)
+claude mcp add --scope user --transport http <name> <url> \
+  --header "Authorization: Bearer <token>"
+
+# List registered MCPs
+claude mcp list
+```
+
+**Scope options:**
+- `--scope user` — writes to `~/.claude.json`, available in all projects (recommended for shared tools)
+- `--scope project` — writes to `.claude/settings.json` in the project root, committed to the repo
+- `--scope local` — default, machine-local only, not committed
+
+**Transport for HTTP MCPs must be `http`** — not `sse`. `type: "sse"` is a deprecated protocol
+that silently fails to connect against FastMCP streamable HTTP servers.
+
+### sequential-thinking MCP (Hard Requirement)
+
+sequential-thinking MCP is required for Mosaic Stack. The installer registers it automatically.
+To verify or re-register manually:
 
 ```bash
 ~/.config/mosaic/bin/mosaic-ensure-sequential-thinking
 ~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
 ```
 
+### OpenBrain Semantic Memory (Recommended)
+
+OpenBrain is the shared cross-agent memory layer. Register once per machine:
+
+```bash
+claude mcp add --scope user --transport http openbrain https://your-openbrain-host/mcp \
+  --header "Authorization: Bearer YOUR_TOKEN"
+```
+
+See [mosaic/openbrain](https://git.mosaicstack.dev/mosaic/openbrain) for setup and API docs.
+
 ## Bootstrap Any Repo
 
 Attach any repository to the Mosaic standards layer: