Kaval

@usekaval/mcp

Before an AI agent acts, Kaval verifies the facts that action depends on and answers ALLOW, REVIEW, or BLOCK with a signed receipt. This package exposes that as an MCP server.

Policy engines decide whether an action is permitted under the rules; Kaval verifies whether the facts those rules depend on are still true.

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

0.6 was a breaking release. Nine tools became seven (before later portfolio/extraction tools landed), and everything removed folded into check; the

API answers 410 tool_retired for the old routes and this server translates that into an error

that tells the agent to call check. See Migrating from 0.5.

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

Resources

The server publishes these JSON resources:

• kaval://bulletins
• kaval://bulletins/extraction-attempts
• kaval://training-jobs
• kaval://training-feedback
• kaval://contracts/{contract_id}
• kaval://contracts/{contract_id}/claims
• kaval://contracts/{contract_id}/extraction-issues
• kaval://bulletins/{source_version_id}
• kaval://bulletins/extraction-attempts/{source_version_id}
• kaval://fact-imports/{import_id}
• kaval://training-jobs/{job_id}

The training resources are read-only. Feedback review and consent require training:manage.

Bulletin extraction status is read-only. MCP does not expose the operator requeue control.

MCP does not start training or promote a model.

check

// arguments

{ "action": "Approve this prior-authorization request at the in-network rate", "context": "payer: Aetna; CPT 12345; plan HMO", "materiality": "critical", }

Or skip extraction entirely by naming the facts:

{

"claims": [ { "subject": "Aetna", "predicate": "requires_prior_auth_for", "object": "CPT 12345", "scope": { "plan": "HMO", "state": "CA" }, }, "The 2024 IBC is the current edition", ], "mode": "fast", }

The response:

| decision | ALLOW — every material fact still holds on fresh evidence, proceed. REVIEW — something is unknown, mid-re-evaluation, or changed at low/medium materiality. REVIEW is never permission to act. BLOCK — a high/critical fact changed, or a critical fact is unknown. | | reason_codes | one or more of ALL_FACTS_HOLD, FACT_CHANGED, FACT_EXPIRED, FACT_UNKNOWN, SOURCE_UPDATED_PENDING_REVIEW, SOURCE_UNREACHABLE, NEW_FACT_UNVERIFIED, COMPILATION_UNCERTAIN | | facts[] | { fingerprint, text, status: holds \| changed \| unknown, materiality, served_from_state, last_verified_at, sources[] } — this is how you see _which_ belief moved | | receipt | { id, signature, signed_at }. Pass receipt.id to report_outcome, or to get_receipt for the full signed document