---
title: "Validatar Agent Kit for Snowflake Cortex Code"
slug: "validatar-agent-kit-cortex-code"
updated: 2026-11-06T15:12:43Z
published: 2026-11-06T15:12:43Z
canonical: "docs.validatar.com/validatar-agent-kit-cortex-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 Snowflake Cortex Code

Set up the [Validatar Agent Kit](/docs/validatar-agent-kits) in Snowflake Cortex Code (the `cortex` CLI and Cortex Code Desktop). When you finish, Cortex Code can explore your Validatar catalog, create and run tests against your Snowflake data, and package test packs.

> **Note:** Cortex Code in Snowsight connects only to MCP servers that use OAuth, so it cannot use the Validatar MCP server today. Use the CLI or the Desktop app.

## Before you start

- Cortex Code CLI or Desktop installed and connected to your Snowflake account.
- 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 Snowflake Cortex Code](https://admin.cloud.validatar.com/marketplace/99) from the Validatar Marketplace.
2. Extract the zip. It holds one folder, `validatar-kit-cortex-code/`. 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 in the shell you start `cortex` from (Cortex Code reads the environment of the process that launched it):

| 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, then open a new terminal. macOS or Linux: `export` lines in `~/.zshrc` or `~/.bashrc`.

## Add the MCP server

Cortex Code keeps MCP servers in your user profile, not in the project. In the kit folder, run:

```
python validatar/scripts/setup.py configure --user
```

It adds this entry to `~/.snowflake/cortex/mcp.json` and backs up the file first:

```
{
  "mcpServers": {
    "validatar": {
      "type": "http",
      "url": "https://acme.cloud.validatar.com/core/mcp",
      "headers": { "x-val-api-token": "${VALIDATAR_MCP_TOKEN}" }
    }
  }
}
```

The header reads the token from the environment when Cortex Code starts. Alternatively, run `cortex mcp add validatar https://acme.cloud.validatar.com/core/mcp --transport http -H "x-val-api-token: <token>"` in your own terminal; Cortex Code moves the header value to your operating system's keychain.

Then run `python validatar/scripts/setup.py check`.

## Start Cortex Code

1. In a terminal where the variables are set, go to the kit folder and run `cortex`.
2. Run `/mcp`: the `validatar` server is listed. Run `/skill list`: the `validatar-*` skills from `.cortex/skills/` are listed.
3. Ask: **"Connect to Validatar and tell me what projects and data sources I have."**

The always-on instructions are in `AGENTS.md`.

## Limits to know

- MCP calls time out after 60 seconds by default. For long queries or runs, set `COCO_MCP_TOOL_TIMEOUT_MS=300000` before starting `cortex`.
- Tool results over 50 KB are cut off. The kit's skills page large lists and ask for specific sections, but ask for smaller pieces if an answer looks incomplete.

## Use the kit in an existing project

Copy `AGENTS.md` (or append its content to yours), `.cortex/skills/validatar-*`, the `validatar/` folder and the lines from `.gitignore`. The MCP server entry is already in your user profile.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `/mcp` does not list `validatar` | The entry is not in `~/.snowflake/cortex/mcp.json`, or an administrator disabled user MCP servers | Run `setup.py configure --user`; ask your Snowflake administrator about MCP policy |
| MCP server answers 401 | `VALIDATAR_MCP_TOKEN` was not set in the shell that started `cortex` | Set it, open a new terminal, start `cortex` again |
| Tool calls time out | The default 60-second limit | Set `COCO_MCP_TOOL_TIMEOUT_MS=300000` |
| `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 |