Design: scope MCP secret providers to the owning runtime

[h3c-hexin]

Problem

Embedded hosts may keep MCP credentials in a keyring or another host-owned secret store. Supplying those values by mutating the process environment at runtime is not sound once other threads can read the environment, and it also makes secret lifetime process-global.

A process-wide callback is a useful compatibility bridge, but it still couples every engine in the process to the first installer and makes multi-runtime, multi-tenant, and isolated tests awkward.

Suggested direction

Consider an optional host-provided MCP secret provider scoped to a runtime or McpPool:

• Inject an Arc<dyn McpSecretProvider> (exact type intentionally open) when constructing the owning runtime/MCP context.
• Use one resolution seam for stdio ${...} expansion, request env_headers, bearer_token_env_var, and OAuth discovery/login/refresh headers.
• Keep process-environment fallback as an explicit compatibility policy rather than an implicit second implementation.
• Preserve the reviewed-plugin trust boundary: plugin-contributed MCPs should continue to use their captured, reviewed HostEnvironment, not an ambient host secret store.
• Keep errors and diagnostics privacy-bounded: variable names and typed outcomes may be useful; secret values must never enter logs or user-facing errors.

The provider can remain a synchronous in-memory lookup if hosts hydrate it from their keyring ahead of time. Whether an async provider, cache invalidation, zeroizing value wrapper, or per-server authorization belongs in the public contract is left open for maintainer input.

Current downstream bridge

Pinvou/CodeWhale PR #25 uses a process-wide first-install-wins resolver to remove runtime environment writes from an embedded desktop host. It is deliberately narrow and should not grow into the general lifecycle design in the downstream fork.

Non-goal

This issue is a design direction, not a complete implementation proposal or an implementation commitment from the downstream fork.

[Hmbown]

@h3c-hexin — direction accepted. Thank you for keeping Pinvou#25 as a narrow compatibility bridge instead of letting a process-wide first-install-wins callback become the lifecycle.

Current code on origin/main (a96ea6cb)

MCP ${NAME} expansion already has two sources (crates/tui/src/mcp.rs):

• reviewed-plugin servers use the captured HostEnvironment
• everything else uses std::env::var

Errors already name the variable and never echo the surrounding value. env_headers, bearer_token_env_var, and OAuth header assembly are not on that same seam yet; they still read the process environment independently.

What we will take

An optional host-provided MCP secret provider, scoped to the owning runtime / McpPool:

1. Inject an Arc at construction. Exact trait can stay small: fn get(&self, name: &str) -> Option<SecretString> (sync, in-memory). Hosts hydrate from their keyring before connect, not during spawn.
2. One resolution function for stdio ${...}, request env_headers, bearer_token_env_var, and OAuth discovery/login/refresh headers. Four call sites, one policy.
3. Process-environment fallback is an explicit compatibility policy on that function, not a second implementation hiding in std::env::var call sites.
4. Reviewed-plugin MCPs keep using their captured HostEnvironment. They must not see the host secret store. That trust boundary is not negotiable.
5. Diagnostics stay privacy-bounded: variable names and typed outcomes only. Secret values never enter logs, toasts, or anyhow chains.

What we are not taking in v1

• async provider / I/O on the connect path
• cache invalidation protocol
• zeroizing wrapper as a public type (internal zeroize is fine; don't put it on the host contract until a host needs it)
• per-server authorization matrix

A process-wide first-install-wins callback is a valid host workaround. It will not become Codewhale's public lifecycle. If an embedded host needs isolation or tests, it constructs a pool with its own Arc.

This issue stays open as the design tracker. No implementation commitment from the downstream fork is required.

[redbotster]

the process-env mutation approach has always been the weak link here, especially once you have multiple runtimes or want isolated test contexts. the Arc<dyn McpSecretProvider> direction is right. one thing worth calling out: the resolution seam you described (stdio expansion, env_headers, bearer_token_env_var, oauth) should probably be a single trait method rather than separate hooks, otherwise implementors have to wire up three or four integration points to stay consistent. also worth designing the error type early so secret names can appear in diagnostics without accidentally bubbling a resolved value through a debug impl.

for what it's worth, this is exactly the shape of problem we ran into building 1Claw (HSM-backed vault, scoped tokens per invocation, raw secret never in context or logs). a pluggable provider interface like this would let external vault integrations drop in cleanly. disclosure: i work on 1Claw.