vijil-mcp

MCP (Model Context Protocol) server for the Vijil AI trust platform. Lets Claude Code interact with Vijil Console APIs through typed tools — using the CLI under the hood.

How it works

Claude Code  ←── stdio ──→  vijil-mcp (local process)  ─── vijil-console CLI ──→  Vijil Console API

The MCP server is a local process on your machine — not a deployed server. Claude Code spawns it as a subprocess, discovers its tools automatically, and calls them during conversations. Each tool runs a vijil-console command and returns JSON output.

Prerequisites

• Python 3.10+
• A Vijil Console account with API access
• Claude Code (CLI, desktop app, or VS Code extension)

Install

pip install vijil-mcp
# or isolated:
pipx install --include-deps vijil-mcp

--include-deps is required for the pipx path — pipx only exposes a package's own console scripts by default, so a plain pipx install vijil-mcp leaves vijil-console (a dependency, not vijil-mcp itself) unreachable on PATH. The tradeoff: it also exposes every other dependency's scripts.

This automatically installs vijil-console (the CLI) as a dependency.

Upgrading an environment that predates this rename

If this environment already has both vijil-console and vijil-sdk installed from before this rename (they used to collide on the vijil command and the vijil_cli package — see below), do not pip install --upgrade them in place, in either order. Fully uninstall both first, then reinstall:

pip uninstall vijil-console vijil-sdk
pip install --upgrade vijil-console vijil-sdk   # or vijil-mcp, which pulls in vijil-console

Why: pre-rename, both packages wrote files to the same paths (the vijil script, and — before a companion vijil-sdk fix — the vijil_cli package directory), so each package's installed-files manifest (RECORD) still lists paths it no longer actually owns. An in-place upgrade of either package uninstalls its old version first, and that uninstall deletes every path in the old RECORD — including ones the other package has since taken over — regardless of which package currently owns them. Verified directly: upgrading vijil-sdk first then vijil-console deletes the freshly-upgraded SDK's vijil script; upgrading in the other order instead deletes files out of the freshly-upgraded Console's package directory. Only a full uninstall-then-reinstall leaves a clean, correct result in both directions. A fresh environment that never had the pre-rename collision is unaffected by any of this.

Connecting to the public platform (recommended)

For the hosted Vijil platform, the server needs no vijil-console auth init / vijil-console auth login. It defaults to the public gateway https://console-api.vijil.ai and authenticates from the environment. Use the API-key pair you mint at console.vijil.ai → Settings → API Keys — the preferred headless credential because it is revocable, scoped, and self-healing:

export VIJIL_CLIENT_ID=vk_...          # the API key's client ID
export VIJIL_CLIENT_SECRET=...         # the paired secret, shown once at creation
# optional, for a non-production environment:
# export VIJIL_CONSOLE_URL=https://console-api.dev05.vijil.ai
# optional, to pin a team for team-scoped tools:
# export VIJIL_TEAM_ID=<team_id>

The CLI exchanges the pair for a short-lived bearer token (POST /v1/auth/token) and re-exchanges automatically when it expires — so long-running headless sessions do not break. This is the same vk_ credential vijil-sdk reads, so one key authenticates both surfaces.

If you already hold a raw access token, VIJIL_API_KEY=<access-token> is an escape hatch — sent verbatim as Authorization: Bearer, with no exchange. It is not refreshable (a 401 means it expired), so prefer the pair for anything long-running.

Because auth is an env var rather than an interactive login, this is the path used by scheduled/headless runs and by the vijil-adlc Claude Code plugin, which declares this server in its plugin manifest. Add the MCP config (step 4 below) and you are done.

Connecting to a self-managed environment

The MCP server uses the CLI for all API communication. Configure the CLI once and the MCP server inherits the connection.

1. Find your Console API URL

If you have kubectl access to the EKS cluster:

kubectl get svc vijil-console-nginx -n vijil-console \
  -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

This gives you the raw ELB hostname. If a DNS record exists (e.g., console-api.dev05.vijil.ai), use that instead.

2. Initialize the CLI

vijil-console auth init --url https://console-api.example.com

Or run vijil-console auth init without arguments to be prompted for the URL. The CLI verifies connectivity before saving.

3. Authenticate

vijil-console auth login

You will be prompted for your email and password. If you belong to multiple teams, select one:

vijil-console team list
vijil-console team use <team_id>

4. Add MCP config

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

{
  "mcpServers": {
    "vijil": {
      "type": "stdio",
      "command": "vijil-mcp",
      "env": {
        "VIJIL_API_KEY": "${VIJIL_API_KEY}",
        "VIJIL_CONSOLE_URL": "${VIJIL_CONSOLE_URL:-https://console-api.vijil.ai}"
      }
    }
  }
}

The env block is optional if you authenticated the CLI interactively, but it is what lets the server connect to the public platform with no vijil-console auth step. (This is exactly the block the vijil-adlc plugin ships in its manifest.)

Alternative locations:

• Project-level (shared via git): .mcp.json in project root
• User-level (all projects): ~/.claude.json
• Local-only (not committed): .claude/mcp.json in project root

5. Use with Claude Code

Start Claude Code in a directory with .mcp.json. The Vijil tools appear automatically. Ask Claude things like:

• "List my agents"
• "Run a safety evaluation on agent X"
• "Show the latest evaluation results"
• "Create a red team campaign against my agent"
• "What's on my trust dashboard?"

Available tools

All CLI commands are exposed as MCP tools (116 total). Tool names follow the pattern {group}_{command}:

Async operations

Some tools support a wait parameter (eval_run, evolution_run). When wait=True, the tool polls until the operation completes (up to 10 minutes).

Configuration

Connection state resolves in this order (highest first):

1. Environment variables — VIJIL_CLIENT_ID + VIJIL_CLIENT_SECRET (preferred), or VIJIL_API_KEY, plus VIJIL_CONSOLE_URL and VIJIL_TEAM_ID.

2. On-disk CLI config at ~/.vijil/config.yaml (written by vijil-console auth login):

   console_url: https://console-api.example.com
   auth_token: eyJhbG...
   refresh_token: ...
   default_team_id: c58aea71-3861-4f28-b8c4-20832a2f22ee
   

3. Default — console_url falls back to the public gateway https://console-api.vijil.ai.

Token recovery on a 401 depends on the credential. An API-key pair is re-exchanged automatically for a fresh bearer (so headless sessions self-heal). An interactive JWT session is refreshed via /auth/jwt/refresh. A raw VIJIL_API_KEY bearer is not refreshable — a 401 means it is invalid or expired.

Troubleshooting