The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: clarify MCP disable guidance
Affaan Mustafa2fd8dfc7e11c
diff --git a/README.md b/README.mdindex e153f773d..3978ad8d0 100644--- a/README.md+++ b/README.md@@ -859,7 +859,9 @@ Windows note: the Claude config directory is `%USERPROFILE%\\.claude`, not `~/clClaude 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 Warningdiff --git a/docs/token-optimization.md b/docs/token-optimization.mdindex 14ee9fe85..ad5fd6ecb 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 READMETips:- 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.jsnew file mode 100644index 000000000..5dd0aa8d6--- /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}`);