> ## Documentation Index
> Fetch the complete documentation index at: https://vijil-vin-docs-darwin-hardening-policy-guide.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> This guide walks through setting up the Vijil MCP server so Claude Code can interact with your Vijil Console deployment. By the end you will have Claude Code listing your agents, running evaluations, and retrieving results — all through natural language. 

## Install

Install the [`vijil-mcp`](https://pypi.org/project/vijil-mcp/) package.

<CodeGroup>
  ```bash title="pip" theme={null}
  pip install vijil-mcp
  ```

  ```bash title="pipx"  theme={null}
  pipx install vijil-mcp
  ```
</CodeGroup>

This also installs `vijil-console` (the CLI) as a dependency. Verify both:

```bash theme={null}
vijil --help

vijil-mcp --help
```

## Initialize the CLI

Point the CLI at your Vijil Console deployment:

```bash theme={null}
vijil init --url https://console-api.example.com
```

## Login to Vijil Console

```bash theme={null}
vijil login
```

You will be prompted for your email and password. On success the CLI stores your JWT token and automatically selects your team if you belong to exactly one.

If you belong to multiple teams, select one:

```bash theme={null}
vijil team list

vijil team use <team_id>
```

## Configure Claude Code

Create a `.mcp.json` file in your project root:

```json theme={null}
{

  "mcpServers": {

    "vijil": {

      "type": "stdio",

      "command": "vijil-mcp"

    }

  }

}
```

This tells Claude Code to launch `vijil-mcp` as a local subprocess and discover its tools.

> **Tip:** Add `.mcp.json` to your project's `.gitignore` if you do not want to share it, or commit it so your whole team gets the Vijil tools automatically.

For global access across all projects, add to `~/.claude.json` instead:

```json theme={null}
{

  "mcpServers": {

    "vijil": {

      "type": "stdio",

      "command": "vijil-mcp"

    }

  }

}
```

## Verify the Setup

Start Claude Code in the directory with `.mcp.json` and ask:

> "Check my Vijil setup"

Claude will call the `vijil_status` tool and confirm the CLI is configured, authenticated, and has a team selected. If anything is missing, it will tell you what to fix.

## Register an Agent

Ask Claude to create an agent configuration pointing at the AI model you want to evaluate:

<Prompt description="Create a new agent called 'My Chat Agent' using gpt-4 at https://api.openai.com/v1/chat/completions with API key sk-...">
  Create a new agent called 'My Chat Agent' using gpt-4 at [https://api.openai.com/v1/chat/completions](https://api.openai.com/v1/chat/completions) with API key sk-...
</Prompt>

Claude will call `agent_create` with the right parameters and show you the created agent including its ID. Copy that ID for the next steps.

## List Agents

<Prompt description="List my agents">
  List my agents
</Prompt>

Claude will call `agent_list` and show agent IDs, names, models, and creation dates.

## List Available Harnesses

Harnesses are test suites that evaluate different trust dimensions:

<Prompt description="What harnesses are available?">
  What harnesses are available?
</Prompt>

Claude will call `harness_list` and show you the test suites (safety, ethics, privacy, security, toxicity, etc.).

## Run an Evaluation

Start a trust evaluation against your agent:

<Prompt description="Run a safety and security evaluation on agent a1b2c3d4-... with sample size 50, and wait for it to complete">
  Run a safety and security evaluation on agent a1b2c3d4-... with sample size 50, and wait for it to complete
</Prompt>

Claude will call `eval_run` with `wait=True` and report back when the evaluation finishes, including the scores.

You can also run without waiting:

<Prompt description="Start a safety evaluation on agent a1b2c3d4-...">
  Start a safety evaluation on agent a1b2c3d4-...
</Prompt>

## Check Evaluation Status

If you did not use `wait`, check the status:

<Prompt description="What is the status of evaluation e5f6a7b8-...?">
  What is the status of evaluation e5f6a7b8-...?
</Prompt>

Claude will call `eval_status` and show whether the evaluation is running, completed, or failed.

## View Evaluation Results

Once the evaluation completes, retrieve the detailed results:

<Prompt description="Show me the detailed results for evaluation e5f6a7b8-...">
  Show me the detailed results for evaluation e5f6a7b8-...
</Prompt>

Claude will call `eval_results_detail` and present the per-Harness breakdowns and individual Probe results.

## Generate a Report

Trigger on-demand report generation for the completed evaluation:

<Prompt description="Generate a report for evaluation e5f6a7b8-...">
  Generate a report for evaluation e5f6a7b8-...
</Prompt>

Claude will call `eval_report` to generate the report.

## Next Steps

Here are more things you can ask Claude with the Vijil MCP tools:

**Custom Harnesses** — create test suites tailored to your use case:

<Prompt description="Create a custom harness called 'My Harness' for agent a1b2c3d4-...">
  Create a custom harness called 'My Harness' for agent a1b2c3d4-...
</Prompt>

**Personas** — list presets and create personas for testing:

<Prompt description="Show me the persona presets">
  Show me the persona presets
</Prompt>

<Prompt description="Create a persona from the 'jailbreaker' preset">
  Create a persona from the 'jailbreaker' preset
</Prompt>

**Policies** — manage compliance policies and rules:

<Prompt description="List my compliance policies">
  List my compliance policies
</Prompt>

<Prompt description="Create a policy from the GDPR preset">
  Create a policy from the GDPR preset
</Prompt>

**DOME Guardrails** — configure runtime protection:

<Prompt description="List my Dome configurations">
  List my Dome configurations
</Prompt>

<Prompt description="Create a Dome config for agent a1b2c3d4-...">
  Create a Dome config for agent a1b2c3d4-...
</Prompt>

**Red team campaigns** — run adversarial attack campaigns:

<Prompt description="What red team tools are available?">
  What red team tools are available?
</Prompt>

<Prompt description="Run a garak campaign against my agent at https://my-agent.com/v1">
  Run a garak campaign against my agent at [https://my-agent.com/v1](https://my-agent.com/v1)
</Prompt>

**Trust dashboard** — view aggregated trust metrics:

<Prompt description="Show me the trust dashboard">
  Show me the trust dashboard
</Prompt>

## How it Works Under the Hood

When Claude calls a tool like `eval_run`, here's what happens:

1. Claude Code sends the tool call to the `vijil-mcp` process via stdin

2. `vijil-mcp` builds the CLI command: `vijil eval run --agent-id ... --harness-names '["safety"]' --json --wait`

3. The CLI sends the HTTP request to your Console API (with auth, team context, etc.)

4. The JSON response flows back: CLI -> `vijil-mcp` -> Claude Code

5. Claude reads the JSON and presents the results in natural language

The CLI handles all authentication, token refresh, and team context — the MCP server is a thin adapter.

## Troubleshooting

| Symptom                               | Fix                                                                 |
| ------------------------------------- | ------------------------------------------------------------------- |
| `vijil` CLI not found in `PATH`       | Run `pip install vijil-console`                                     |
| `vijil` CLI not configured            | Run `vijil init --url <your-url>`                                   |
| Session expired                       | Run `vijil login`                                                   |
| No team selected                      | Run `vijil team use <team_id>`                                      |
| Tools do not appear in Claude Code    | Verify `.mcp.json` is in the project root, then restart Claude Code |
| Claude uses Bash instead of MCP tools | Make sure `vijil-mcp` is in your `PATH` (`which vijil-mcp`)         |