PAI repeatedly writes MCP config to settings.json instead of ~/.claude.json

[michaelaye]

Summary

When asked to add a new MCP server, PAI consistently writes the configuration to ~/.claude/settings.json under a mcpServers key — which is a PAI-custom field that Claude Code never reads. Claude Code reads MCP server configuration exclusively from ~/.claude.json (user-scoped) or .mcp.json (project-scoped).

This has happened on every single MCP server addition across multiple sessions. The pattern:

1. User asks to add an MCP server (e.g., Bluesky)
2. PAI writes config to settings.json → mcpServers
3. Server doesn't appear in /mcp
4. Debugging reveals the config is in the wrong file
5. User has to point out the mistake — again

Root Cause

CLAUDE.md and settings.json contain a mcpServers key that looks like a valid MCP config location but is actually just a PAI-internal reference. There is no steering rule or prominent warning that tells PAI: "Claude Code MCP servers go in ~/.claude.json, NOT in settings.json."

Expected Behavior

When adding MCP servers, PAI should:

1. Use claude mcp add --scope user CLI command, OR
2. Directly edit ~/.claude.json under the top-level mcpServers key
3. Never write MCP config to settings.json

Suggested Fix

Add a prominent note in one of:

• CLAUDE.md build components
• AISTEERINGRULES.md
• CONTEXT_ROUTING.md
• Or remove the misleading mcpServers key from settings.json entirely

Something like:

MCP SERVER CONFIG: Claude Code reads MCP servers from ~/.claude.json (user) or .mcp.json (project). 
NEVER write MCP config to settings.json — it is ignored by Claude Code.
Use: claude mcp add --scope user --transport stdio <name> -- <command>

Impact

Every MCP addition fails on first attempt. User frustration compounds with each occurrence since the fix is always the same.

Environment

• PAI v4.0.0
• Claude Code (latest)
• macOS