feat(mcp): add structured connection diagnostics

[reachjalil]

Important

Parent MCP diagnostics release: #2674

Parent integration status: Not integrated. Verified by Jalil: Not started.

This source PR remains the workspace for its focused fixes and evidence. After Jalil reviews and accepts this level, the verified change will be integrated into feature/mcp-diagnostics-release and the parent ledger will be updated. Because the parent branch intentionally exists only on Jalil's fork, GitHub cannot use it as the literal base of an upstream-repository PR; this PR therefore remains based on dev while pointing to the parent release tracker.

Intent

Make MCP connection failures diagnosable end to end. Operators should see the failing phase, a stable safe error code, retry guidance, and an actionable owner without exposing credentials, provider bodies, or tenant data.

What changed

Area	Change
Diagnostic model	Added phase-specific, typed MCP diagnostics covering configuration, DNS/TCP/TLS/HTTP, OAuth, transport, initialization, catalog, execution, continuity, and shutdown.
Den API	Normalizes connection failures into safe envelopes with reference IDs, retryability, action owner, operator guidance, provider IDs, and hashed paths.
OAuth + transport	Adds bounded discovery/token/resource errors, guarded redirects, HTTPS policy, response limits, stable timeouts, and post-token MCP validation.
Catalog + search	Adds page/tool/schema/cursor/aggregate limits, bounded depth, duplicate/cycle checks, shared deadlines, concurrency limits, and hard top-20 pruning.
UI	Renders safe actionable failures and callback states while handling rejected requests without leaking raw URLs or query values.

Security and correctness

• Hosted connections require HTTPS; private-network mode is explicit, and browser HTTP remains loopback-only.
• Redirects are validated at every hop, HTTPS downgrade is rejected, cross-origin bodies are not replayed, and sensitive headers are stripped across origins.
• OAuth and MCP response bodies are capped before parsing; catalog aggregation and search fan-out have hard memory, concurrency, and wall-clock ceilings.
• Diagnostic payloads exclude tokens, cookies, raw provider bodies, raw query strings, and unredacted paths.
• Lifecycle deadlines are shared across the operation and abort active work; late workers cannot mutate returned results.

Reviewer focus

• ee/apps/den-api/src/lib/mcp-connection-diagnostics.ts
• ee/apps/den-api/src/lib/mcp-external-client.ts
• OAuth callback and agent MCP route error normalization
• MCP connection UI error and URL handling

Validation

• Den API focused suite: 166 tests / 437 assertions
• Web focused suite: 7 tests / 9 assertions
• Independent adversarial review: 126 focused tests / 273 assertions, including canonical IPv6 SSRF probes, cross-origin header stripping, shared-deadline fan-out, and cross-realm oversized bodies
• Den API and Den Web TypeScript checks
• Den API and Den Web production builds
• Fraimz proof: 3/3 frames passed, including cleanup and voiceover checks
• git diff --check
• ./bin/openwork-hub check mcp mcp-connection-diagnostics

This is the first of three independent MCP diagnostic PRs. The mock enterprise server and live tracing changes are intentionally separate; overlapping MCP client surfaces will need normal merge sequencing.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
openwork-landing	Ready	Preview, Comment, Open in v0	Jul 11, 2026 8:32pm

[vercel]

@reachjalil is attempting to deploy a commit to the Different AI Team on Vercel.

A member of the Team first needs to authorize it.

[reachjalil]

Agent integration rehearsal update — 2026-07-11

This source branch is published at 7b99407 and was exercised in the independent combined rehearsal, #2675.

The rehearsal confirmed and regression-tested the Level 1 fixes for callback origin, lifecycle and late-write fencing, stale post-token validation, owned 401 versus 403 failures, and structured provider tool-result errors.

Status remains deliberately separate:

• Agent-verified in feat(mcp): integrate diagnostics for end-to-end rehearsal #2675: yes
• Verified by Jalil: not started
• Integrated into the controlled parent feat(mcp): stage the diagnostics verification release #2674: no

This PR remains based on upstream dev because the controlled parent branch exists only on the Jalil fork. #2674 is the approval ledger; this PR is the source and evidence branch.