---
id: 10824
title: Audit MCP env vars for config substrate cleanup
state: CLOSED
labels:
  - enhancement
  - ai
  - refactoring
  - architecture
  - model-experience
assignees:
  - neo-gpt
createdAt: '2026-05-06T16:10:43Z'
updatedAt: '2026-05-06T21:41:33Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10824'
author: neo-gpt
commentsCount: 0
parentIssue: 10822
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-06T21:41:32Z'
---
# Audit MCP env vars for config substrate cleanup

## Context

Epic #10822 graduated Discussion #10819 into the config substrate cleanup track. Phase 1 AC1 requires an audit that classifies every environment-variable read across `ai/mcp/server/**` before the swarm deletes aliases, introduces the Tier 1 shared config, or restores `config.mjs` delta-merge as the primary non-env extensibility path.

This ticket exists because Phase 1 #2 is already filed as #10823, but deletion should consume an explicit inventory rather than infer scope from resolver-local grep. Claude's A2A lane handoff (`MESSAGE:ecb64615-491c-4a87-bd9d-b735bcd4a5d0`) assigned this read-only audit lane to @neo-gpt.

Duplicate sweep evidence:
- Knowledge Base semantic ticket sweep for `duplicate ticket env-var audit classify config substrate cleanup AC1` returned no relevant documents.
- GitHub exact sweeps found #10822 and #10823, but no standalone AC1 inventory ticket.
- Local grep found the AC1 parent text in `resources/content/issues/issue-10822.md:99`.

## The Problem

The current config substrate mixes at least five env-var roles in one surface: secrets, runtime binding, identity/session binding, single-writer process role, and operator one-shot toggles. It also carries dev-branch-only aliases and config-key fallbacks that are scheduled for hard deletion under #10823.

Without an explicit inventory, follow-up PRs can accidentally delete boot-critical env reads too early, leave dead aliases behind, or move values into the wrong tier of the three-tier model. The audit is the dependency that turns KISS deletion into a controlled substrate change.

## The Architectural Reality

Empirical starter scan on current `dev`:
- `rg "process\\.env\\.[A-Z0-9_]+|process\\.env\\[[^\\]]+\\]" ai/mcp/server` finds reads in Memory Core, Knowledge Base, and shared server services.
- `ai/mcp/server/shared/helpers/DeploymentConfig.mjs:23` resolves `MCP_HTTP_PORT` with legacy `SSE_PORT`.
- `ai/mcp/server/shared/helpers/DeploymentConfig.mjs:67` and `:89` resolve Chroma host/port with optional legacy env-var names.
- `ai/mcp/server/memory-core/helpers/EmbeddingProviderConfig.mjs:12` resolves canonical and legacy embedding-provider inputs.
- `ai/mcp/server/knowledge-base/config.template.mjs:141` still reads both `NEO_MEMORY_DB_PATH` and `NEO_MEMORY_CORE_DB_PATH`.
- `ai/mcp/server/shared/services/TransportService.mjs:112` still reads bare `HOST`, which needs classification rather than blind deletion.

The target classification is defined by #10822: keep env vars only when they belong to secrets, runtime-binding, identity-binding, single-writer-process-role, multi-tenant-isolation, or operator-one-shot-toggle roles. Everything else should move to Tier 1 shared config or Tier 2 per-server config, or be deleted.

## The Fix

Produce a markdown audit table, committed with the implementation PR, covering every env-var read under `ai/mcp/server/**`.

Required table columns:

| env var | current readers | target tier | deletion/keep rationale |
|---|---|---|---|

The audit must distinguish canonical env vars from legacy aliases and must explicitly call out reads that are not direct `process.env.NAME` dot-access, such as indexed legacy env reads.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback / Edge Case | Docs | Evidence |
|---|---|---|---|---|---|
| Env-var inventory for `ai/mcp/server/**` | #10822 AC1 + operator KISS/v13 direction | Complete markdown table classifying every env-var read into the target tier model | If a read cannot be classified confidently, mark it `needs-design` with the owning file and rationale instead of guessing | PR body links the table and summarizes keep/delete counts | `rg` command output plus reviewed source paths |
| Alias deletion dependency | #10822 AC2 + #10823 | #10823 consumes the audit output before deleting aliases | Deletion PR must not remove boot-critical vars before Phase 1.5 substrate is active per #10822 AC14 | Cross-link from #10823 or PR body | Audit table rows for each alias |

## Acceptance Criteria

- [ ] Every `process.env.*` and `process.env[...]` read under `ai/mcp/server/**` is represented in the table.
- [ ] Every row includes current reader path(s), target tier, and deletion/keep rationale.
- [ ] The table explicitly marks legacy/deprecated aliases targeted by #10823.
- [ ] The table explicitly marks boot-critical env vars that must survive until Phase 1.5 config substrate is active per #10822 AC14.
- [ ] The PR body includes the exact scan command(s) used and a short count summary by target tier.
- [ ] No alias deletion or resolver behavior change lands in this ticket's PR.

## Out of Scope

- Deleting aliases or flattening resolvers. That belongs to #10823 and later #10822 AC12 work.
- Creating the Tier 1 shared config module.
- Implementing the boot-time validator.
- Operator-side `.env` migration across harnesses.

## Avoided Traps

- **Blind deletion from grep output:** env-var reads have different roles; some are secrets or runtime binding and should stay env-backed.
- **Framework-style deprecation chains:** the audit should not preserve aliases just because they exist; dev-branch-only aliases are not released-version compatibility.
- **Moving secrets into config files:** secrets remain env territory.

## Related

- Parent: #10822
- Feeds: #10823
- Originating Discussion: #10819
- Origin A2A Message: `MESSAGE:ecb64615-491c-4a87-bd9d-b735bcd4a5d0`

## Handoff Retrieval Hints

- `query_raw_memories(query="config substrate cleanup KISS three-tier env-var audit")`
- `query_raw_memories(query="Phase 1 env var audit classify every process.env ai/mcp/server")`
- GitHub archaeological source: Discussion #10819 and Epic #10822

## Timeline

- 2026-05-06T16:10:45Z @neo-gpt added the `enhancement` label
- 2026-05-06T16:10:46Z @neo-gpt added the `ai` label
- 2026-05-06T16:10:46Z @neo-gpt added the `refactoring` label
- 2026-05-06T16:10:46Z @neo-gpt added the `architecture` label
- 2026-05-06T16:10:46Z @neo-gpt added the `model-experience` label
- 2026-05-06T16:11:34Z @neo-gpt added parent issue #10822
- 2026-05-06T16:19:43Z @neo-gpt cross-referenced by #10822
- 2026-05-06T16:21:06Z @neo-gpt assigned to @neo-gpt
- 2026-05-06T16:29:06Z @neo-gpt cross-referenced by PR #10831
- 2026-05-06T17:44:24Z @neo-gpt referenced in commit `691ab0a` - "docs(agentos): audit MCP env-var substrate (#10824)"
- 2026-05-06T21:36:23Z @neo-gpt referenced in commit `8d930a8` - "chore(agentos): remove ticket sync noise (#10824)"
- 2026-05-06T21:41:33Z @tobiu closed this issue
- 2026-05-06T21:41:33Z @tobiu referenced in commit `6a498f4` - "docs(agentos): audit MCP env-var substrate (#10824) (#10831)

* docs(agentos): audit MCP env-var substrate (#10824)

* chore: ticket sync [skip ci]

* chore(agentos): remove ticket sync noise (#10824)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"

