@usekaval/mcp

@usekaval/mcp

The Kaval action-verification layer as an MCP server. It builds durable, action-bound proof packets and returns ALLOW, BLOCK, or REVIEW before an agent sends, quotes, approves, updates, grants, or transacts. Compatibility currentness tools remain available for a cached fact, stored field, retrieved RAG chunk, or prior answer.

This package is a thin client over the hosted Kaval API. All classification, grounding, and retrieval run server-side, so you bring just a Kaval API key — no model or search keys, no local engine.

Billable tool calls automatically carry a unique operation key. The underlying client reuses it for one bounded retry only when the transport outcome is ambiguous or the API is still finalizing the same operation, preventing duplicate billing without retrying terminal errors.

If both attempts remain ambiguous, the tool error includes idempotency_key. Retry later by passing that exact value back as the optional idempotency_key argument on the same billable tool. Omit it for a genuinely new operation.

Run it

npx -y @usekaval/mcp

It speaks MCP over stdio. Point any MCP client at it.

Client config

{
  "mcpServers": {
    "kaval": {
      "command": "npx",
      "args": ["-y", "@usekaval/mcp"],
      "env": {
        "KAVAL_API_KEY": "kv_live_…",
      },
    },
  },
}

Tools

Tool	What it does
currentness_verify	Pre-action gate: returns act (boolean) + a typed verdict + proof. Call before acting on a held belief.
currentness_check	The raw freshness verdict without the act/don't-act decision.
currentness_extract_and_check	Pull the checkable beliefs out of a paragraph and re-ground each.
currentness_scan_store	Sweep a batch of beliefs for drift (summary + the riskiest).
currentness_monitor	Sweep + POST the newly-risky beliefs to a webhook (run on a schedule).
proof_audit	Build a complete action-bound ProofPacket with exact evidence, policy, lineage, risk, and expiry.
proof_gate	Apply a durable proof to the exact action and return staged enforcement without repeating research.
report_outcome	Report what actually happened for a prior check so the service can calibrate.

For consequential actions, call proof_audit, then proof_gate immediately before execution. Only when enforcement.controlApplied is true may Kaval control the action; then honor enforcement.executionAllowed exactly. In shadow mode controlApplied is false, executionAllowed is null, and wouldAllow is counterfactual telemetry—the customer's existing action path remains authoritative. If enforcement is absent, a direct integration should fail closed unless the proof state is current and the decision is ALLOW.

A verdict status is one of: current, stale, contradicted, unsupported, conflicting, insufficient. Treat anything other than current (or act === false) as "re-research before relying on it".

Environment

Var	Required	Purpose
KAVAL_API_KEY	yes	Bearer key for the hosted Kaval API (create one at https://usekaval.com)
KAVAL_BASE_URL	no	Override the API base URL (self-hosted / staging). Defaults to https://api.usekaval.com

The marketing site uses KAVAL_API_URL for its /api/verify proxy — not KAVAL_BASE_URL.

Programmatic use

This package is primarily a CLI (kaval-mcp). It also exports the server factory for embedding:

import { createMcpServer, createClientFromEnv } from "@usekaval/mcp";

const server = createMcpServer(createClientFromEnv());
// connect `server` to your own MCP transport

Or pass your own configured client:

import { createMcpServer } from "@usekaval/mcp";
import { Kaval } from "@usekaval/kaval";

const server = createMcpServer(
  new Kaval({ apiKey: process.env.KAVAL_API_KEY }),
);