Spike: surface warning / error content for MCP servers

[a-effort]

Explore: what content can we surface for errors / warning for MCP servers? There's no option to get info about what this warning is currently.

[a-effort]

Spike findings

LLM-assisted investigation:
Traced this through both the React app and the backend (mcpgateway @ b935ccd19). Summary: the warning in the screenshot has no backend cause to surface, and the Recent Activity feed only partially helps. There is a separate, better source for "why" that we're not reading yet.

1. The badge in the screenshot is derived client-side

src/components/servers/ServerStatusBadge.tsx:9-21 computes warning from enabled && reachable && lastSeen older than 5 minutes. There is no warning state anywhere in the backend gateway model.

So there is nothing to explain: the badge means we haven't heard from this server in 5 minutes. Suggested action: add a popover that shows this information. Content: Last seen {time} ago. (e.g. Last seen 12 minutes ago.)

More information for troubleshooting is not available currently.

2. What the activity feed will carry for MCP servers

The endpoint has landed on backend main (mcpgateway/routers/log_search.py, mappers _audit_to_activity at :355, _security_to_activity at :404).

Gateway audit rows are written at six sites in gateway_service.py: create (:2043), update (:3023, :3221), delete (:3889, :4033), and set_gateway_state (:3710).

The recurring health check reaches it via _handle_gateway_failure → set_gateway_state(activate=True, reachable=False, only_update_reachable=True), and the audit call sits inside the transition guard at :3558 (if (gateway.enabled != activate) or (gateway.reachable != reachable)). So offline/online transitions do land in the feed, one row per real transition. But as written, these things go wrong:

1. Offline transitions render green: _audit_to_activity derives status from row.success, which defaults to True, and the health-check path never passes success=False. A server dropping offline arrives as a success item.
2. The title is mangled: _RESOURCE_LABELS maps only mcp_server and a2a_agent, but the service writes resource_type="gateway"; _ACTION_VERBS has no entry for set_gateway_state. Rendered result: title "Gateway set gateway state", description "Gateway 'x' was set gateway state by system."
3. No reason text, and it's unrecoverable at that layer: on the recurring health-check path the exception is only logger.debug'd (gateway_service.py:~4875) and _handle_gateway_failure receives the gateway, not the error. The "why" is discarded before any row could carry it.

Flagging src/mocks/recentActivity.ts uses resource_type: "mcp_server" and rich prose descriptions. The real mappers produce nothing like that. This will need to be reconciled against payloads.

3. Where the error / warning exists

The Gateway model carries status, status_message, last_error, registration_attempts, and next_retry_at, and GatewayRead already exposes all of them (schemas.py:3854-3866). _finalize_pending_gateway_failure (gateway_service.py:4212) writes a sanitized error string plus a retry timestamp.

The catch: those fields are only written on the registration / pending-init lifecycle. A server that failed to register, or failed re-init after a URL/auth edit. The recurring health check neither writes them nor clears them, so they can also go stale on a server that has since recovered.

Two small blockers:

• openapi.json in this repo is stale: status_message, last_error, next_retry_at, and last_seen are all absent. Needs npm run generate against a current backend.
• MCPServer in src/types/server.ts has none of these fields.

Recommendation

Split into two tracks, as they need different fixes and have different timelines.

1. Track A: per-server "why"
   Surface status_message / last_error / next_retry_at on the server row behind an info affordance on the status badge. Popover, not Tooltip as Radix tooltips don't open on tap; copy the VisibilityInfoPopover shape. This is immediately useful for the registration-failure case, which today shows the user nothing at all. Covering offline servers too depends on the backend change below.

2. Track B: feed
   Blocked on three backend fixes: pass success=False + error_message from the failure path, add "gateway" to _RESOURCE_LABELS, add a verb for set_gateway_state. Until those land the feed shows offline transitions as green rows with garbled titles.

Filed the backend work upstream: IBM/mcp-context-forge#6342 (feed rendering) and IBM/mcp-context-forge#6343 (health-check path discards the failure reason).