--- title: "Validatar Agent Kit for Claude Code" slug: "validatar-agent-kit-claude-code" updated: 2026-11-06T15:12:34Z published: 2026-11-06T15:12:34Z canonical: "docs.validatar.com/validatar-agent-kit-claude-code" --- > ## 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 Claude Code Set up the [Validatar Agent Kit](/docs/validatar-agent-kits) in Claude Code. When you finish, Claude Code can explore your Validatar catalog, create and run tests, and package test packs from a folder on your machine. ## Before you start - Claude Code installed and signed in. - Python 3.9 or newer: `python --version` must work in the terminal you start Claude Code from. On Windows, Claude Code runs commands in Git Bash, so check there. - 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 Claude Code](https://admin.cloud.validatar.com/marketplace/95) from the Validatar Marketplace. 2. Extract the zip. It holds one folder, `validatar-kit-claude-code/`. Use it as your working folder, or copy its contents into an existing repository (see below). ## Create your tokens 1. In Validatar, open your user profile and go to **User Tokens**. 2. Create a token of type **MCP** and copy it. 3. Optional, for [MCP + API mode](/docs/validatar-agent-kits#two-access-modes): create a token of type **API** with the scopes Authoring, Execution, Data Steward and Catalog, and copy it. Without it the kit works in MCP only mode. ## Set the environment variables The kit and Claude Code read your instance and tokens from environment variables, so no file ever holds a token. | Variable | Value | | --- | --- | | `VALIDATAR_URL` | Your instance address, with 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" setx VALIDATAR_MCP_TOKEN "" setx VALIDATAR_API_TOKEN "" # optional ``` **macOS or Linux:** add these lines to `~/.zshrc` or `~/.bashrc`: ``` export VALIDATAR_URL="https://acme.cloud.validatar.com" export VALIDATAR_MCP_TOKEN="" export VALIDATAR_API_TOKEN="" # optional ``` Open a new terminal afterwards: programs started before the change do not see the variables. ## Check the setup In a new terminal, go to the kit folder and run: ``` python validatar/scripts/setup.py check ``` The check confirms Python, the variables, the MCP connection and, if you set an API token, the API connection. It prints the server version and the access mode, and lists anything still missing. It never prints a token. ## Start Claude Code 1. In the kit folder, run `claude`. 2. Claude Code asks whether you trust the folder and whether to use the `validatar` MCP server from `.mcp.json`. Accept both. 3. Type `/mcp`. The `validatar` server shows as connected. 4. Ask: **"Connect to Validatar and tell me what projects and data sources I have."** The kit's `.claude/settings.json` lets the agent run read-only MCP tools and read-only helper commands without asking each time. Anything that creates, changes or runs something in Validatar still asks for your approval. Claude Code applies that file only after you trust the folder. ## What to ask - "Profile the CUSTOMER table in the STAGING schema and suggest tests." - "Create a test that fails if any ORDER row has no matching CUSTOMER." - "Here is our source-to-target mapping sheet. Turn it into a test plan." - "Make the duplicate-key test a template for every table in the STAGING schema." - "Run the tests in the Daily Checks folder and explain the failures." - "Package the Reconciliation folder as a test pack I can import into production." (MCP + API) The agent shows you each design before it creates anything. Skills can also be called directly: type `/` and the skill name, for example `/validatar-test-plan`. ## Use the kit in an existing repository Copy these from the kit folder into the repository root: - `CLAUDE.md`. If the repository already has one, save the kit's file as `validatar/INSTRUCTIONS.md` and add the line `@validatar/INSTRUCTIONS.md` to your `CLAUDE.md` - `.claude/skills/validatar-*` - `.mcp.json`, or merge its `validatar` entry into yours - `.claude/settings.json`, or merge its `permissions.allow` entries into yours - the `validatar/` folder and the lines from `.gitignore` ## Unattended runs `claude -p` loads the project MCP server without a prompt, but it cannot ask for approvals. Start Claude Code interactively in the folder once to trust it, and name the tools the run may use: ``` claude -p "Run the tests in folder 42 and summarize the failures" --allowedTools mcp__validatar "Bash(python validatar/scripts/*)" ``` ## Troubleshooting | Symptom | Cause | Fix | | --- | --- | --- | | `/mcp` shows `validatar` failed or not listed | Claude Code started before the variables were set, or `VALIDATAR_URL` has a trailing slash | Run `setup.py check` in the same terminal, fix what it reports, restart `claude` | | MCP server answers 401 | The token is not an MCP-type token, or it expired | Create a new MCP token and update `VALIDATAR_MCP_TOKEN` | | Every tool call asks for approval, including reads | The folder is not trusted, so `.claude/settings.json` is ignored | Start `claude` interactively in the folder and accept the trust prompt | | `python: command not found` | Python is not on the PATH of the shell Claude Code uses | Install Python 3.9+ and make `python --version` work in Git Bash (Windows) or your shell | | `api.py` answers 403 "does not have scope" | The API token lacks a scope (or an MCP token was used) | 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 |