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. If your Console uses a private CA

A self-managed Console often terminates TLS with a certificate from your own PKI, which certifi does not carry — so step 2 fails with a certificate error even though the URL is right. Point VIJIL_CA_BUNDLE at a PEM file containing that CA:

export VIJIL_CA_BUNDLE=/etc/ssl/certs/your-internal-ca.pem

It is additive: the CLI verifies against the OS trust store, certifi, and that file. It never disables verification.

This value cannot be persisted anywhere — there is no config key for it — so the MCP server needs it in its own env block as well as in your shell, because the server captures its environment at spawn:

"env": { "VIJIL_CA_BUNDLE": "${VIJIL_CA_BUNDLE:-}" }

vijil-console auth status --json reports it as ca_bundle (null when unset), and so does the vijil_status tool, so a missing or stale bundle is visible rather than mysterious.

5. 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}"
      }
    }
  }
}

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 plugin ships in its manifest.)

Note the two shapes, and copy them as written. The :- on a credential is the belt: hosts that support it emit an empty string rather than the literal text ${VIJIL_API_KEY} when the variable is unset in your shell. The braces on VIJIL_CONSOLE_URL carry no :- default: pinning the public gateway there would override a self-hosted console_url already on disk (CON-723). Either way the CLI treats an unexpanded ${NAME} as unset for every one of these variables — credentials included — so a host that ignores :- cannot turn a placeholder into a credential that shadows your session (CON-725).

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

6. 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. The URL carrier at ~/.vijil/credentials.json — its url field, written by whichever client (this CLI or the vijil SDK) logged in most recently, so a URL learned by one is visible to the other.

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

A console_url that is not an http(s):// URL is a configuration error naming the file it came from, never a network error. When two of these sources name different hosts, the CLI prints one warning on stderr naming both — a token minted at one Console and sent to another is the usual cause of an unexplained 401.

VIJIL_CONSOLE_URL is not an ephemeral override at login time: vijil-console auth login / login-browser persist the URL they signed in against into config.yaml, so a login performed with the variable set pins that host durably and unsetting it afterwards does not undo it. Run vijil-console auth init --url <other> to move it.

This server captures its environment at spawn. Exporting or unsetting a VIJIL_* variable in your shell does not reach an already-running server — reconnect it (restart Claude Code, or toggle the server off and on) for the change to take effect.

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