fix(mcp): distinguish MCP configuration from OAuth authentication

[gjtorikian]

Summary

• report MCP server definitions as configured instead of implying OAuth is complete
• recover when Codex persists configuration but its OAuth flow is interrupted
• validate the effective Codex endpoint and surface safe host-shell recovery commands
• retain legacy JSON outcome and installed fields for compatibility
• link setup and doctor output to the canonical WorkOS MCP guide

Addresses #213.

Testing

• bun run format:check
• bun run lint
• bun run typecheck
• bun run test
• bun run build

[greptile-apps]

Greptile Summary

The PR separates MCP configuration from OAuth status and strengthens Codex recovery handling.

• Verifies the effective Codex endpoint before treating a failed or colliding add operation as successful.
• Adds structured authentication metadata, recovery guidance, and compatibility-preserving JSON fields.
• Updates setup, status, doctor, help, tests, and documentation to consistently report MCP definitions as configured rather than authenticated.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/lib/mcp-clients.ts	Adds Codex endpoint introspection and ensures non-zero add and collision recovery only succeed when the surviving definition uses the intended endpoint.
src/commands/mcp.ts	Reports configuration and authentication separately while retaining the legacy installed field for JSON consumers.
src/commands/setup.ts	Propagates structured MCP configuration metadata and client-owned OAuth recovery guidance through setup output.
src/doctor/checks/mcp.ts	Generalizes effective-endpoint validation and annotates configured clients whose OAuth state cannot be verified.
src/doctor/output.ts	Renders MCP definitions as configured and links users to recovery documentation when OAuth remains unverified.
src/doctor/types.ts	Extends the public doctor report with configuration, authentication, and documentation fields while preserving installed compatibility.
src/bin.ts	Updates MCP command help terminology to describe configuration rather than installation.
src/utils/help-json.ts	Keeps agent-facing JSON help synchronized with the updated MCP command description.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Run Codex MCP add] --> B{Exit status}
  B -->|Success| C[Report configured]
  B -->|Failure or collision| D{WorkOS entry present?}
  D -->|No| E[Report failure]
  D -->|Yes| F[Read effective endpoint]
  F -->|Expected WorkOS URL| G[Report configured and OAuth action required]
  F -->|Wrong or unreadable URL| E
  C --> H[Show OAuth recovery guidance]
  G --> H

Loading

_{Reviews (5): Last reviewed commit: "refactor(mcp): drive the OAuth caveat of..." | Re-trigger Greptile}