docs: clarify MCP disable guidance

README.md

@@ -859,7 +859,9 @@ Windows note: the Claude config directory is `%USERPROFILE%\\.claude`, not `~/cl
 
 Claude plugin installs intentionally do not auto-enable ECC's bundled MCP server definitions. This avoids overlong plugin MCP tool names on strict third-party gateways while keeping manual MCP setup available.
 
-Copy desired MCP server definitions from `mcp-configs/mcp-servers.json` into your official Claude Code config in `~/.claude/settings.json`, or into a project-scoped `.mcp.json` if you want repo-local MCP access.
+Use Claude Code's `/mcp` command or CLI-managed MCP setup for live Claude Code server changes. Use `/mcp` for Claude Code runtime disables; Claude Code persists those choices in `~/.claude.json`.
+
+For repo-local MCP access, copy desired MCP server definitions from `mcp-configs/mcp-servers.json` into a project-scoped `.mcp.json`.
 
 If you already run your own copies of ECC-bundled MCPs, set:
 
@@ -867,7 +869,7 @@ If you already run your own copies of ECC-bundled MCPs, set:
 export ECC_DISABLED_MCPS="github,context7,exa,playwright,sequential-thinking,memory"
 ```
 
-ECC-managed install and Codex sync flows will skip or remove those bundled servers instead of re-adding duplicates.
+ECC-managed install and Codex sync flows will skip or remove those bundled servers instead of re-adding duplicates. `ECC_DISABLED_MCPS` is an ECC install/sync filter, not a live Claude Code toggle.
 
 **Important:** Replace `YOUR_*_HERE` placeholders with your actual API keys.
 
@@ -1032,13 +1034,7 @@ Official references:
 
 Too many MCP servers eat your context. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.
 
-**Fix:** Disable unused MCPs per project:
-```json
-// In your project's .claude/settings.json
-{
-  "disabledMcpServers": ["supabase", "railway", "vercel"]
-}
-```
+**Fix:** Disable unused MCPs from Claude Code with `/mcp`. Claude Code writes those runtime choices to `~/.claude.json`; `.claude/settings.json` and `.claude/settings.local.json` are not reliable toggles for already-loaded MCP servers.
 
 Keep under 10 MCPs enabled and under 80 tools active.
 </details>
@@ -1516,7 +1512,8 @@ The `strategic-compact` skill (included in this plugin) suggests `/compact` at l
 
 - Keep under 10 MCPs enabled per project
 - Keep under 80 tools active
-- Use `disabledMcpServers` in project config to disable unused ones
+- Use `/mcp` to disable unused Claude Code MCP servers; those runtime choices persist in `~/.claude.json`
+- Use `ECC_DISABLED_MCPS` only to filter ECC-generated MCP configs during install/sync flows
 
 ### Agent Teams Cost Warning
 

docs/token-optimization.md

@@ -98,8 +98,10 @@ Each enabled MCP server adds tool definitions to your context window. The README
 
 Tips:
 - Run `/mcp` to see active servers and their context cost
+- Use `/mcp` to disable Claude Code MCP servers when you want a live runtime change. Claude Code persists those runtime disables in `~/.claude.json`.
 - Prefer CLI tools when available (`gh` instead of GitHub MCP, `aws` instead of AWS MCP)
-- Use `disabledMcpServers` in project config to disable servers per-project
+- Do not rely on `.claude/settings.json` or `.claude/settings.local.json` to disable already-loaded Claude Code MCP servers; use `/mcp` for that.
+- `ECC_DISABLED_MCPS` only affects ECC-generated MCP config output during install/sync flows, such as `install.sh`, `npx ecc-install`, and Codex MCP merging. It is not a live Claude Code toggle.
 - The `memory` MCP server is configured by default but not used by any skill, agent, or hook — consider disabling it
 
 ---

tests/docs/mcp-management-docs.test.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    passed++;
+  } catch (error) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${error.message}`);
+    failed++;
+  }
+}
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
+}
+
+console.log('\n=== Testing MCP management docs ===\n');
+
+test('token optimization guide separates Claude MCP disables from ECC config filters', () => {
+  const source = read('docs/token-optimization.md');
+
+  assert.ok(
+    source.includes('Use `/mcp` to disable Claude Code MCP servers'),
+    'Token guide should direct Claude Code users to /mcp for runtime MCP disables'
+  );
+  assert.ok(
+    source.includes('Claude Code persists those runtime disables in `~/.claude.json`'),
+    'Token guide should name ~/.claude.json as the observed runtime disable store'
+  );
+  assert.ok(
+    source.includes('`ECC_DISABLED_MCPS` only affects ECC-generated MCP config output'),
+    'Token guide should scope ECC_DISABLED_MCPS to config generation'
+  );
+  assert.ok(
+    !source.includes('Use `disabledMcpServers` in project config to disable servers per-project'),
+    'Token guide should not tell users that project settings disable Claude runtime MCP servers'
+  );
+});
+
+test('README MCP guidance avoids settings.json disable instructions', () => {
+  const source = read('README.md');
+
+  assert.ok(
+    source.includes('Use `/mcp` for Claude Code runtime disables; Claude Code persists those choices in `~/.claude.json`.'),
+    'README should route runtime MCP disables through /mcp and ~/.claude.json'
+  );
+  assert.ok(
+    source.includes('`ECC_DISABLED_MCPS` is an ECC install/sync filter, not a live Claude Code toggle.'),
+    'README should explain ECC_DISABLED_MCPS scope'
+  );
+  assert.ok(
+    !source.includes('// In your project\'s .claude/settings.json\n{\n  "disabledMcpServers"'),
+    'README should not show disabledMcpServers under .claude/settings.json'
+  );
+  assert.ok(
+    !source.includes('Use `disabledMcpServers` in project config to disable unused ones'),
+    'README quick reference should not repeat stale project-config guidance'
+  );
+});
+
+if (failed > 0) {
+  console.log(`\nFailed: ${failed}`);
+  process.exit(1);
+}
+
+console.log(`\nPassed: ${passed}`);