feat(mcp): add live connection diagnostic tracing

[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

Add a Den-side diagnostic mode that traces an enterprise MCP connection live, identifies the first failing layer without losing the highest proven health level, and produces support-safe evidence without exposing credentials, provider payloads, session IDs, tool arguments, or customer content.

What changed

Area	Change
Persisted diagnostics	Adds tenant-scoped attempts and ordered events with immutable first failure, highest health, safe evidence, action owner, retryability, remediation, and 24-hour retention.
Live execution	Adds a subscriber-independent background runner, admin-only start/SSE/snapshot routes, reconnect replay, and terminal-state guards. A disconnected or absent UI cannot stop the diagnostic.
Den UI	Adds a Diagnose action and live modal showing phase outcomes/timings, highest health, first failure, redacted evidence, explicit authorization continuation, and retry to Catalog Ready.
OAuth consistency	Binds encrypted single-use PKCE grants and stable DCR client revisions to signed state; uses atomic attempt leases/generations and credential-write fencing across callback/timeout races.
SDK parity	Preserves production OAuth discovery fallbacks, Microsoft tenant OIDC, 401 refresh/retry, 403 scope/ACL behavior, supported MCP revisions, and request-specific phase/remediation.
Transport safety	Adds one lifecycle deadline, bounded streaming bodies/catalogs/schemas/cursors, bounded close, per-hop redirect policy, discarded-body cancellation, and structural IPv6 embedded-address protection.
Schema	Adds migration 0034_famous_nekra for attempts, events, pending OAuth grants, registration leases, client revisions, and ordered event uniqueness.

Security and correctness

• Diagnostic evidence is allowlisted and structured; callback query parameters are redacted before request logging.
• Hosted URLs require HTTPS and reject private/metadata pivots, mapped/compatible IPv6, private NAT64 embeddings, downgrade, credentialed URLs, and cross-origin body replay.
• Sensitive auth, cookie, API-key, MCP session, and resume headers are stripped across origins.
• Every non-returned response body is canceled; exact live probes show zero active I/O after status, size, and malformed-redirect failures.
• Callback deadlines abort the SDK token exchange itself. A losing or stale callback cannot write credentials, rotate the client, or retain a grant.
• OAuth discovery and refresh remain SDK-controlled and observable: tracing does not change whether a production-valid server succeeds.
• Catalog Ready proves initialization and the complete bounded tool catalog only; it does not claim that a provider operation or mutation was tested.
• DEN_API_PUBLIC_URL is propagated through Turbo so local/hub OAuth callbacks target Den API rather than Den Web.

Reviewer focus

• external-mcp-diagnostic-runner.ts and external-mcp-diagnostics.ts
• callback lease/credential fencing in external-mcp-connections.ts, external-mcp-client.ts, and oauth-credentials.ts
• diagnostic routes and request-log redaction
• migration 0034_famous_nekra and tenant/sequence indexes
• live diagnostic dialog/SSE reconnect behavior
• guarded transport and production SDK parity fixtures

Validation

• Final Den API matrix: 119 tests / 291 assertions
• Final Den Web matrix: 7 tests / 26 assertions
• Exact live probes for callback timeout/no-write, DCR A/B interleaving, no-subscriber execution, disconnect/reconnect, Microsoft OIDC fallback, 401 refresh, scope vs ACL 403, token-phase fidelity, body cancellation, and mapped/compatible/NAT64 URL+DNS rejection
• @openwork/types, Den DB, Den API, and Den Web production builds
• Den API and Den Web TypeScript checks
• Clean upstream 0033 bootstrap → branch 0034 migration replay: 34 ledger entries, three diagnostic tables, required columns, and two-column attempt/sequence uniqueness
• Post-rebase Fraimz: 1 flow / 0 failures / 5 validated frames, plus setup, cleanup, and voiceover coverage
• Independent hub runtime proof that generated OAuth callbacks target Den API public origin
• git diff --check
• ./bin/openwork-hub check mcp mcp-live-diagnostic-tracing

Follow-ups

• Make the background runner and not-yet-delivered authorization URL recoverable across process restarts/instances.
• Add an explicit per-org/member concurrency and rate limit; authorization waits currently poll persisted state while active.
• Deduplicate possible completion audit records emitted by both callback terminal paths and runner cleanup.
• Cancel every browser SSE body on protocol errors and add Last-Event-ID resume rather than full snapshot replay.

This is the third of three independent MCP diagnostic PRs. It is based directly on dev; overlapping MCP transport/client surfaces with the structured-diagnostics and enterprise-mock PRs 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:52pm

[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 3e84bd3 and was exercised in the independent combined rehearsal, #2675.

The rehearsal confirmed post-OAuth resource-phase classification, diagnostic deletion and start-race cleanup, runner cancellation and recovery audit behavior, callback stability, and a visible Catalog Ready scope boundary that does not imply provider-operation readiness.

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.