Severity: low · Effort: S · Aspect: mcp
Goal
Either rename/re-document GET /v1/mcp-proxy/_health/:sid to make clear it reports credential-resolution status only, or extend it to perform (or cache) a real upstream reachability check, so the Console's sandbox status page doesn't show a green "ok" for an MCP server whose credential resolves but whose upstream is actually down/misconfigured.
Context & Why
The handler's own doc comment (apps/main/src/routes/mcp-proxy.ts:722-733) is candid about the limitation: "resolves each MCP server declared on a session's agent snapshot WITHOUT forwarding a real MCP call" — it only checks whether resolveProxyTargetByTenant finds a matching credential, returning status: "ok" purely on that basis (line 758: status: target ? "ok" : "unresolved"). It never makes an actual initialize/tools/list JSON-RPC call to the upstream server.
From the end-user POV (someone looking at the Console's "sandbox status" MCP health indicator, per AGENTS.md's "Health check" section: "Powers the sandbox status page's MCP health indicator"), a green "ok" naturally reads as "this MCP server is reachable and working," but it can be green even when: the upstream URL is unreachable/misspelled, the upstream is down, or the credential is present but revoked/expired server-side (only surfaces later as a 401/403 during an actual tool call, which then triggers a completely different, non-health-check code path in forwardWithRefresh). This creates a false sense of confidence exactly at the moment a user is debugging why their agent's MCP tools aren't working.
Evidence
apps/main/src/routes/mcp-proxy.ts:722-733 (doc comment) explicitly states the check is credential-presence-only.apps/main/src/routes/mcp-proxy.ts:749-759 — the actual implementation: target ? "ok" : "unresolved", no upstream fetch.AGENTS.md "Health check" section describes the endpoint to end users/integrators without this caveat: "reports ... whether its credential currently resolves" is accurate in AGENTS.md's wording, but the Console UI label (worth checking apps/console for the exact string shown) may not carry the same nuance to end users.
Suggested approach
- Cheap fix: rename the
status values from "ok"/"unresolved" to something less confidence-inspiring, e.g. "credential_resolved"/"credential_missing", and update the Console UI label/tooltip to say "credential configured" rather than implying live connectivity.
- Fuller fix: add an optional lightweight upstream probe (e.g. a JSON-RPC
initialize call with a short timeout, cached for N seconds per session+server to avoid hammering upstreams — tie into the rate-limit fix in the companion finding) and surface a third status like "unreachable" distinct from "unresolved".
- Whichever is chosen, update AGENTS.md's "Health check" section and the Console's status-page copy to match.
Validation
Configure a session with a valid vault credential pointed at a URL that returns connection-refused, hit GET /v1/mcp-proxy/_health/:sid, and confirm the response no longer claims "ok" for that server (today it does, since only credential presence is checked).
Filed by automated multi-repo audit (2026-07-16) — aspect: mcp (MCP (Model Context Protocol) integration).
Severity: low · Effort: S · Aspect: mcp
Goal
Either rename/re-document
GET /v1/mcp-proxy/_health/:sidto make clear it reports credential-resolution status only, or extend it to perform (or cache) a real upstream reachability check, so the Console's sandbox status page doesn't show a green "ok" for an MCP server whose credential resolves but whose upstream is actually down/misconfigured.Context & Why
The handler's own doc comment (
apps/main/src/routes/mcp-proxy.ts:722-733) is candid about the limitation: "resolves each MCP server declared on a session's agent snapshot WITHOUT forwarding a real MCP call" — it only checks whetherresolveProxyTargetByTenantfinds a matching credential, returningstatus: "ok"purely on that basis (line 758:status: target ? "ok" : "unresolved"). It never makes an actualinitialize/tools/listJSON-RPC call to the upstream server.From the end-user POV (someone looking at the Console's "sandbox status" MCP health indicator, per AGENTS.md's "Health check" section: "Powers the sandbox status page's MCP health indicator"), a green "ok" naturally reads as "this MCP server is reachable and working," but it can be green even when: the upstream URL is unreachable/misspelled, the upstream is down, or the credential is present but revoked/expired server-side (only surfaces later as a 401/403 during an actual tool call, which then triggers a completely different, non-health-check code path in
forwardWithRefresh). This creates a false sense of confidence exactly at the moment a user is debugging why their agent's MCP tools aren't working.Evidence
apps/main/src/routes/mcp-proxy.ts:722-733(doc comment) explicitly states the check is credential-presence-only.apps/main/src/routes/mcp-proxy.ts:749-759— the actual implementation:target ? "ok" : "unresolved", no upstream fetch.AGENTS.md"Health check" section describes the endpoint to end users/integrators without this caveat: "reports ... whether its credential currently resolves" is accurate in AGENTS.md's wording, but the Console UI label (worth checkingapps/consolefor the exact string shown) may not carry the same nuance to end users.Suggested approach
statusvalues from"ok"/"unresolved"to something less confidence-inspiring, e.g."credential_resolved"/"credential_missing", and update the Console UI label/tooltip to say "credential configured" rather than implying live connectivity.initializecall with a short timeout, cached for N seconds per session+server to avoid hammering upstreams — tie into the rate-limit fix in the companion finding) and surface a third status like"unreachable"distinct from"unresolved".Validation
Configure a session with a valid vault credential pointed at a URL that returns connection-refused, hit
GET /v1/mcp-proxy/_health/:sid, and confirm the response no longer claims"ok"for that server (today it does, since only credential presence is checked).Filed by automated multi-repo audit (2026-07-16) — aspect: mcp (MCP (Model Context Protocol) integration).