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

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

Set up the [Validatar Agent Kit](/docs/validatar-agent-kits) in Cursor, the editor or the Cursor CLI. When you finish, Cursor's agent can explore your Validatar catalog, create and run tests, and package test packs.

## Before you start

- Cursor 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 Cursor](https://admin.cloud.validatar.com/marketplace/98) from the Validatar Marketplace.
2. Extract the zip. It holds one folder, `validatar-kit-cursor/`. 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`.
4. Quit and reopen Cursor so it sees the variables, then open the kit folder.

## Check the connection

1. Open **Settings > MCP**. `validatar` is listed and enabled, with its tools. The kit's `.cursor/mcp.json` reads the address and token from the environment:

```
{
  "mcpServers": {
    "validatar": {
      "url": "${env:VALIDATAR_URL}/core/mcp",
      "headers": { "x-val-api-token": "${env:VALIDATAR_MCP_TOKEN}" }
    }
  }
}
```
2. In the agent chat, ask: **"Connect to Validatar and tell me what projects and data sources I have."**

The always-on rule is `.cursor/rules/validatar.mdc`. Skills are in `.cursor/skills/`; type `/` and a skill name to call one directly. The Cursor CLI (`agent`) uses the same files.

## Network access for the scripts

Cursor's sandbox blocks network for commands by default. `setup.py configure` writes `.cursor/sandbox.json`, which allows your Validatar host and nothing else:

```
{ "networkPolicy": { "default": "deny", "allow": ["acme.cloud.validatar.com"] } }
```

Without it, the helper scripts fail inside the sandbox with a connection error.

## Use the kit in an existing repository

Copy `.cursor/rules/validatar.mdc`, `.cursor/skills/validatar-*`, `.cursor/mcp.json` (or merge its `validatar` entry), `.cursor/sandbox.json` (or add the host to yours), the `validatar/` folder and the lines from `.gitignore`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `validatar` shows an error in Settings > MCP | Cursor started before the variables were set, or `VALIDATAR_URL` ends with `/` | Run `setup.py check`, fix what it reports, quit and reopen Cursor |
| MCP server answers 401 | The token is not an MCP token, or expired | Create a new MCP token and update `VALIDATAR_MCP_TOKEN` |
| Scripts fail with "Cannot reach" | The sandbox blocks the host | Run `setup.py configure` to write `.cursor/sandbox.json` |
| `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 |