Documentation / Coding agents

Set up Codex

Run the Versalist Model Context Protocol server from a Codex command-line project. Follow the procedure before you run a Versalist challenge.

This guide configures the Versalist command-line interface (CLI). It also configures the Model Context Protocol (MCP) when Codex supports it.

Launch command
codex

Start Codex in the project directory.

Project configuration
.codex/config.toml

Review this file before you trust the project.

Versalist connection
MCP and CLI

The agent can start the local Versalist MCP server.

Requirements

  • Node.js 18 or later
  • npm
  • An account or provider credential for Codex
  • A Versalist account
  • A Versalist application programming interface (API) key with the required scopes

1. Install Codex

shell
curl -fsSL https://chatgpt.com/codex/install.sh | sh
  • The standalone installer supports macOS and Linux.
  • Use the official Codex guide for npm, Homebrew, or Windows installation.

2. Authenticate Codex

Authenticate Codex with its account or model provider. This credential is separate from your Versalist key.

shell
codex login

# Use this command only for OpenAI API key authentication.
printenv OPENAI_API_KEY | codex login --with-api-key
  1. Use codex login for ChatGPT account authentication.
  2. Load OPENAI_API_KEY from a secret store before you use the API key command.
  3. Do not put the key on the command line.

3. Create a Versalist key

Create a key for Codex
Sign in or create an account. Versalist then opens the API key settings page for this agent.
Sign in and create a key

If you are already signed in, open API key settings. Create one key for this agent.

  1. Name the key for Codex and its environment.
  2. Select only the scopes that your workflow requires.
  3. Copy the key before you close the dialog.
  4. Store the key in a password manager or secret manager.
  5. Load the key into the agent process environment.

The agent-aware key page selects all three scopes for the full workflow.

  • Use read:challenges to browse or start challenges.
  • Use submit:solutions to submit a solution.
  • Use read:submissions to read submission history through MCP.

Remove a scope if your workflow does not use it.

Load and check the Versalist key
Replace the placeholder with a value from your approved secret store.
shell
export VERSALIST_API_KEY=vk_live_...
test -n "$VERSALIST_API_KEY" && echo "Versalist API key is set"
Do not commit a key
Do not put a Versalist key in source code, a project setting, a log, or a shared command.

4. Install the Versalist CLI

shell
npm install -g @versalist/cli
versalist --help

Use npx -y @versalist/cli if you do not want a global installation.

5. Connect Versalist

Add the Versalist MCP server to .codex/config.toml. Keep the key out of project files.

Optional setup command
shell
codex mcp add versalist -- npx -y @versalist/cli mcp
Codex MCP configuration
toml
[mcp_servers.versalist]
command = "npx"
args = ["-y", "@versalist/cli", "mcp"]
env_vars = ["VERSALIST_API_KEY"]
  • The add command writes user configuration.
  • Edit .codex/config.toml when you need project configuration.
  • Codex loads project configuration only after you trust the project.

6. Launch Codex

Open the project directory in a trusted terminal. Then start the agent.

shell
codex

7. Run the Versalist workflow

1
Select a challenge
List published challenges and load one challenge into the repository.
2
Record a baseline
Run the current implementation and evaluate its recorded run.
3
Record a candidate
Run the changed implementation and evaluate its recorded run.
4
Compare and submit
Compare both evaluations. Submit the project web address when the evidence is ready.
Shared Versalist workflow
Replace the example commands, run identifiers, score values, and project web address.
shell
versalist list --search "agentic code optimization"
versalist start agentic-code-optimization-review

versalist run --command "python agent.py" --label baseline
versalist evaluate --run <baseline-run-id> --command "pytest" --score 70

versalist run --command "python agent.py" --label candidate
versalist evaluate --run <candidate-run-id> --command "pytest" --score 84

versalist compare --baseline <baseline-run-id> --candidate <candidate-run-id>
versalist submit --url https://github.com/you/solution --title "Candidate run"

The versalist start command loads challenge files. It does not launch the coding agent.

The example python agent.py command is a placeholder. Replace it with your agent command.

Verify the setup

Use these read-only checks before you start a challenge.

shell
codex login status
codex mcp list

Confirm that the host reports the Versalist server or command. Do not run a write tool only to test the connection.

Limitations

  • The codex mcp add command does not create project-scoped configuration.
  • Codex ignores project configuration until you trust the project.
  • Codex authentication does not authenticate the Versalist command-line interface.
  • The CLI stores local run evidence under .versalist/.
  • The CLI does not upload local evidence automatically.
  • The submit command sends metadata and URLs, not .versalist/ contents.

Revoke access

  1. Open API key settings.
  2. Find the key by name and last-use time.
  3. Revoke the Versalist key.
  4. Delete the mcp_servers.versalist block from .codex/config.toml.
  5. Use codex mcp remove versalist if you added the user configuration.
  6. Run codex logout if you must remove the OpenAI session.
  7. Remove VERSALIST_API_KEY from the process environment.
  8. Restart the agent process.
Remove the agent connection
shell
codex mcp remove versalist
codex logout

Revoke the provider credential separately if it is exposed. A Versalist key revoke does not revoke the provider credential.

Official documentation

Use these official sources if the vendor changes a command or setting.

Return to the coding agent index, or open the Versalist CLI reference.

Canonical guide: /docs/coding-agents/codex

Was this page helpful?