feat(mcp): add enterprise diagnostic mock server

[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

Provide a deterministic enterprise MCP diagnostic server that can run beside an isolated Den, exercise realistic ServiceNow and Microsoft OAuth/MCP behavior, and drive a safe read-only connection test from the Den Connections UI.

What changed

Area	Change
Enterprise mock	Adds loopback-first generic, ServiceNow, Work IQ, Microsoft enterprise, and Agent 365 Mail profiles with synthetic data only.
Provider fidelity	Models ServiceNow manual client registration and provider-specific OAuth endpoints, plus pre-registered Entra tenant clients for Work IQ and Agent 365. Profile identifiers and schemas are pinned to dated primary references.
OAuth + MCP lifecycle	Exercises exact redirect/client/resource/scope/PKCE binding, one-time codes, refresh rotation, sessions, JSON and long-lived SSE, pagination, shutdown, and deterministic faults.
Den API	Adds POST /v1/mcp-connections/:connectionId/test, a credential-scoped read-only initialize/catalog/teardown probe with stable safe failures. It never starts authorization, DCRs, writes PKCE state, refreshes credentials, or invokes a tool.
Den UI	Adds a per-row Test connection action that reports protocol, catalog, page, session, and diagnostic-ID evidence without rendering credentials or raw provider failures.
Proof fixture	Adds a live ServiceNow-style OAuth→MCP Fraimz flow and a full advertised-fault matrix.

Enterprise references

• ServiceNow Quickstart MCP path, mcp_server scope, manual registration, Client Secret Post, and OAuth endpoint topology: https://www.servicenow.com/docs/r/intelligent-experiences/configure-client-connect-server.html
• Work IQ tool schemas and delegated scope: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/mcp/tool-reference and https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/work-iq/permissions
• Agent 365 Mail endpoint/tool catalog and McpServers.Mail.All manifest contract: https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-mail-work-iq and https://learn.microsoft.com/en-us/microsoft-agent-365/developer/tooling

Microsoft marks the Mail contract as preview, so the identifiers are centralized and the fixtures record their verification date.

Security and correctness

• Binds to verified loopback addresses by default; non-loopback listening requires an explicit unsafe flag.
• Requires HTTPS redirect URIs except numerically verified loopback HTTP, with exact registered URI matching.
• Validates every redirect hop, blocks private/metadata pivots, downgrade and cross-origin body replay, strips credential/session headers, and cancels every discarded body.
• Streams SSE immediately while enforcing per-response and cumulative decoded-byte limits.
• Uses one absolute lifecycle deadline through initialize, catalog, session DELETE and close; timeout fixtures prove zero active requests after settlement.
• Caps, expires, protects and redacts diagnostic state; synthetic mutation/draft records do not retain customer content.
• The UI test path is tenant/member/role/API-key scoped and byte-stable against stored OAuth state and credentials.

Reviewer focus

• scripts/mock-oauth-mcp-server.mjs and its enterprise/fault fixtures
• ee/apps/den-api/src/capability-sources/external-mcp-client.ts
• redirect-safe streaming bounds in url-guard.ts
• POST /v1/mcp-connections/:connectionId/test authorization and read-only behavior
• per-row UI result parsing and safe presentation

Validation

• Independent URL-guard suite: 45 tests / 70 assertions
• Independent mock OAuth/MCP suite: 24 tests / 399 assertions
• Independent Den API connection suite: 10 tests / 188 assertions
• Independent UI-state suite: 4 tests / 9 assertions
• Exact live probes for redirect-body cancellation, deceptive hosts, IPv4/IPv6 loopback, open SSE, timeout cleanup, hung DELETE, and zero active I/O
• Den API and Den Web TypeScript checks
• Den API and Den Web production builds
• Post-rebase Fraimz: 1 flow / 0 failures / 8 green steps, including cleanup and voiceover
• git diff --check
• ./bin/openwork-hub check mcp mcp-diagnostic-mock-server

Follow-ups

• Expand operator-facing documentation for faithful manual/pre-registered enterprise setup versus the explicit local DCR convenience override used by the visual proof.
• Consider an explicit per-org quota for the intentionally expensive connection-test route if the deployment-level limiter is not sufficient.

This is the second of three independent MCP diagnostic PRs. It is based directly on dev; overlapping MCP transport surfaces with the structured-diagnostics and live-tracing 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 e1569ec and was exercised in the independent combined rehearsal, #2675.

The rehearsal confirmed the realistic pre-registered ServiceNow-style confidential-client path, the read-only catalog test, distinct credential and provider-permission failures, stable UI row targeting, bounded callback replacement, listener cleanup, fail-closed runtime controls, and operation-only denial and throttling faults.

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.