LearnNewsExamplesServices
Frontmatter
id13933
titleCodex KB MCP client still expects GEMINI_API_KEY
stateClosed
labels
bugaitestingmodel-experience
assigneesneo-gpt
createdAtJun 23, 2026, 5:50 PM
updatedAtJun 23, 2026, 5:54 PM
githubUrlhttps://github.com/neomjs/neo/issues/13933
authorneo-gpt
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtJun 23, 2026, 5:54 PM

Codex KB MCP client still expects GEMINI_API_KEY

Closed v13.1.0/archive-v13-1-0-chunk-6 bugaitestingmodel-experience
neo-gpt
neo-gpt commented on Jun 23, 2026, 5:50 PM

Context

Post-harness-restart MCP verification on 2026-06-23 found all four live Neo MCP servers healthy, but the focused MCP client health spec still fails for the Knowledge Base bootstrap path.

Observed evidence:

  • Native mcp__neo_mjs_knowledge_base.healthcheck returned healthy/current.
  • Native query_documents and ask_knowledge_base both responded.
  • Shell env has NEO_KB_ASK_API_KEY set and GEMINI_API_KEY unset.
  • npm run test-unit -- test/playwright/unit/ai/mcp/client/McpServersHealth.spec.mjs passed 4/5 and failed only for Knowledge Base with MCP Client: Missing required environment variables for 'knowledge-base': GEMINI_API_KEY.

Live latest-open sweep: checked latest 20 open issues at 2026-06-23T15:49Z; no equivalent open ticket found. A2A in-flight sweep: checked latest 30 all-state messages at 2026-06-23T15:49Z; no active claim on this stale KB ask-key/client-config path found. KB ticket sweep: queried GEMINI_API_KEY NEO_KB_ASK_API_KEY MCP client knowledge-base requiredEnv; top hits were archived unrelated historical issues, not this current config drift.

Release classification: boardless local-harness/test hardening; live MCP service health is already green.

The Problem

The runtime architecture has moved the Knowledge Base ask-synthesis secret to the dedicated NEO_KB_ASK_API_KEY leaf, while the generic MCP client config still declares knowledge-base.requiredEnv = ["GEMINI_API_KEY"]. That makes the client health test report a false Knowledge Base failure in the intended local Codex environment.

Separately, the Codex config template forwards the local model/provider env vars but does not include NEO_KB_ASK_API_KEY, even though the Knowledge Base ask path is explicitly allowed to use that dedicated key.

The Architectural Reality

  • .codex/config.template.toml is the tracked Codex Desktop MCP template and should forward only intended local MCP env vars.
  • ai/mcp/server/knowledge-base/config.template.mjs defines askSynthesis.apiKey as leaf(null, 'NEO_KB_ASK_API_KEY', 'string').
  • ai/mcp/client/config.mjs defines the default MCP client server requirements consumed by test/playwright/unit/ai/mcp/client/McpServersHealth.spec.mjs.
  • GEMINI_API_KEY is no longer the intended Knowledge Base ask credential in this lane.

The Fix

  • Add NEO_KB_ASK_API_KEY to the Knowledge Base env forwarding list in .codex/config.template.toml.
  • Remove the stale GEMINI_API_KEY requirement from knowledge-base.requiredEnv in ai/mcp/client/config.mjs, or replace it with the actual required semantics if the client layer needs a provider-aware check.
  • Keep GEMINI_API_KEY opt-in only for explicit remote-Gemini local tests.

Contract Ledger Matrix

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
Codex KB MCP env forwarding .codex/config.template.toml + ai/mcp/server/knowledge-base/config.template.mjs Forward NEO_KB_ASK_API_KEY to the KB MCP child when present; do not forward GEMINI_API_KEY by default KB retrieval/query remains healthy; ask synthesis may degrade if no dedicated key/local ask provider is configured Existing template comments around remote Gemini opt-in Focused MCP health and native KB ask/query checks
MCP client Knowledge Base env gate ai/mcp/client/config.mjs Do not require retired shared GEMINI_API_KEY to boot Knowledge Base Server healthcheck may return degraded only if real provider config is unavailable Client health spec McpServersHealth.spec.mjs should pass without GEMINI_API_KEY

Decision Record impact

Aligned with ADR 0019: read resolved config leaves at the use site and avoid stale pass-through aliases or duplicated provider assumptions.

Acceptance Criteria

  • .codex/config.template.toml forwards NEO_KB_ASK_API_KEY to neo-mjs-knowledge-base.
  • Default MCP client config no longer requires GEMINI_API_KEY for knowledge-base startup.
  • npm run test-unit -- test/playwright/unit/ai/mcp/client/McpServersHealth.spec.mjs passes with NEO_KB_ASK_API_KEY set and GEMINI_API_KEY unset.
  • Native Knowledge Base healthcheck, query_documents, and ask_knowledge_base remain healthy/usable.

Out of Scope

  • Rotating or provisioning any secret.
  • Changing the Knowledge Base ask model/provider policy.
  • Reintroducing shared GEMINI_API_KEY forwarding for local Codex MCP servers.

Related

  • ADR 0019: learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md
  • .codex/HARNESS_RESTART.md

Origin Session ID: 02b1972b-2925-4458-89c7-287df50c726e

Handoff Retrieval Hint: NEO_KB_ASK_API_KEY GEMINI_API_KEY McpServersHealth knowledge-base requiredEnv Codex config template

tobiu referenced in commit a8a3644 - "fix(ai): align kb mcp ask key config (#13933) (#13934)" on Jun 23, 2026, 5:54 PM
tobiu closed this issue on Jun 23, 2026, 5:54 PM