Metadata-Version: 2.4
Name: vijil-mcp
Version: 0.3.1
Summary: MCP server for the Vijil AI trust platform CLI
License: Apache-2.0
License-File: LICENSE
Author: Vijil AI
Author-email: engineering@vijil.ai
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: fastmcp (>=2.0)
Requires-Dist: vijil-console (>=0.1.42)
Description-Content-Type: text/markdown

# 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

```bash
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:

```bash
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:

```bash
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`](https://github.com/vijilAI/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.

| Variable | Default | Purpose |
|----------|---------|---------|
| `VIJIL_CLIENT_ID` + `VIJIL_CLIENT_SECRET` | — | Revocable API-key pair, exchanged for a bearer (preferred). Highest precedence; re-exchanged on expiry. Same credential `vijil-sdk` reads. |
| `VIJIL_API_KEY` | — | Raw bearer access token, sent verbatim. Escape hatch; not refreshable. Used only when the pair is unset. |
| `VIJIL_CONSOLE_URL` | `https://console-api.vijil.ai` | Platform/gateway URL override. |
| `VIJIL_TEAM_ID` | — | Team scope for team-scoped commands when not signed in interactively. |

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`](https://github.com/vijilAI/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:

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

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

```bash
vijil-console auth login
```

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

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

### 4. Add MCP config

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

```json
{
  "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}`:

| Group | Example tools | Description |
|-------|--------------|-------------|
| `agent` | `agent_list`, `agent_create`, `agent_get`, `agent_update`, `agent_import` | Manage AI agents |
| `eval` | `eval_run`, `eval_status`, `eval_list`, `eval_results_detail`, `eval_report` | Run and manage evaluations |
| `harness` | `harness_list`, `harness_custom_create`, `harness_custom_list` | Manage test harnesses |
| `dome` | `dome_config_list`, `dome_config_create`, `dome_detect` | Guardrail configuration and detection |
| `persona` | `persona_list`, `persona_create`, `persona_from_preset` | Manage test personas |
| `policy` | `policy_list`, `policy_create`, `policy_activate`, `policy_add_rule` | Compliance policies and rules |
| `telemetry` | `telemetry_logs`, `telemetry_traces`, `telemetry_metric_total` | Query observability data |
| `evolution` | `evolution_run`, `evolution_status` | Darwin evolution engine |
| `proposal` | `proposal_list`, `proposal_approve`, `proposal_reject` | Manage mutation proposals |
| `genome` | `genome_list`, `genome_get`, `genome_create`, `genome_extract` | Manage agent genomes |
| `demographics` | `demographics_list`, `demographics_create`, `demographics_values` | Demographic dimensions |
| `dimensions` | `dimensions_list`, `dimensions_create`, `dimensions_values` | Evaluation dimensions |
| `dashboard` | `dashboard_show` | Trust dashboard |
| `team` | `team_list`, `team_use` | Switch team context |
| `vijil_status` | `vijil_status` | Check CLI configuration |

### 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`):

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

| Error | Fix |
|-------|-----|
| "vijil-console not found in PATH" | Run `pip install vijil-console` |
| 401 with `VIJIL_CLIENT_ID` / `VIJIL_CLIENT_SECRET` set | The API-key pair was rejected (invalid or revoked) — mint a new one at Settings → API Keys |
| 401 with `VIJIL_API_KEY` set | The raw bearer token is invalid or expired — supply a fresh one, or switch to the key pair |
| "Session expired" (interactive login) | Run `vijil-console auth login` |
| "No team selected" | Run `vijil-console team use <team_id>` or set `VIJIL_TEAM_ID` |
| Tools don't appear in Claude Code | Check `.mcp.json` is in the project root and restart Claude Code |

