Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vijil.ai/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you will have Claude Code connected to your Vijil account. Once connected, you can type requests like these and Claude will handle everything for you:
  • “List my agents”
  • “Run a safety evaluation on my customer support agent”
  • “Show me the results of the last evaluation”
You just describe what you want, without writing any code.

​
Prerequisites

  • Vijil Console deployed with an account set up.
  • Python 3.10 or higher. Python is free software that runs the Vijil tools. To check, open your Terminal and type python3 --version.
  • Claude Code (CLI, desktop app, or VS Code Extension) installed.
What is a Terminal? The Terminal (on Mac and Linux) or Command Prompt (on Windows) is a text-based window where you type commands directly. To open it on Mac, press Command + Space, type “Terminal”, and press Enter. On Windows, press the Windows key, type “cmd”, and press Enter.

​
Install the Vijil Tools

This step installs two tools: vijil-mcp (which connects Claude Code to Vijil) and vijil (the underlying Vijil command-line tool). Recommended: pipx pipx is a program for installing command-line tools safely. It avoids the permission errors and PATH problems that pip can cause, so it is the easiest path if you have it. If you do not have pipx yet, install it first, then run: 
pipx install vijil-mcp
Alternative: pip If you prefer to use pip directly: 
pip install vijil-mcp
If that command is not found, try pip3 install vijil-mcp.
When the install finishes, confirm both tools are available: 
vijil --help
vijil-mcp --help
Each command should print a list of options. If you see an error instead, see the Troubleshooting section below.

​
Connect to Vijil Console

Tell the Vijil tool where your Console is. Replace the URL below with the address of your Vijil Console deployment. 
vijil init --url https://console-api.your-company.com
Not sure what your Console URL is? Ask the person who set up Vijil for your organization. The URL is usually something like https://console-api.yourcompany.com.

​
Login to Vijil

vijil login
You will be asked for your email address and password, the same ones you use to log in to the Vijil Console website. After a successful login, the tool saves your session so you do not need to log in again each time. If you belong to more than one team, you will need to pick which one to use: 
vijil team list
This shows your teams with their IDs. Then select the one you want: 
vijil team use <team_id>
Replace <team_id> with the ID shown in the list.

​
Connect Claude Code to Vijil

Now you need to create a small configuration file that tells Claude Code to use the Vijil tools. In your Terminal, navigate to the folder where you do your work, then create a file named .mcp.json with this exact content: 
{
  "mcpServers": {
    "vijil": {
      "type": "stdio",
      "command": "vijil-mcp"
    }
  }
}
What is this file? This file is a short set of instructions for Claude Code. It says “when you start, also start the Vijil tool and make its capabilities available.” You only need to create this file once per project folder.
If you want Vijil available everywhere — not just one folder — add the same content to a file named claude.json in your home directory (~/.claude.json on Mac/Linux).

​
Verify Everything Works

Start Claude Code in the same folder as your .mcp.json file and type:

Check my Vijil setup

Claude will check that the tools are installed, that you are logged in, and that a team is selected. If anything is missing, it will tell you exactly what to fix.

​
What You Can Do Now

​
Register an Agent

Tell Claude about the AI agent you want to evaluate. Provide its name, the model it uses, and its API endpoint and key.

Create a new agent called 'My Chat Agent' using gpt-4 at https://api.openai.com/v1/chat/completions with API key sk-...

Claude registers the agent and shows you its ID. Keep that ID handy — you will use it when running evaluations.

​
See Your Agents

List my agents

Claude shows all your registered agents with their names, IDs, and the last time they were evaluated.

​
See Available Harnesses

Harnesses are the pre-built test suites Vijil uses to run evaluations.

What Harnesses are available?

Claude lists the available Harnesses — safety, security, reliability, and any custom ones your team has created.

​
Run an Evaluation

Run a safety and security evaluation on agent a1b2c3d4-... with sample size 50, and wait for it to complete

Replace a1b2c3d4-... with your agent’s ID. Claude starts the evaluation and waits for it to finish, then shows you the results. Evaluations typically take a few minutes depending on sample size and rate limits. If you prefer not to wait, you can start one and check back:

Start a safety evaluation on agent a1b2c3d4-...

​
Check Evaluation Status

What is the status of evaluation e5f6a7b8-...?

Claude tells you whether the evaluation is still running, completed, or failed.

​
Read the Results

Show me the detailed results for evaluation e5f6a7b8-...

Claude presents the Trust Score breakdown per Harness, and the individual Probe findings — including what failed and why.

​
Generate a Report

Generate a report for evaluation e5f6a7b8-...

Claude triggers report generation. You can then open the full PDF report from your Vijil Console.

​
More Things You Can Ask

Set up Personas — define the types of users who interact with your agent during evaluation:

Show me the persona presets

Create a persona from the 'jailbreaker' preset

Set up Policies — define the compliance rules your agent must follow:

List my compliance policies

Create a policy from the GDPR preset

Manage Dome Guardrails — configure runtime protection for your agent:

List my Dome configurations

Create a Dome config for agent a1b2c3d4-...

View the Trust Dashboard — see aggregated trust metrics across all your agents:

Show me the trust dashboard

​
Troubleshooting

ProblemWhat to Do
pip: command not foundTry pip3 install vijil-mcp instead, or use the pipx method above
Permission denied during installUse pip install --user vijil-mcp, or switch to the pipx method above
vijil: command not found after install succeededClose and reopen your Terminal. If the command is still not found, try re-installing with pipx — it handles the PATH setup automatically
vijil says it is not configuredRun vijil init --url <your-console-url>
”Session expired” or login errorsRun vijil login
”No team selected”Run vijil team list then vijil team use <team_id>
Vijil tools do not appear in Claude CodeMake sure .mcp.json is in the folder where you opened Claude Code, then restart Claude Code
Claude uses the wrong tool or seems confusedTry rephrasing your request to be more specific, for example “Use Vijil to list my agents”
Last modified on June 3, 2026