[Bug]: ecm-mcp settings.json `api_key` field collision — Dispatcharr token gets overwritten by MCP key after image update, causing 401 on all channel/stream operations

[swarthyplacebo]

ECM Version

0.16.0 (latest image pull, 2026-05-14)

Priority

Priority 2: ECM is severely degraded

What is the bug?

After pulling the latest ECM image, every channel and stream operation returns 401. ECM itself starts fine and the web UI loads, but nothing that touches Dispatcharr works — GET /api/channels, GET /api/streams, M3U refresh tasks, everything.

The root cause is a field name collision in ecm-mcp:/config/settings.json. The file uses api_key for two completely different purposes depending on who's reading it:

• ECM reads api_key as its Dispatcharr REST API token
• The MCP sidecar's "Generate" flow writes the new ECM MCP key into api_key

So when you follow the post-update procedure — ECM Settings → MCP Integration → Revoke → Generate, copy the new key — you end up with the MCP key sitting in api_key. ECM then sends that to Dispatcharr and gets 401 on everything.

There are actually three distinct auth values all living in the same file:

Field in settings.json	What it's actually used for
url	Dispatcharr base URL
api_key	Dispatcharr REST API token (read by ECM to talk to Dispatcharr)
mcp_api_key	ECM MCP key (read by ecm-mcp to authenticate calls to ECM)

The README's MCP setup section and the redeployment procedure don't mention this distinction at all, so it's a very easy trap.

Steps to Reproduce

1. Pull latest ECM image: docker compose pull && docker compose up -d
2. Follow the README redeployment steps: ECM Settings → MCP Integration → Generate new API key
3. Update ecm-mcp:/config/settings.json — set api_key to the newly generated MCP key (as the README implies you should)
4. Restart ecm-mcp
5. All channel/stream operations now return 401 — ECM is authenticating to Dispatcharr with the MCP key

Workaround

settings.json needs two separate values — the Dispatcharr token in api_key must not be touched when rotating the MCP key:

# Get the correct Dispatcharr API token
docker exec -u dispatch dispatcharr psql -d dispatcharr -t -c \
  "SELECT api_key FROM accounts_user WHERE username='admin';"

# Patch settings.json: restore Dispatcharr token, leave mcp_api_key alone
docker exec ecm-mcp cat /config/settings.json | python3 -c "
import sys, json
d = json.load(sys.stdin)
d['api_key'] = 'YOUR_DISPATCHARR_TOKEN_HERE'
print(json.dumps(d, indent=2))
" > /tmp/fixed_settings.json
docker cp /tmp/fixed_settings.json ecm-mcp:/config/settings.json
docker restart ecm-mcp

Suggested Fix

Either rename the fields so they can't be confused (e.g. dispatcharr_api_key vs mcp_api_key), or at minimum add a clear note to the README's redeployment section clarifying that generating a new MCP key should only update mcp_api_key and must never touch api_key.

Additional Context

ECM version: 0.16.0
Dispatcharr: separate Docker container on same host
OS: OMV7/Debian, Docker

(Written by Claude Sonnet 4.6)

[MotWakorb]

Thanks for the detailed report — your diagnosis is correct, and this is an important catch.

Root cause confirmed: the field collision exists in our README guidance, NOT in the code. ECM and the MCP sidecar already use separate fields:

• api_key — Dispatcharr REST API token (read by ECM)
• mcp_api_key — ECM MCP key (read by ecm-mcp)

The README's MCP setup section doesn't disambiguate them clearly, so following it as written leads to overwriting api_key with the MCP key — exactly what you hit.

Workaround for anyone hitting this: the api_key field in settings.json is the Dispatcharr token and must not be touched when rotating the MCP key. The MCP key goes in mcp_api_key. Re-fetch the Dispatcharr token from Dispatcharr's accounts table (your bash one-liner) and put it back in api_key.

Tracking: filed as bd-6gm3l (P1) for v0.17.0 — README clarification + a callout box near the redeployment steps. Will also visually verify via Playwright that ECM Settings UI > MCP Integration > Generate writes to mcp_api_key (not api_key); code says it does, but eyes on it. We'll close this issue when v0.17.0 ships with the docs fix.

[MotWakorb]

Partial coverage in v0.17.0 (https://github.com/MotWakorb/enhancedchannelmanager/releases/tag/v0.17.0) — leaving this issue open because the root field-name collision is NOT yet fixed.

What v0.17.0 shipped (bd-ix1g6, backported from v0.16.1): MCP /health is now self-diagnosing when api_key_configured: false. The endpoint returns a new api_key_status field distinguishing the four ways the MCP key can appear missing (file_not_found, invalid_json, field_missing, field_empty), and the MCP Settings UI surfaces a remediation hint. This helps operators diagnose MCP-side key-missing problems without needing container shell — but it does NOT address the field-name collision this issue actually reports.

What's still pending: the api_key field in settings.json is still overloaded — used by ECM for the Dispatcharr REST API token, AND written by the MCP "Generate" flow with the MCP key. The README's redeployment section still doesn't clearly distinguish the two. Your suggested fix (rename to dispatcharr_api_key vs mcp_api_key, or at minimum a README clarification) is the right shape. Filing a follow-up bead for a future release.

Workaround in the original report is still valid.

[MotWakorb]

Fixed by PR #302 (commit a993d64) shipping in v0.17.1-0001.

Resolution: Renamed the Dispatcharr REST API token field in settings.json from api_key to dispatcharr_api_key to eliminate the long-standing name collision with mcp_api_key. The collision was the root cause operators saw when conflating the UI "API Key" label and the settings.json field name with the MCP "Generate API key" output.

Back-compat: the legacy api_key field is still read (with a one-time-per-process deprecation WARN: [CONFIG] Reading deprecated 'api_key' field as Dispatcharr token — please rename to 'dispatcharr_api_key' in settings.json) and still written in lockstep on save, so external scripts reading settings.json directly (the workaround in this issue's body) keep working. Removal target: v0.19.0 (tracked in bead bd-ewm4h).

Operator migration: existing operators see one WARN on the first start after upgrading to v0.17.1. The next save (any settings change via UI, or the next MCP key rotation) silently mirrors the value into the new canonical field. No manual settings.json edit is required, though manual cleanup is allowed once the operator confirms dispatcharr_api_key is populated.

Scope: the rename is intentionally narrow — mcp_api_key was already correctly named and is unchanged, auth_method: "api_key" is the mode name (not a field name) and is unchanged, and the v0.16.1 bd-ix1g6 MCP /health self-diagnostic is unchanged.

Security: the field-rename also closed a pre-existing credential-leak gap discovered during code review — the debug-bundle redactor in backend/routers/auto_creation.py was missing both api_key (pre-existing since v0.16.0-0004) and the new dispatcharr_api_key. Operators sharing debug bundles for support are no longer leaking raw Dispatcharr tokens.

[swarthyplacebo]

Confirmed resolved on the latest images (ecm: main-d10e910, ecm-mcp: dev-f32b0b3).

Pulled fresh images and redeployed the full ECM stack today. The /health endpoint on ecm-mcp now reports api_key_status: ok out of the box, and api_key (Dispatcharr token) and mcp_api_key (ECM MCP key) are correctly distinct in settings.json — no collision. All channel and stream operations returning 200s, Dispatcharr connected.

Thanks for the quick turnaround on this one.