---
title: "Validatar Agent Kit for OpenAI Codex"
slug: "validatar-agent-kit-codex"
updated: 2026-11-06T15:12:36Z
published: 2026-11-06T15:12:36Z
canonical: "docs.validatar.com/validatar-agent-kit-codex"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validatar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validatar Agent Kit for OpenAI Codex

Set up the [Validatar Agent Kit](/docs/validatar-agent-kits) 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](https://admin.cloud.validatar.com/marketplace/96) 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](/docs/validatar-agent-kits#two-access-modes) (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

| Symptom | Cause | Fix |
| --- | --- | --- |
| `/mcp` does not list `validatar` | The folder is not trusted, or the server is only in project config and you use the IDE extension | Trust the folder, or run `setup.py configure --user` and restart |
| MCP server answers 401 | `VALIDATAR_MCP_TOKEN` is not visible to Codex, not an MCP token, or expired | Run `setup.py check` in the same terminal; create a new MCP token if needed |
| Scripts fail with "Cannot reach" | Sandbox network is off | Keep the project config, or start Codex with `-c sandbox_workspace_write.network_access=true` |
| `api.py` answers 403 "does not have scope" | The API token lacks a scope | Create an API-type token with the scopes listed above |
| A template test has no child tests | Template tests create child tests only when materialized | Ask the agent to materialize it (MCP + API), or click **Materialize Child Tests** on the template |