Expose session MCP inventory consistently in direct and broker modes

Problem

Applications currently need different MCP inventory APIs depending on how Mecatl is deployed:

• Direct/global mode: client.mcp.listSources(...) exposes configured sources and diagnostics.
• Broker mode: session.listMcpConnectors() exposes the session’s broker connector inventory.

Calling session.listMcpConnectors() in direct mode currently fails with mcp_connector_unavailable. An application cannot build one session-level MCP panel without understanding the deployment’s internal wiring.

We want one inventory experience across both modes, without introducing direct-mode enrollment, credential management, or server administration.

User outcome

An application can display:

• Which MCP connectors are relevant to the current session.
• Whether their catalogue is known, and its tool count when known.
• Whether a connector is deployment-managed or session-scoped.
• Whether the caller can start or manage workspace enrollment.

The application does not need to branch on “direct versus Kubernetes.” Differences appear as explicit scope and supported actions.

Proposed approach

1. Support session connector inventory in both modes

Prefer extending the existing ListSessionMcpConnectors operation and session.listMcpConnectors() SDK method rather than introducing a competing inventory API.

The server computes the inventory from the session’s applicable MCP configuration and runtime state:

• Direct/global: project the applicable configured connectors and available catalogue information.
• Broker: preserve the existing session-bound broker inventory.

A session inventory must not become an unrestricted view of deployment configuration. The server must authorize the caller and return only connector information appropriate for that session.

Keep ListMcpSources as the separate configuration/source-diagnostics API. Do not change its meaning or make clients combine it with broker inventory to construct the common view.

2. Describe management scope explicitly

Each connector should indicate whether it is:

• Deployment-managed: configuration and connection lifecycle are shared and operator-owned.
• Session-scoped: associated with the session’s broker binding.

This is descriptive metadata, not permission to mutate the connector.

Connector names remain display values, not routing handles. The response must not expose backend URLs, credentials, private binding identifiers, or configuration paths.

3. Preserve truthful catalogue observations

Retain the distinction between:

• A discovered catalogue containing zero tools.
• A hidden catalogue.
• A catalogue whose contents are unknown.

Expose a tool count only with clear semantics. Do not turn missing catalogue information into a claim that a connector has no tools.

The inventory is not a health check or authorization guarantee. Listing connectors must not:

• Probe upstream servers.
• Initiate OAuth.
• Open or replace broker attachments.
• Advance enrollment.
• Reconnect failed direct servers.

An inventory read reports available server-side information without changing MCP state.

4. Report workspace-enrollment applicability separately

Alongside connector rows, expose enough session-level information for an application to decide whether to offer the existing workspace-enrollment controls.

Distinguish at least:

• Not applicable: direct/global connectors do not use workspace enrollment.
• Applicable: the broker supports workspace enrollment; preserve its existing enrollment observation.
• Unknown/unavailable: the server cannot currently determine the relevant state.

Do not overload not_started to mean that a direct deployment needs enrollment.

Enrollment remains a whole-workspace operation, not a per-connector action. Do not add per-connector connect/retry/cancel methods.

Deployment capabilities indicate supported operations; session-level information describes their current applicability. Neither replaces authorization and eligibility checks when an operation is invoked.

Design preference: use a small, typed enrollment/applicability projection rather than a generic action framework. Exact fields and vocabulary should be agreed during the acceptance-plan stage.

Expected application behavior

Situation	Inventory presentation	Enrollment controls
Direct connector with a known catalogue	Show connector as deployment-managed and show catalogue count	None
Applicable direct connector without a known catalogue	Show unknown catalogue; do not claim healthy or empty	None
Broker workspace not enrolled	Show the broker’s declared/hidden connectors	Offer workspace enrollment when eligible
Broker enrollment pending	Show the pending aggregate observation	Offer the existing correlation-based workflow where the application holds the correlation
Broker workspace enrolled	Show the published catalogue	Preserve existing server-defined refresh eligibility
Broker snapshot temporarily unavailable	Show unavailable/unknown observation	Do not infer recovery actions from missing data

The inventory must not invent an “operator login required” diagnosis from an unknown catalogue. Such a diagnosis requires explicit server evidence and is not necessary for this issue.

Acceptance criteria

1. Direct-mode support: an authorized caller can list the session’s applicable direct MCP connectors through ListSessionMcpConnectors, without receiving an unsupported-broker error merely because the deployment uses direct mode.
2. Broker behavior preserved: the same operation continues to return the session’s broker inventory without initiating or advancing enrollment.
3. Session-appropriate visibility: unauthorized callers cannot inspect another session’s connectors, and direct-mode projection does not disclose unrelated deployment configuration.
4. Honest observations: hidden, unknown, and discovered-empty catalogues remain distinguishable. Inventory does not assert connector health, credential validity, or guaranteed tool-call success.
5. Explicit scope: clients can distinguish deployment-managed connectors from session-scoped connectors without inspecting deployment mode, server names, or transport details.
6. Enrollment applicability: direct mode is explicitly non-applicable for workspace enrollment. Broker enrollment observations retain their existing meaning. Lack of information is not reported as “not enrolled.”
7. Read-only behavior: inventory performs no upstream discovery/probes, OAuth, reconnection, enrollment mutation, or attachment creation.
8. Capability consistency: connector-inventory capability discovery reflects support in both modes. Enrollment capability remains independent; enabling inventory in direct mode does not advertise enrollment support.
9. SDK and transport parity: gRPC and HTTP expose equivalent semantics; the TypeScript SDK returns SDK-owned typed projections for both modes through the same session method.
10. Compatibility: preserve existing broker clients and define additive fields/defaults so an older server’s omitted fields cannot be misinterpreted as a positive claim about scope or enrollment applicability.
11. Documentation: explain the common inventory contract, its observation limits, the distinction from source diagnostics, and why direct-mode inventory does not imply interactive enrollment.

Out of scope

• Adding/removing MCP servers through the session API.
• Direct-mode OAuth/login or reconnect APIs.
• Changing shared credentials from a session.
• Per-user or per-session direct MCP credential isolation.
• Per-connector broker enrollment.
• Credential revocation or deployment-wide disconnect.
• Unifying enrollment with run-scoped authorization.
• Automatic polling, browser opening, or recovery in the SDK.
• A generic action/workflow framework.

Decisions to settle before implementation

1. Direct connector membership: define “applicable to the session” precisely, including configured connectors whose initial connection failed and sessions with attenuated tool access. Do not silently equate “configured globally” with “visible to every session.”
2. Observation source: identify the existing direct-mode inventory/catalogue data that can supply this projection without reconnecting or introducing a second state store.
3. Public schema: agree the smallest additive representation for management scope and enrollment applicability, including unknown/default behavior for older servers.
4. Unavailable semantics: distinguish an unsupported operation from a supported inventory whose snapshot is temporarily unavailable. Avoid using mcp_connector_unavailable for both indiscriminately.

Relevant implementation

These references describe the implementation reviewed on impl/sdk-mcp-workspace-enrollment; line numbers may drift.

• Broker-only inventory and capability gating: internal/adapter/server/connector_status.go:20–78
• Existing SDK session methods: sdk/typescript/src/client.ts:605–664
• Existing direct source/resource/prompt namespace: sdk/typescript/src/namespaces-core.ts:31–59
• Direct MCP construction: internal/app/build.go:5755–5806

Success means one session MCP panel works in both modes—not that both modes gain the same connection-management powers.

Start with internal/adapter/server/connector_status.go:20–78 and the existing session methods in sdk/typescript/src/client.ts:605–664, then review direct MCP construction in internal/app/build.go:5755–5806. Resolve the listed schema, membership, observation, and unavailable-state decisions before implementation. Done means equivalent read-only inventory semantics across direct and broker modes in gRPC, HTTP, and the TypeScript session API, with compatibility and documentation covered by the acceptance criteria.