Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
index e153f773d..3978ad8d0 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.
</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
diff --git a/docs/token-optimization.md b/docs/token-optimization.md
index 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 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 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}`);