Problem
McpServerRegistrar.register(...) currently catches every per-server setup exception, logs a warning and continues. Callers receive no typed result describing which configured servers are ready, failed, skipped or partially registered. Enterprise deployments therefore cannot fail fast on an invalid command, unsupported transport, initialization/authentication failure or missing required tool.
The stdio configuration also has no working-directory field. McpClientBuilder.stdioTransport(command, args, env) inherits the host JVM cwd instead of the Harness workspace/project cwd, which differs from coding-agent expectations and from workspace-scoped tools.json ownership.
Finally, McpServerConfig has request/initialization timeout but no typed reconnect/restart policy or connection health state for SSE/streamable HTTP.
Observed against e3a412ed2cc944e401da861c8d5e464b967724e9 with real stdio/SSE/streamable-HTTP fixtures. Transport discovery/call, static headers, workspace config scope and permission/HITL work; these lifecycle/readiness facts do not.
Proposed contract
Have registration return a typed immutable report, for example one entry per configured server:
- server name and transport;
- state (
READY, FAILED, SKIPPED, DEGRADED, CLOSED or equivalent);
- discovered/enabled tool names;
- stable failure category and sanitized message;
- lifecycle owner/close capability;
- reconnect policy and current connection health where applicable.
Harness builder policy should select fail-fast vs best-effort explicitly. Enterprise/sandbox production profiles can require all declared/required servers and tools to be ready; local development may opt into best-effort.
For stdio, add an optional cwd/working-directory field resolved through the Harness workspace policy. Relative cwd should be rooted and validated by WorkspaceManager/filesystem policy, not by an application host. The default behavior must be documented for compatibility.
For SSE/HTTP, expose a typed reconnect policy (disabled/fixed/exponential with bounded attempts/backoff) and observable state transitions. Reconnect execution remains owned by the MCP client/registrar, not by product hosts.
Acceptance
- Invalid command, unsupported transport, auth failure and initialization timeout produce typed failure entries.
- Strict mode fails agent bootstrap without leaving partially initialized clients/processes.
- Best-effort mode returns both ready and failed entries without hiding failures in logs.
- Required
enableTools missing from server discovery is reportable/fail-fast.
- stdio fixture observes the configured Harness workspace cwd and cannot escape workspace policy.
- SSE/HTTP disconnect/reconnect transitions are typed and bounded; close stops reconnect.
- Fresh runtime bootstrap can report readiness without a JCode registry, retry scheduler or config parser.
This is separate from MCP client close/copy ownership (#2139), though strict-mode rollback should use that lifecycle contract.
Problem
McpServerRegistrar.register(...)currently catches every per-server setup exception, logs a warning and continues. Callers receive no typed result describing which configured servers are ready, failed, skipped or partially registered. Enterprise deployments therefore cannot fail fast on an invalid command, unsupported transport, initialization/authentication failure or missing required tool.The stdio configuration also has no working-directory field.
McpClientBuilder.stdioTransport(command, args, env)inherits the host JVM cwd instead of the Harness workspace/project cwd, which differs from coding-agent expectations and from workspace-scopedtools.jsonownership.Finally,
McpServerConfighas request/initialization timeout but no typed reconnect/restart policy or connection health state for SSE/streamable HTTP.Observed against
e3a412ed2cc944e401da861c8d5e464b967724e9with real stdio/SSE/streamable-HTTP fixtures. Transport discovery/call, static headers, workspace config scope and permission/HITL work; these lifecycle/readiness facts do not.Proposed contract
Have registration return a typed immutable report, for example one entry per configured server:
READY,FAILED,SKIPPED,DEGRADED,CLOSEDor equivalent);Harness builder policy should select fail-fast vs best-effort explicitly. Enterprise/sandbox production profiles can require all declared/required servers and tools to be ready; local development may opt into best-effort.
For stdio, add an optional
cwd/working-directory field resolved through the Harness workspace policy. Relative cwd should be rooted and validated byWorkspaceManager/filesystem policy, not by an application host. The default behavior must be documented for compatibility.For SSE/HTTP, expose a typed reconnect policy (disabled/fixed/exponential with bounded attempts/backoff) and observable state transitions. Reconnect execution remains owned by the MCP client/registrar, not by product hosts.
Acceptance
enableToolsmissing from server discovery is reportable/fail-fast.This is separate from MCP client close/copy ownership (#2139), though strict-mode rollback should use that lifecycle contract.