---
title: "Validatar Agent Kit for GitHub Copilot"
slug: "validatar-agent-kit-github-copilot"
updated: 2026-11-06T15:12:38Z
published: 2026-11-06T15:12:38Z
canonical: "docs.validatar.com/validatar-agent-kit-github-copilot"
---

> ## 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 GitHub Copilot

Set up the [Validatar Agent Kit](/docs/validatar-agent-kits) for GitHub Copilot: agent mode in VS Code, Copilot CLI, or the Copilot cloud agent on github.com. When you finish, Copilot can explore your Validatar catalog, create and run tests, and package test packs.

## Before you start

- GitHub Copilot with agent mode available to you.
- 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 GitHub Copilot](https://admin.cloud.validatar.com/marketplace/97) from the Validatar Marketplace.
2. Extract the zip. It holds one folder, `validatar-kit-copilot/`. Use it as your working folder, or copy its contents into an existing repository (see below).

The kit puts the always-on instructions in `.github/copilot-instructions.md` and the skills in `.github/skills/`, which every Copilot surface reads.

## 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 (the helper scripts and Copilot CLI read them):

| 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`.

## VS Code (agent mode)

1. Restart VS Code, open the kit folder and trust the workspace.
2. Open `.vscode/mcp.json` (written by `setup.py configure`) and click **Start** above the `validatar` server. VS Code asks for the MCP token once and keeps it in its secret storage.
3. Open Copilot Chat, switch to **Agent**, and check that the tools list includes the `validatar` tools.
4. Ask: **"Connect to Validatar and tell me what projects and data sources I have."**

VS Code asks before the agent runs a helper script in the terminal. To let read-only checks run without asking, add them to `chat.tools.terminal.autoApprove` in your settings, for example:

```
"chat.tools.terminal.autoApprove": {
  "python validatar/scripts/setup.py check": true,
  "/^python validatar\\/scripts\\/check_config\\.py /": true
}
```

## Copilot CLI

Run `copilot` in the kit folder and trust the folder when asked. Copilot CLI reads `.mcp.json`, which takes the URL and token from `VALIDATAR_URL` and `VALIDATAR_MCP_TOKEN`. Type `/mcp` to see the server. For non-interactive runs (`copilot -p`), add `--trust-folder`.

## Copilot cloud agent

1. Commit the kit's files to the repository.
2. In the repository settings, open **Copilot > MCP servers** and paste:

```
{
  "mcpServers": {
    "validatar": {
      "type": "http",
      "url": "https://acme.cloud.validatar.com/core/mcp",
      "headers": { "x-val-api-token": "$COPILOT_MCP_VALIDATAR_TOKEN" },
      "tools": ["*"]
    }
  }
}
```
3. Under **Settings > Secrets and variables > Agents**, add `COPILOT_MCP_VALIDATAR_TOKEN` (the MCP token). Only MCP servers see secrets that start with `COPILOT_MCP_`, so for the helper scripts also add `VALIDATAR_URL` and `VALIDATAR_MCP_TOKEN` (and `VALIDATAR_API_TOKEN` for MCP + API mode).
4. Add your instance's host to the agent firewall's custom allowlist so the scripts can reach it.

## Use the kit in an existing repository

Copy `.github/copilot-instructions.md` (or append its content to yours), `.github/skills/validatar-*`, `.mcp.json` and `.vscode/mcp.json` (or merge their `validatar` entries), the `validatar/` folder and the lines from `.gitignore`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| No `validatar` tools in agent mode | The server was not started, or the workspace is not trusted | Start it from `.vscode/mcp.json` or **MCP: List Servers** |
| MCP server answers 401 | The token entered is not an MCP token, or expired | Create a new MCP token. VS Code keeps the value it asked for, so give the input a new id in `.vscode/mcp.json` (change `validatar-mcp-token` in `inputs` and in `${input:...}` to, for example, `validatar-mcp-token-2`), then restart the server and enter the new token when VS Code asks |
| Copilot CLI does not load `.mcp.json` | The folder is not trusted | Trust it, or pass `--trust-folder` |
| Scripts fail with "VALIDATAR_URL is not set" | VS Code started before the variables were set | Restart VS Code |
| `api.py` answers 403 "does not have scope" | The API token lacks a scope | Create an API-type token with the scopes listed above |