Metadata-Version: 2.4
Name: vijil-mcp
Version: 0.1.19
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
Requires-Dist: fastmcp (>=2.0)
Requires-Dist: vijil-console (>=0.1.4)
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 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` CLI 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 vijil-mcp
```

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

## Connecting to a deployed 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 auth init --url https://console-api.example.com
```

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

### 3. Authenticate

```bash
vijil auth login
```

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

```bash
vijil team list
vijil 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"
    }
  }
}
```

**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 |
| `redteam` | `redteam_run`, `redteam_list`, `redteam_results`, `redteam_tools` | Red team attack campaigns |
| `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`, `redteam_run`, `evolution_run`). When `wait=True`, the tool polls until the operation completes (up to 10 minutes).

## Configuration

All connection state is managed by the CLI and stored in `~/.vijil/config.yaml`:

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

Token refresh is automatic — if a request returns 401, the CLI attempts a refresh before failing.

## Troubleshooting

| Error | Fix |
|-------|-----|
| "vijil CLI not found in PATH" | Run `pip install vijil-console` |
| "Vijil CLI not configured" | Run `vijil auth init --url <your-url>` |
| "Session expired" | Run `vijil auth login` |
| "No team selected" | Run `vijil team use <team_id>` |
| Tools don't appear in Claude Code | Check `.mcp.json` is in the project root and restart Claude Code |

