# Kaval MCP server

> Verifies the facts an AI agent's action depends on by returning ALLOW, REVIEW, or BLOCK decisions with signed receipts.

- Repository: https://github.com/usekaval/kaval-clients
- Page: https://hostedmcp.org/servers/usekaval/kaval
- Transport: stdio
- Stars: 0
- License: Apache-2.0
- Latest version: 0.8.2

## Install

### Claude Code

```sh
claude mcp add --env 'KAVAL_API_KEY=<YOUR_KAVAL_API_KEY>' kaval -- npx -y @usekaval/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "kaval": {
      "command": "npx",
      "args": [
        "-y",
        "@usekaval/mcp"
      ],
      "env": {
        "KAVAL_API_KEY": "<YOUR_KAVAL_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "kaval": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@usekaval/mcp"
      ],
      "env": {
        "KAVAL_API_KEY": "<YOUR_KAVAL_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"kaval","type":"stdio","command":"npx","args":["-y","@usekaval/mcp"],"env":{"KAVAL_API_KEY":"<YOUR_KAVAL_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "kaval": {
      "command": "npx",
      "args": [
        "-y",
        "@usekaval/mcp"
      ],
      "env": {
        "KAVAL_API_KEY": "<YOUR_KAVAL_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add kaval --env 'KAVAL_API_KEY=<YOUR_KAVAL_API_KEY>' -- npx -y @usekaval/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.kaval]
command = "npx"
args = ["-y", "@usekaval/mcp"]

[mcp_servers.kaval.env]
KAVAL_API_KEY = "<YOUR_KAVAL_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'KAVAL_API_KEY=<YOUR_KAVAL_API_KEY>' kaval npx -- -y @usekaval/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "kaval": {
      "command": "npx",
      "args": [
        "-y",
        "@usekaval/mcp"
      ],
      "env": {
        "KAVAL_API_KEY": "<YOUR_KAVAL_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `KAVAL_API_KEY` | yes | yes | Bring-your-own Kaval bearer key (kv_live_…). Create one at https://usekaval.com. |
| `KAVAL_BASE_URL` | no | no | Point at a self-hosted or staging Kaval API instead of the hosted one. Defaults to https://api.usekaval.com. |

## Tools (40)

- `check`
- `get_receipt`
- `prepare_contract_upload`
- `ingest_contract`
- `get_contract`
- `list_contract_claims`
- `list_contract_extraction_issues`
- `review_contract_claim`
- `import_facts`
- `get_fact_import`
- `list_bulletins`
- `get_bulletin`
- `list_bulletin_extraction_attempts`
- `get_bulletin_extraction_attempt`
- `list_training_jobs`
- `get_training_job`
- `list_training_feedback`
- `record_training_feedback_consent`
- `create_extraction_schema`
- `list_extraction_schemas`
- `create_extraction_run`
- `get_extraction_run`
- `list_extraction_runs`
- `list_extraction_packages`
- `list_publishers`
- `create_publisher`
- `get_publisher`
- `update_publisher`
- `add_source`
- `list_sources`
- `remove_source`
- `update_source`
- `get_source_version_content`
- `report_outcome`
- `verify`
- `error`
- `tool_retired`
- `timeout`
- `network_unreachable`
- `request_ambiguous`

## FAQ

### How does Kaval decide whether to allow an action?

Kaval verifies if the facts that rules depend on are still true and answers with ALLOW, REVIEW, or BLOCK.

### Does the MCP server require a local model or search engine?

No, it is a thin client that runs all compilation, grounding, and retrieval server-side using a Kaval API key.

### What should an agent do if it receives a REVIEW decision?

A REVIEW decision is never permission to act; it indicates something is unknown, mid-re-evaluation, or changed at low/medium materiality.
