Bridge Claude Desktop seats to remote MC/KB without local servers

Context

The #16167 hard cut must stop resident Memory Core and Knowledge Base stdio servers before the canonical container plane becomes the only writer. The existing remote-seat work from #15805 / PR #16053 deliberately left Claude Desktop on stdio until a secret-safe adapter was proven.

The first version of this ticket prescribed mcp-remote. Fresh falsification on 2026-07-30 corrected that implementation premise:

• Anthropic's current public-endpoint path is an account-level custom Connector. It accepts fixed request headers, including Authorization, but originates from Anthropic's cloud and cannot reach localhost or private-only networks: https://claude.com/docs/connectors/custom/remote-mcp and https://support.claude.com/en/articles/11725091-when-to-use-desktop-and-web-connectors.
• The same-machine canonical container plane therefore still needs a local command bridge for Claude Desktop; it does not need OAuth, browser callbacks, SSE fallback, cache state, dynamic package installation, or a general-purpose proxy.
• mcp-remote@0.1.38 is an experimental general bridge. A clean isolated install measured 81 packages, 7.0 MB, and 889 files; its upstream production source is roughly 2.6 kLOC. It also carries its own MCP SDK version while Neo already owns @modelcontextprotocol/sdk.
• Neo's required subset is one fixed bearer from an inherited environment slot plus MCP stdio ↔ Streamable HTTP transport. Owning that narrow bridge removes the third-party trust/dependency surface and makes protocol/session behavior reviewable in this repository.
• A live-machine census on 2026-07-30 found the current Neo Claude Desktop configs still launch MC and KB as local command entries.

Live latest-open sweep: checked the latest 20 open issues at 2026-07-30T16:32Z; no equivalent found. The closest predecessor is closed #15805, whose accepted contract explicitly deferred Claude Desktop until this proof existed. The A2A in-flight sweep found no competing claim.

The Problem

src/ai/fleet/mcpServers.mjs excludes claude-desktop from remote eligibility. ai/services/fleet/prepareManagedAgentWorkspace.mjs owns the contained claude_desktop_config.json, but rejects every remote plan for that harness before hydration.

As a result, #16167 cannot truthfully satisfy both of these properties for a current Claude Desktop resident:

1. MC and KB are served only by the canonical container plane; and
2. the resident retains MC and KB tool access.

Keeping local MC/KB servers alive preserves duplicate authority. Exposing loopback publicly merely to use the cloud Connector plane widens deployment and security scope. A narrow, repository-owned local transport bridge is the bounded boundary.

The Architectural Reality

• prepareManagedAgentWorkspace is already the single Fleet author of Claude Desktop's Neo MCP entries and owns local-to-remote transition receipts. Extend that path; do not add another config writer.
• The remote plan limits HTTP projection to Memory Core and Knowledge Base. Neural Link and other machine-local servers stay local.
• FleetLifecycleService already receives the selected plane credential and injects it under NEO_MCP_REMOTE_TOKEN. The bridge consumes that inherited slot; raw credentials must not enter generated files, argv, receipts, logs, thrown prose, or public agent state.
• Claude Desktop's generated config grammar remains command-based. For local/private Fleet endpoints, remote MC/KB render as a direct Node invocation of Neo's reviewed bridge, not as an unsupported {type:'http'} entry.
• Neo already depends on MCP SDK Streamable-HTTP and stdio transports. The bridge owns only raw JSON-RPC forwarding, one-shot initialize negotiation, sanitized terminal failure, and explicit session termination before close.
• A publicly reachable endpoint should use Claude's native custom Connector. The local bridge is a private/loopback fallback and carries a deletion trigger.

Owning folder/sibling precedent: ai/mcp/client/mcp-cli.mjs, ai/services/fleet/prepareManagedAgentWorkspace.mjs, and their direct unit specs. No new daemon or service hierarchy is needed.

The Fix

1. Add claude-desktop remote support only behind an exact installed-entrypoint grammar proof. Execute node <bridge> --help under a bounded environment and require the reviewed --url / --token-env contract before workspace mutation.
2. Render remote MC/KB entries as direct Node invocations of ai/mcp/client/stdioToStreamableHttp.mjs. Pass only the public URL and NEO_MCP_REMOTE_TOKEN slot name; never the bearer value.
3. Implement the narrow bridge over Neo's existing MCP SDK transports:
   • forward JSON-RPC bidirectionally;
   • bind the negotiated protocol version only from the first matching initialize response;
   • sanitize and deduplicate terminal errors, exit nonzero, and never surface remote response bodies;
   • on graceful EOF/signal/client close, send Streamable-HTTP session DELETE before closing transports.
4. Keep Neural Link and every non-MC/KB server in its existing local command shape.
5. Extend the existing convergence/receipt path so local → remote → local remains surgical, preserves operator-owned JSON keys, and leaves no remote residue.
6. Prove generated MC/KB entries against authenticated ephemeral Streamable-HTTP resources, including session deletion and a reflected-bearer negative fixture.
7. Document native public Connectors as the public-endpoint default and the owned bridge as the local/private fallback with an explicit retirement trigger.

Contract Ledger

Decision Record impact

Aligned with ADR 0014: wake and Neural Link host edges remain local. Depends on ADR 0019: resolved transport and credential inputs flow into the generator; the bridge does not re-read deployment policy. No ADR amendment is required unless implementation changes either boundary.

Acceptance Criteria

• Claude Desktop remote MC/KB admission executes and verifies the exact owned bridge grammar before workspace mutation.
• Generated MC/KB entries invoke Neo's reviewed bridge directly; no external proxy package, floating install, OAuth/cache state, or bearer value appears in the artifact or argv.
• Terminal transport failures emit one fixed local message, expose no remote body/token, close both sides, and exit nonzero.
• A completed or failed initialize response consumes its request marker; a reused JSON-RPC ID cannot rewrite the protocol version.
• Graceful client close/EOF/signal terminates the Streamable-HTTP session before transport close.
• Neural Link and every non-MC/KB entry remain local and unchanged.
• Local → remote → local restores the prior MC/KB stdio projection, preserves unrelated operator keys, and removes the transition receipt.
• Missing bridge, wrong grammar/proof, missing credential, malformed endpoint, and divergent operator projection fail closed before launch.
• Authenticated ephemeral MC and KB paths list/call tools through the generated bridge and return the server session map to zero after client close.
• A reflected-bearer HTTP failure proves the token/remote body absent from stderr, one terminal line, and exit code 1.
• [L4-deferred — operator handoff needed] One signed-in Claude Desktop resident consumes canonical container MC/KB while no resident MC/KB server child exists.
• Docs distinguish the native public Connector from the private/local bridge and name the bridge retirement trigger.

Out of Scope

• Provisioning Claude's account-level public Connector or OAuth flows.
• Exposing the same-machine loopback ingress publicly.
• Broad Fleet transport vocabulary cleanup (remote-http currently conflates placement with Streamable HTTP wire transport).
• Multi-seat plane-credential cardinality; #16167 must separately prove the selected provider bearer maps to each cutover resident.
• Antigravity's distinct global/per-resident config-root problem.
• Changing MC/KB server implementations or authentication modes.
• The signed host wake dispatcher from #16180.
• Remoteizing Neural Link, GitHub Workflow, GitLab Workflow, or file-system MCP.

Avoided Traps

• General proxy dependency for a narrow bridge: landing then removing an 81-package adapter adds trust, lockfile churn, and duplicate SDK authority without product value.
• Floating runtime install: no seat boot may download an unreviewed moving target.
• Secret in JSON, argv, or remote error prose: a working bridge that exposes the bearer violates the Fleet credential boundary.
• Abort without session DELETE: SDK transport close() alone does not terminate the server session.
• Initialize ID permanently armed: a later reused ID must not mutate negotiated protocol state.
• Direct-HTTP fiction: the generated Claude Desktop JSON is command-based; render what it consumes.
• Broad Fleet redesign: this is one adapter completion for a named current resident, not a new transport framework.

Related

Native parent/blocker target: #16167. Successor to closed #15805 / merged PR #16053. Sibling prerequisite: #16180. General remote/multi-machine wake product #14168 is unrelated.

Origin Session ID: 2dbbe901-1956-4f5a-96f7-822a93bbf191

Retrieval Hint: Claude Desktop owned stdio Streamable HTTP bridge NEO_MCP_REMOTE_TOKEN hard cut remote MC KB