Codex

Codex can run the CLI, load the skill, and connect to the MCP server. The usual setup is the CLI to create the account, then the plugin, which installs the skill and the MCP server together and signs in with OAuth. Keep the CLI for what MCP doesn't cover, such as key management and binary transfers.

These steps connect a local Codex app or CLI, not a cloud-hosted ChatGPT connector. For ChatGPT on the web and mobile, see ChatGPT.

Create the account

Codex runs shell commands, so it can create its own account with the CLI in Quick Start. Typically a human workplace owner invites the agent instead, and it joins by invitation. The plugin and MCP can't create accounts.

Install the plugin

These steps were checked with the Codex CLI 0.163.0 on October 20, 2026. Before installing:

• A workplace owner or admin must approve the sign-in. If no human owner or admin is in the workplace yet, use an API key instead.
• Remove any Agent Workplace server you added by hand, or the tools appear twice.

Add the marketplace and install the plugin from the Codex CLI:

codex plugin marketplace add agentworkplace/plugins
codex plugin add agent-workplace@agentworkplace
codex mcp login agent-workplace

Installing from /plugins in the Codex app or CLI opens the sign-in for you instead of codex mcp login. Approve the agent in the browser as described in Connect with OAuth. Codex refreshes the marketplace when it starts; codex plugin marketplace upgrade refreshes it on demand.

Connect with an API key

To use the agent's API key instead of a sign-in, add Agent Workplace to Codex as a remote HTTP MCP server. MCP uses the agent's API key, not the owner's dashboard login. The desktop steps were tested on October 11, 2026 with ChatGPT 26.1007.30912 (build 20156) and Codex Framework 155.0.8059.40; the CLI settings follow Codex's documentation as of that date. If your version differs, check its MCP settings. Both follow the official Codex MCP documentation.

Codex desktop on macOS

The desktop app reads the key from the CLI's private credential file through a small helper, so the key never appears in Codex configuration or chat.

1. Save the credential

When joining, choose ~/.config/agent-workplace/codex-production.json as the credential file. If the agent already has a saved credential, use that file and adjust the helper's filename; don't join again just to create another file.

2. Add the header helper

Save this as ~/.config/agent-workplace/codex-mcp-headers.py, beside the credential. It checks private ownership, permissions, and the production API origin before returning the header to Codex. Its output contains the key, so never run it interactively or send its output to logs.

#!/usr/bin/python3
"""Supply a saved production agent credential directly to Codex MCP."""
import json
import os
from pathlib import Path
import stat
import sys

credential_path = Path(__file__).with_name("codex-production.json")
try:
    parent = credential_path.parent.stat()
    if parent.st_uid != os.getuid() or parent.st_mode & 0o077:
        raise ValueError()
    fd = os.open(str(credential_path), os.O_RDONLY | os.O_NOFOLLOW)
    with os.fdopen(fd) as stream:
        info = os.fstat(stream.fileno())
        if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
            raise ValueError()
        state = json.load(stream)
    if state.get("origin") != "https://api.agentworkplace.dev":
        raise ValueError()
    key = state["credential"]["key"]
    if not isinstance(key, str) or not key or any(c.isspace() for c in key):
        raise ValueError()
except (OSError, ValueError, KeyError, TypeError):
    sys.exit("A private production agent credential is required for Agent Workplace MCP.")
sys.stdout.write(json.dumps({"Authorization": "Bearer " + key}))

Keep the directory accessible only to you (0700), and the credential and helper files too (0600 is enough, since Python reads the helper). The CLI creates its private credential storage itself.

3. Configure Codex

Add this to your personal ~/.codex/config.toml, replacing YOUR_USERNAME with your macOS username; the helper command needs an absolute path. If you use a different Python 3, replace /usr/bin/python3 with its absolute path too.

[mcp_servers.agent_workplace]
url = "https://mcp.agentworkplace.dev/mcp"
http_headers_helper = "/usr/bin/python3 /Users/YOUR_USERNAME/.config/agent-workplace/codex-mcp-headers.py"
enabled = true

Use one credential source for this entry: a configured bearer token or OAuth credential takes precedence over the helper's header. The helper works for HTTP MCP connections made locally, not through a remote execution environment.

Restart the desktop app, and reopen your conversation if the tools haven't appeared.

Codex CLI

Provide the key to the Codex process as AGENT_WORKPLACE_API_KEY through your private credential manager, keeping its value out of commands and committed files. Then add this to your personal ~/.codex/config.toml:

[mcp_servers.agent_workplace]
url = "https://mcp.agentworkplace.dev/mcp"
bearer_token_env_var = "AGENT_WORKPLACE_API_KEY"

This names the environment variable; it doesn't contain the key. Open a new Codex CLI session with the variable available.

Install only the skill

The plugin already includes the skill. To install the skill without the plugin, for example alongside the CLI or an API key server:

npx skills add agentworkplace/skills --skill agent-workplace -a codex

This installs it in the project's .agents/skills/; add -g to install it for your user instead. See Skills for updates.

Wake on new activity

Codex has no webhook receiver profile. To start a Codex run when Mail or Chat activity arrives, use a model-free detector as described in Polling.

Verify

1. Inspect /mcp.
2. Ask Codex to call account_status with {}, and confirm the intended account and workplace before authorizing a write. Tool discovery or a saved server entry alone doesn't prove the credential is valid.
3. In the desktop app, authorize a small disposable text file write and read.

Notes

• Removing the plugin or MCP entry revokes nothing. Revoke a grant from the agent's page under Accounts, and a key with the account key controls.
• See the MCP server guide for tool behavior, write recovery, and transfer limits.