Validatar Agent Kit for OpenAI Codex

Set up the Validatar Agent Kit in OpenAI Codex: the Codex CLI, the IDE extension or the Codex app. When you finish, Codex can explore your Validatar catalog, create and run tests, and package test packs.

Before you start

• Codex installed and signed in.
• Python 3.9 or newer on the PATH (python --version).
• Your Validatar instance address, for example https://acme.cloud.validatar.com.
• A Validatar user that can create tests in at least one project, ideally a sandbox project.

Get the kit

1. Download Validatar Agent Kit for OpenAI Codex from the Validatar Marketplace.
2. Extract the zip. It holds one folder, validatar-kit-codex/. Use it as your working folder, or copy its contents into an existing repository (see below).

Create your tokens and set the variables

1. In Validatar, open your user profile, User Tokens. Create a token of type MCP. For MCP + API mode (optional), also create a token of type API with the scopes Authoring, Execution, Data Steward and Catalog.

2. Set the environment variables for your user account:

   Variable	Value
   VALIDATAR_URL	Your instance address, no trailing slash
   VALIDATAR_MCP_TOKEN	The MCP token
   VALIDATAR_API_TOKEN	The API token (optional: MCP + API mode)

   Windows (PowerShell): setx VALIDATAR_URL "https://acme.cloud.validatar.com", and the same for each token. macOS or Linux: export lines in ~/.zshrc or ~/.bashrc.

3. Open a new terminal (restart VS Code for the extension) so Codex sees them.

Configure Codex

In the kit folder, run:

python validatar/scripts/setup.py configure

It writes .codex/config.toml with your instance address:

[mcp_servers.validatar]
url = "https://acme.cloud.validatar.com/core/mcp"
env_http_headers = { "x-val-api-token" = "VALIDATAR_MCP_TOKEN" }
startup_timeout_sec = 30
tool_timeout_sec = 300

[sandbox_workspace_write]
network_access = true

env_http_headers names the environment variable that holds the token; the token itself is never written. codex mcp add cannot set a custom header, which is why the kit writes the file.

The IDE extension and the Codex app read ~/.codex/config.toml. To add the server there too, run python validatar/scripts/setup.py configure --user. It appends a [mcp_servers.validatar] table and backs up your file first.

Then run python validatar/scripts/setup.py check. It confirms Python, the variables, the MCP connection, the API connection if you set an API token, and the access mode.

Start Codex

1. In the kit folder, run codex.
2. When Codex asks whether to trust the folder, trust it. Codex ignores a project's .codex/config.toml until you do.
3. Type /mcp: validatar is listed with its tools.
4. Ask: "Connect to Validatar and tell me what projects and data sources I have."

Skills are in .agents/skills/. Type $ or /skills to list them and call one directly.

Network access for the scripts

Codex runs shell commands in a sandbox with network turned off. The kit's helper scripts call your Validatar instance, so the project configuration turns network access on for this folder ([sandbox_workspace_write] network_access = true). If you rely on the user configuration only, start Codex with:

codex -c sandbox_workspace_write.network_access=true

or approve the scripts when Codex asks to run them outside the sandbox. MCP calls go through Codex itself and are not affected.

Use the kit in an existing repository

Copy AGENTS.md (or append its content to yours), .agents/skills/validatar-*, .codex/config.toml (or merge its tables), the validatar/ folder and the lines from .gitignore.

Troubleshooting