Validatar Agent Kit for Claude Code

Set up the Validatar Agent Kit 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 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: 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.

Windows (PowerShell):

setx VALIDATAR_URL "https://acme.cloud.validatar.com"
setx VALIDATAR_MCP_TOKEN "<your MCP token>"
setx VALIDATAR_API_TOKEN "<your 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="<your MCP token>"
export VALIDATAR_API_TOKEN="<your 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