From 2fd8dfc7e11c8621f862ee33917cfc9eda4da5c8 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Thu, 30 Apr 2026 04:52:17 -0400 Subject: [PATCH] docs: clarify MCP disable guidance --- README.md | 17 +++--- docs/token-optimization.md | 4 +- tests/docs/mcp-management-docs.test.js | 77 ++++++++++++++++++++++++++ 3 files changed, 87 insertions(+), 11 deletions(-) create mode 100644 tests/docs/mcp-management-docs.test.js diff --git a/README.md b/README.md index e153f773..3978ad8d 100644 --- a/README.md +++ b/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. @@ -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 diff --git a/docs/token-optimization.md b/docs/token-optimization.md index 14ee9fe8..ad5fd6ec 100644 --- a/docs/token-optimization.md +++ b/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 --- diff --git a/tests/docs/mcp-management-docs.test.js b/tests/docs/mcp-management-docs.test.js new file mode 100644 index 00000000..5dd0aa8d --- /dev/null +++ b/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}`);