feat(mcp): stage the diagnostics verification release

[reachjalil]

MCP diagnostics controlled release

Important

Current status: Level 1 is merged upstream. Jalil personally verified both the real native Microsoft 365 connection and the package-driven OAuth/MCP initialization path against the new mock. Catalog/safe-read and negative-fault evidence remain automated until Jalil selects those manual checkpoints.

Managerial summary

This draft is the decision and verification ledger for the MCP diagnostics program. It keeps implementation PRs independently reviewable while recording what has been merged, what automation proved, what Jalil personally verified, and what still needs a live or manual check.

We set out to deliver three understandable levels:

1. Clear failure source: identify where an MCP connection failed, who owns the next action, and a safe diagnostic reference.
2. Enterprise development fixture: reproduce Microsoft- and ServiceNow-style OAuth/MCP behavior and controlled faults without customer data.
3. Live diagnostic mode: show connection phases in real time, preserve the highest proven health and the real first failure, and support repair/retry.

During the work, a fourth architectural concern became explicit: the reusable outbound enterprise client should be package-first, with Den supplying infrastructure through adapters. That is tracked separately in #2694.

Microsoft 365 and current package boundary

• Microsoft 365 quick add is a native OAuth/Microsoft Graph integration. It works and Jalil verified it, but it does not use @openwork/enterprise-mcp-client.
• Standard remote/custom MCP connections are the current scope of the provider-neutral package. DEN_ENABLE_ENTERPRISE_MCP_CLIENT=true switches these external MCP routes only.

Microsoft- and ServiceNow-named scenarios in #2670/#2699 are realistic mock fixtures, not newly shipped provider connectors. The word enterprise describes hardened lifecycle, security, persistence, and diagnostics—not a Microsoft-specific implementation.

The long-term direction is to consolidate reusable remote MCP behavior behind package contracts. Migrating native Microsoft 365 or claiming that all connections already use the package is outside this release.

Current status

Area	Source	Automated state	Jalil verification	Integration state
Level 1 structured MCP diagnostics	#2669	Passed	Initial error-source behavior reviewed	Merged into upstream dev
Native Microsoft 365 OAuth safe errors	#2698	10 focused tests + typecheck passed	Real Connect succeeded after replacing the secret value	Draft; not merged
Enterprise mock package and lab	#2670	162 package + 20 lab tests passed	Healthy OAuth/MCP initialization manually observed	Draft; not merged
Package-first enterprise client	#2694	Source + Den matrices passed	Flag-selected external package path reached Connected	Draft; not merged
Client/mock combined proof	#2699	23 client tests + 4 integration scenarios passed	OAuth, token, resource validation, MCP initialize and initialized verified; catalog/safe read remain automated	Verification-only draft
Live tracing	#2672	Earlier focused proof passed	Not started	Draft; must be refreshed from current dev before review

What the real Microsoft 365 check taught us

The browser authorization and callback succeeded, but token exchange returned HTTP 401. The old screen only said:

Token request failed with status 401.

The provider's safe error was invalid_client / AADSTS7000215: Microsoft rejected the client secret because the secret value must be supplied, not the secret ID. After the active secret value was configured, Jalil confirmed the real connection succeeded.

The focused fix in #2698 makes that failure source explicit without exposing provider bodies or secrets, and adds a Den diagnostic reference.

The check also confirmed that Azure local development requires the exact callback form:

http://localhost:<den-api-port>/v1/oauth-providers/microsoft-365/connect/callback

The mock in #2670 now accepts exact HTTP loopback callbacks using localhost, 127.0.0.1, or [::1]. Its protected admin UI uses a separate exact literal loopback origin (127.0.0.1 by default, optionally [::1]) and never treats localhost as equivalent.

What combined automation found

The package-first client/mock rehearsal found a subtle but important diagnostic bug: after token exchange failed, a later successful metadata request could overwrite the recorded request phase. The administrator could therefore be shown discovery as the problem instead of the wrong client secret.

#2694 now preserves failed-request evidence separately. #2699 proves that wrong-secret Microsoft and ServiceNow scenarios both end at oauth-token-exchange, while their healthy flows complete OAuth, MCP initialization, catalog loading, and a safe read.

Earlier integration rehearsal #2675 remains useful historical evidence for the original three levels, but #2699 is the current proof for the new package-first client/mock boundary. Neither rehearsal grants human approval.

What is complete versus still open

Complete:

• Level 1 structured MCP diagnostics merged into current upstream dev.
• Real native Microsoft 365 connection confirmed.
• Safe native token-exchange wording implemented in a focused draft.
• Microsoft and ServiceNow deterministic mock profiles aligned to wrong-secret failures.
• Azure localhost callback behavior represented and tested.
• Package-first client and mock tested together through public package exports.
• Failure phase overwrite found and fixed.
• Package-driven browser connection reached Connected as you with safe events through MCP initialization.

Still open:

• Jalil's manual healthy/wrong-secret ServiceNow mock walkthrough.
• Jalil's manual wrong-secret Microsoft-shaped mock walkthrough and catalog/safe-read review.
• Live Microsoft Enterprise MCP and live ServiceNow tenant verification.
• Review and refresh of live tracing against current upstream dev.
• Maintainer decisions on package naming, adapter contracts, rollout policy, and evidence boundaries.

Controlled verification process

For each checkpoint:

1. Jalil selects one behavior to understand.
2. We start only the required isolated services and review the visible outcome.
3. We record verified, needs changes, or deferred here.
4. Only accepted source commits are integrated into the controlled feature branch.
5. We rerun cumulative package, Den, and browser checks.
6. We update this ledger before selecting the next behavior.

Automation reduces risk but never changes Jalil's verification state by itself.

Recommended next checkpoint

Start with the ServiceNow mock because it demonstrates the reusable enterprise path without involving the already-proven native Microsoft provider:

1. Create a healthy ServiceNow fixture in the lab.
2. Register Den's exact localhost callback.
3. Connect from Den and confirm catalog readiness.
4. Switch to invalid client/wrong secret.
5. Confirm Den identifies OAuth token exchange as the source and gives a safe organization-admin action.
6. Recover to healthy and repeat the same story for Microsoft Enterprise.

After those steps are understood and recorded, review live tracing. Do not begin with the tracing PR while the underlying package connection story is still being learned.

Evidence boundary

The deterministic mock is a development and regression tool. It is not proof of a live customer's license, consent, Conditional Access, ACL, proxy/CA, egress policy, region, patch level, or provider business behavior. Those facts require approved nonproduction ServiceNow and Microsoft tenants and must remain separately recorded.

No secrets, OAuth codes, access tokens, customer hostnames, or customer content belong in this ledger or its linked PR evidence.

[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 13, 2026 2:43am

[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.

[benjaminshafii]

Validation disposition: keep this as release-staging documentation, not as the product fix.

The repository checks are green, but this PR does not provide the runtime diagnostics implementation by itself. It should follow whichever implementation candidate is ultimately published and should not be merged independently as evidence that the ServiceNow MCP issue is fixed.

The implementation validation now covers production builds, clean and upgrade DB migration paths, structured API compatibility, and 16 production fraimz frames. No merge or branch mutation performed.