feat(connector-mcp): declarative provider — non-fatal / lazy boot for unreachable MCP servers (ADR-0096 follow-up)

[os-zhuang]

Follow-up to #2977 / ADR-0096. Deferred enhancement identified while implementing the declarative provider factories (#2994) and the boot/reload reconcile (#3001).

Context

ADR-0096 boot materialization is intentionally fail-loud for configuration faults: unknown provider, invalid providerConfig, unresolvable credentialRef, and name conflict all abort startup. That policy is correct for authoring mistakes.

An mcp provider-bound instance, however, must connect to a remote MCP server to materialize its action handlers. Today that connection happens synchronously during boot materialization, so a transient / operational fault — the MCP server being momentarily unreachable — is indistinguishable from a config fault and aborts the whole server boot. This is why the showcase demo ships a provider: 'rest' instance (synchronous, no network at boot) rather than provider: 'mcp'.

Ask

Distinguish config-invalid (stays fatal) from remote-temporarily-unreachable (should degrade, not crash boot):

• Lazy connect: materialize the connector's def / handler surface from declared metadata without requiring a live connection at boot; establish (and cache) the MCP connection on first dispatch, with reconnect / backoff.
• or boot-time connect with a non-fatal degrade: an instance whose connection fails at boot registers in a degraded state (dispatch returns a clear error; GET /connectors surfaces the state) and re-attempts on the next reconcile / metadata:reloaded, rather than aborting startup.
• Preserve fatal behavior for genuine config faults (malformed providerConfig, unresolvable credentialRef, name conflict).
• Once resilient, upgrade the showcase to a live provider: 'mcp' instance — completing ADR-0096 D6's original intent.
• Tests: unreachable-at-boot degrades (boot survives), recovery on reconnect / reload, config-fault still fatal.

Refs

• ADR-0096 (docs/adr/0096-declarative-connector-instances.md), ADR-0024 (MCP adapter)
• feat(connectors): ADR-0096 — provider-bound declarative connector instances (#2977) #2994 (declarative provider factories), feat(automation): ADR-0096 follow-ups — runtime re-materialization + connector origin (#2977) #3001 (runtime reconcile — signature diffing, close() teardown)

[os-zhuang]

Mechanism landed — #3049 (merged, 4f8c2d1) delivers the non-fatal boot story this issue asked for:

• Config-invalid stays fatal at boot (unknown provider / bad providerConfig / unresolvable credentialRef / name conflict — unchanged).
• Remote-temporarily-unreachable now degrades instead of crashing boot: the mcp provider throws ConnectorUpstreamUnavailableError (spec), the reconcile registers an honest action-less husk (state: 'degraded' + degradedReason on GET /connectors; pointed connector_action error) — or keeps the old connector serving on a changed-config failure — and retries on an exponential backoff (5s→5min) plus on every metadata:reloaded. Recovery swaps the husk atomically.
• Lazy connect-on-first-dispatch was evaluated and rejected: MCP actions ARE the server's tools/list, so materializing without connecting would register a zero-action def — the plausible-but-dead shape ADR-0097 exists to kill. Rationale recorded in ADR-0097 §"Upstream availability".

The remaining ask — upgrading the showcase to a live provider: 'mcp' instance — is deferred to #3056 (default-preset adoption), which now owns it: the natural in-repo target (@objectstack/mcp, the platform's own endpoint) is not listening until after the automation plugin's start(), so the demo needs an in-repo MCP fixture (or a boot-ordering story) to be CI-deterministic; the degrade+retry landed here is what makes that demo safe to attempt at all. Related hardening: #3055 (declarative stdio default-deny, PR #3059).

Closing as completed.

---

Generated by Claude Code