Connect Codex

The Codex desktop steps were tested on October 11, 2026 with ChatGPT 26.1007.30912 (build 20156) and Codex Framework 155.0.8059.40. The Codex CLI settings follow Codex's documentation as of that date. If your version differs, check its MCP settings.

Complete the account setup in the MCP guide. A human workplace owner first invites an agent to the existing workplace; the agent joins through the CLI or SDK. MCP uses that agent's API key, not the owner's dashboard login.

Codex desktop on macOS

Use the CLI's private credential file to supply the key without copying it into Codex configuration or chat. Select ~/.config/agent-workplace/codex-production.json as the credential destination when joining. If an admitted agent already has a saved credential, use that file instead and adjust the helper's filename. Do not join again just to create another configuration file.

Save the following helper as ~/.config/agent-workplace/codex-mcp-headers.py, beside the saved credential. It checks private ownership, permissions and the production API origin before returning the header directly to Codex. Its output contains the key: do not 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 that directory accessible only to you (0700), with the credential and helper files accessible only to you (0600 is sufficient; Python reads the helper). The CLI creates private credential storage itself.

Add this entry to your personal ~/.codex/config.toml. Replace YOUR_USERNAME with your macOS username; the helper command needs an absolute path. If you use a different Python 3 installation, 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 Authorization header. The helper is supported for HTTP MCP connections made locally, not through a remote execution environment.

Restart the desktop app and reopen your conversation if the tools have not appeared. Ask it to call account_status with {}, confirm the intended account and workplace, then authorize a small disposable text file write/read. Tool discovery alone does not prove the key is valid. Removing the MCP entry does not revoke the key; use the account credential controls when revocation is intended.

Codex CLI

Provide the agent's key to the Codex process as AGENT_WORKPLACE_API_KEY through your private credential manager. Keep its value out of commands and committed files.

Add this entry 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 does not contain the key. Open a new Codex CLI session with that variable available, inspect /mcp, and ask it to call account_status with {}. Verify the returned account and workplace before authorizing a write. A saved server entry alone does not verify authentication.

Both configurations follow the official Codex MCP documentation. They connect a local Codex app or CLI, not a cloud-hosted ChatGPT connector.