Hard-cut built-in MC and KB clients to canonical HTTP

Context

At origin/dev@85be75ab12200e5ae57df38fe3b111ad8942605d, ai/mcp/client/config.mjs still declares the built-in Memory Core and Knowledge Base clients as stdio commands. The literal repo CLI path therefore starts a checkout-local server instead of consuming the canonical Docker plane through loopback ingress.

The canonical local topology already publishes authenticated MC/KB Streamable HTTP at 127.0.0.1:3102, and src/ai/fleet/mcpServers.mjs already owns the remote credential slot as REMOTE_MCP_CREDENTIAL_ENV_VAR (NEO_MCP_REMOTE_TOKEN). The repository-workflow credential is a separate authority and must not be substituted.

This is the one-PR client-default leaf of the larger machine cutover. It does not replay the cutover or close its parent.

Live latest-open sweep: checked the newest 20 open issues and the latest 30 A2A messages at 2026-08-08T10:23Z. No equivalent ticket or competing claim exists; #16671 owns deploy-composition admission, not repo-client transport defaults.

Structure-map result: ai/mcp/client is the owning folder, with the existing Client.mjs, config.mjs, CLI, and bridge siblings. No new file or ownership move is needed.

The Problem

The built-in defaults contradict the accepted single-plane topology:

• an unconfigured MC/KB client can spawn another host process and observe or mutate a different store;
• the generic remote transports accept static transportOptions, but there is no instance-scoped, just-in-time Bearer injection contract;
• storing a resolved token in the shared client config would leak authority across instances;
• accepting both a literal Authorization header and an environment slot would create two competing authorities; and
• replacing every stdio default would erase intentional host-local capabilities such as Neural Link.

The parent #16167 ledger names GH_TOKEN for these rows. That spelling is obsolete: the canonical remote-plane credential is NEO_MCP_REMOTE_TOKEN, while GH_TOKEN remains repository workflow authority.

The Architectural Reality

• Neo.ai.mcp.client.Client#createTransport() owns SDK transport construction.
• Client#loadServerConfig() maps one built-in server row onto one client instance.
• ai/mcp/client/config.mjs owns the repo-native default server map.
• src/ai/fleet/mcpServers.mjs owns the canonical remote MCP credential environment name.
• ADR 0019 requires one configuration authority, use-site resolution, no shared-singleton mutation, and no fallback chain.
• ADR 0019 §10.7 keeps MC/KB behind authenticated loopback HTTP while Neural Link remains a host-edge capability.

The Fix

1. Add a nullable bearerTokenEnvVar client config.
2. For SSE and Streamable HTTP only, resolve the named slot from the instance environment first and process.env second.
3. Clone request options and headers before injecting Authorization: Bearer …; never write the token into shared ClientConfig.
4. Fail before connection when the slot is missing or empty.
5. Reject a row that declares both bearerTokenEnvVar and a literal Authorization header.
6. Point built-in MC and KB rows at the canonical loopback ingress with REMOTE_MCP_CREDENTIAL_ENV_VAR; remove their command and args.
7. Keep Neural Link on explicit local stdio.
8. Remove the obsolete sibling-isolation spec whose subject is independently spawned MC/KB host servers.

Contract Ledger

Decision Record impact

Aligned with ADR 0019, especially §§2, 3, 5, and 10.7. No ADR amendment is required.

Acceptance Criteria

• Built-in MC and KB config rows use the exact canonical Streamable HTTP ingress URLs and contain no command or args.
• Both rows use REMOTE_MCP_CREDENTIAL_ENV_VAR; neither names or falls back to GH_TOKEN.
• Remote Bearer resolution prefers the client instance environment, then process.env, without mutating shared config.
• Missing/empty Bearer slots fail before connection.
• A literal Authorization header plus bearerTokenEnvVar fails as ambiguous authority.
• SSE and Streamable HTTP receive cloned remote options; stdio behavior remains unchanged.
• Neural Link remains an explicit local stdio client.
• The obsolete independently-spawned MC/KB isolation spec is removed.
• Focused client transport/config unit coverage is green.
• Authenticated routed KB and MC probes reach neo-local-canonical; transient service saturation is reported separately and is not misclassified as token failure.

Out of Scope

• Rebuilding or restarting the canonical container cohort.
• MC heap saturation, healthcheck-process distortion, backup, or restore.
• Fleet-generated seat adapters and provisioning templates already delivered by #16181 and #16205.
• Deploy-pipeline composition admission owned by #16671.
• Removing stdio from file-system, repository-workflow, or Neural Link families.
• Closing the broader cutover, deletion ledger, roadmap, reboot, or persistence ACs in parent #16167.

Avoided Traps

• No credential literal in config or durable state.
• No GH_TOKEN compatibility fallback.
• No universal no-stdio rule.
• No mutation of shared ClientConfig.
• No inference that runtimeFreshness: current proves deployed revision freshness.
• No data restore or container mutation based on a transient timeout.

Related

Parent: #16167

Related: #10900

Related: #16181

Related: #16205

Related: #16671

Origin Session ID: abdf06f7-5c90-4124-ad28-f0e2897214ee

Retrieval Hint: "repo-native MCP client defaults canonical HTTP remote credential authority"