---
title: "Validatar Agent Kit for Kiro"
slug: "validatar-agent-kit-kiro"
updated: 2026-11-06T15:12:46Z
published: 2026-11-06T15:12:46Z
canonical: "docs.validatar.com/validatar-agent-kit-kiro"
---

> ## 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 Kiro

Set up the [Validatar Agent Kit](/docs/validatar-agent-kits) in Kiro, the IDE or `kiro-cli` (which replaced the Amazon Q Developer CLI). When you finish, Kiro can explore your Validatar catalog, create and run tests, and package test packs.

## Before you start

- Kiro 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 Kiro](https://admin.cloud.validatar.com/marketplace/101) from the Validatar Marketplace.
2. Extract the zip. It holds one folder, `validatar-kit-kiro/`. 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. In the kit folder, run `python validatar/scripts/setup.py configure`, then `python validatar/scripts/setup.py check`.

## Check the connection

`setup.py configure` wrote `.kiro/settings/mcp.json` with your instance address:

```
{
  "mcpServers": {
    "validatar": {
      "url": "https://acme.cloud.validatar.com/core/mcp",
      "headers": { "x-val-api-token": "${VALIDATAR_MCP_TOKEN}" },
      "autoApprove": ["describe", "list", "..."],
      "disabledTools": []
    }
  }
}
```

The read-only Validatar tools are in `autoApprove`; tools that create or change something still ask.

1. Restart Kiro and open the kit folder (or run `kiro-cli` in it).
2. Open the MCP panel (`/mcp` in the CLI): `validatar` is connected.
3. Ask: **"Connect to Validatar and tell me what projects and data sources I have."**

The always-on instructions are the steering file `.kiro/steering/validatar.md` (`inclusion: always`), so they sit next to any `AGENTS.md` you already have. Skills are in `.kiro/skills/`.

## Let the helper scripts run

Kiro asks before running shell commands that no rule covers. To let the kit's scripts run without asking each time, add a rule to `~/.kiro/settings/permissions.yaml`:

```
- capability: shell
  match: ["python validatar/scripts/*"]
  effect: allow
```

The rule lives in your profile, so a repository cannot grant itself permissions.

## Use the kit in an existing repository

Copy `.kiro/steering/validatar.md`, `.kiro/skills/validatar-*`, `.kiro/settings/mcp.json` (or merge its `validatar` entry), the `validatar/` folder and the lines from `.gitignore`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `validatar` shows an error | Kiro started before the variables were set, or `VALIDATAR_URL` ends with `/` | Run `setup.py check`, fix what it reports, restart Kiro |
| MCP server answers 401 | The token is not an MCP token, or expired | Create a new MCP token and update `VALIDATAR_MCP_TOKEN` |
| Every script asks for approval | No shell rule for the scripts | Add the permissions rule above |
| `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 |