mcp_servers. differs from ECC recommendation (run with…

Error message

mcp_servers.${name} differs from ECC recommendation (run with --update-mcp to refresh)

What it means

In merge-mcp-config.js add-only mode, when a recommended MCP server exists in the config but its fields differ from the ECC recommendation (detected by shallow configDiffers comparison), the script skips the update and warns the user to run with --update-mcp to refresh it.

Solutions

Run the script with --update-mcp to overwrite the entry with the ECC recommendation
If the customization is intentional, ignore the warning — it is informational drift
Or manually align the TOML fields with the spec in scripts/codex/merge-mcp-config.js
Re-run the merge to confirm the entry logs `[ok]`

Example fix

// before
$ node scripts/codex/merge-mcp-config.js
[ecc-mcp] WARNING: mcp_servers.context7 differs from ECC recommendation...
// after
$ node scripts/codex/merge-mcp-config.js --update-mcp
[ecc-mcp] [ok] mcp_servers.context7

Defensive patterns

Strategy: validation

Validate before calling

const differs = (existing, recommended) =>
  Object.keys(recommended).some(k => JSON.stringify(existing[k]) !== JSON.stringify(recommended[k]));
// run with --update-mcp if differs(existingEntry, spec.fields)

Prevention

Decide whether local customizations are intentional; if not, run --update-mcp after each ECC update
Track the config file in git so drift is visible in diffs
Re-run the merge periodically and treat warnings as drift reports

When it happens

Trigger: main finds existing `mcp_servers.<name>` (hasCanonical true) and configDiffers(finalEntry, spec.fields) returns true — at least one top-level field (or array, compared by JSON) mismatches the spec — while the script runs without --update-mcp.

Common situations: User customized command/args/env of an MCP server after ECC installed it; ECC updated the recommended spec in a new release; hand-edited config missing or altering a recommended field.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/c152ac89b226125a. Report an issue: GitHub.

Appendix: source

Thrown at scripts/codex/merge-mcp-config.js:302

    if (finalEntry) {
      if (updateMcp) {
        // --update-mcp: remove existing section (and legacy alias), will re-add below
        toRemoveLog.push(`mcp_servers.${resolvedLabel}`);
        raw = removeServerFromText(raw, resolvedLabel, existing);
        if (resolvedLabel !== name) {
          raw = removeServerFromText(raw, name, existing);
        }
        if (legacyName && hasCanonical) {
          toRemoveLog.push(`mcp_servers.${legacyName}`);
          raw = removeServerFromText(raw, legacyName, existing);
        }
        toAppend.push(spec.toml);
      } else {
        // Add-only mode: skip, but warn about drift
        if (legacyName && !hasCanonical) {
          warn(`mcp_servers.${legacyName} is a legacy name for ${name} (run with --update-mcp to migrate)`);
        } else if (configDiffers(finalEntry, spec.fields)) {
          warn(`mcp_servers.${name} differs from ECC recommendation (run with --update-mcp to refresh)`);
        } else {
          log(`  [ok] mcp_servers.${name}`);
        }
      }
    } else {
      log(`  [add] mcp_servers.${name}`);
      toAppend.push(spec.toml);
    }
  }

  const hasRemovals = toRemoveLog.length > 0;

  if (toAppend.length === 0 && !hasRemovals) {
    log('All ECC MCP servers already present. Nothing to do.');
    return;
  }

  const appendText = '\n' + toAppend.join('\n\n') + '\n';

View on GitHub (pinned to 8321021c54)