Document Codex global/project MCP setup and add agent-facing recovery guidance

[sergeliatko]

WorkOS MCP Codex Setup And Agent Guidance

Documentation Gap

The Codex section of the WorkOS MCP Server documentation does not clearly distinguish user-global setup from project-only setup, and it does not show the explicit OAuth login and verification steps. This caused an avoidable setup interruption and cost about 15 minutes to diagnose.

The WorkOS CLI currently installs the Management MCP integration for Codex at user scope. That is a reasonable default for an account-level service, but users and agents also need a documented repository-scoped option when they do not want the server registered globally.

Observed Behavior

After the server was configured, Codex displayed this warning at startup:

MCP startup interrupted. The following servers were not initialized: workos

The WorkOS documentation did not provide the next authentication and verification steps.

Requested Documentation

Please make the WorkOS MCP documentation the canonical source for both configuration scopes and link to it from any WorkOS CLI, plugin, skill, or MCP-server guidance.

User-Global Setup

Use this option when the WorkOS MCP server should be available in every Codex project for the current user:

codex mcp add workos --url https://mcp.workos.com/mcp
codex mcp login workos
codex mcp get workos
codex mcp list

The documentation should state that this registers the server in the user-level Codex configuration and makes it available across projects.

Project-Only Setup

Use this option when the WorkOS MCP server should be available only in one trusted repository. Add the following to <repository-root>/.codex/config.toml:

[mcp_servers.workos]
url = "https://mcp.workos.com/mcp"

Run the following commands from that repository root:

codex mcp get workos
codex mcp login workos
codex mcp list

The documentation should state that Codex loads repository-level .codex/config.toml only for trusted projects and only while operating in that project context.

Scope And Credential Guidance

• Explain that user-level configuration makes the server available across projects.
• Explain that repository-level configuration limits server discovery to one trusted project.
• Advise against defining the same workos server at both scopes unless an override is intentional.
• State that .codex/config.toml contains the server definition, not OAuth credentials.
• State that OAuth credentials must remain in the host credential store and must never be committed.
• State that teams should commit the project-level server definition only when they intend to share it.

Verification And Recovery Guidance

• Use codex mcp get workos to confirm that Codex discovered the intended configuration.
• Use codex mcp list to confirm the endpoint and OAuth authentication type.
• Use codex mcp login workos when the server is configured but not authenticated.
• Restart Codex after completing the WorkOS consent flow.
• Check the WorkOS team MCP controls when authentication succeeds but access remains disabled.
• Run browser, keyring, and certificate-sensitive authentication from the normal host shell when an agent is sandboxed.
• Do not treat sandbox-only authentication failures as proof that the WorkOS server is unavailable.

Agent And Skill Guidance

The public WorkOS skills repository publishes both plugins/workos/mcp.json and a WorkOS agent skill. The MCP manifest registers https://mcp.workos.com/mcp, while the skill tells agents to prefer the Management MCP server for workspace-management tasks.

Please add a short setup and recovery route to the published WorkOS skill or to a dedicated reference that the skill must read. That guidance should require an agent to determine the requested configuration scope, avoid modifying user-global configuration without user intent, verify project trust, protect OAuth credentials, and hand browser or credential-store authentication back to the host user when the agent is sandboxed.

If the Management MCP server publishes an MCP instructions value, onboarding resource, or other agent-facing help, please include or link the same setup and recovery guidance there. This would help agents recover when the server is registered but unavailable before they can call any WorkOS tools.

Suggested Acceptance Criteria

• The canonical WorkOS MCP page documents user-global Codex setup.
• The canonical WorkOS MCP page documents trusted-project-only Codex setup.
• Both paths include authentication, verification, and restart steps.
• The documentation explains configuration scope and credential storage.
• The published WorkOS skill routes missing or unauthenticated MCP cases to the canonical setup guidance.
• Agent-facing MCP guidance identifies host-only authentication steps.
• WorkOS CLI or diagnostic output links to the same recovery guidance when appropriate.

Environment

• Windows PowerShell
• Codex CLI 0.146.0
• WorkOS Management MCP endpoint https://mcp.workos.com/mcp
• WorkOS server registration name workos

Related WorkOS Surfaces

• WorkOS MCP Server documentation
• WorkOS team MCP controls
• WorkOS CLI repository
• WorkOS skills repository
• WorkOS MCP plugin manifest
• WorkOS published skill