Verifies the facts an AI agent's action depends on by returning ALLOW, REVIEW, or BLOCK decisions with signed receipts.
Also known as usekaval/kaval-clients, @usekaval/mcp
- Stars
- 0
- Tools
- 40
- Downloads, 30 days
- —
- Latest version
- 0.8.2
- Last commit
- Sep 10, 2026
- License
- Apache-2.0
What is Kaval MCP?
Kaval verifies the facts an AI agent's action depends on by returning ALLOW, REVIEW, or BLOCK decisions with signed receipts. It exposes 40 tools, such as check, get_receipt, prepare_contract_upload.
Summary generated from the project's README
About Kaval MCP server
Kaval provides a verification layer for AI agents by validating the facts that underpin their intended actions. Instead of letting an agent act on potentially outdated or incorrect information, this server returns specific decisions: ALLOW, REVIEW, or BLOCK. Each decision includes a signed receipt that serves as a verifiable record of the check. This tool is designed for developers building autonomous agents that require high levels of accuracy and accountability.
The server operates as a thin client that communicates with a hosted Kaval API via stdio. Because all heavy lifting like compilation, grounding, and retrieval happens on the server side, you only need to provide a Kaval API key to get started. You do not need to manage local models or search keys. The primary tool for this process is the check command, which evaluates actions or specific claims against current evidence to ensure everything remains true before an agent proceeds.
What you can do with it
- 1Verify action claimsAsk the agent to check if specific claims or an intended action are still valid based on current evidence.
- 2Retrieve signed evidenceRequest the full signed document associated with a specific check ID to provide proof of the decision.
- 3Manage contract extractionQueue a PDF or HTTPS document for text extraction and monitor its processing status.
- 4Bulk fact importationUpload a large set of reviewed facts to prepare them for rapid verification checks.
Written from the project's README. Every use case is checked against a quote from it.
How to install Kaval MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Kaval MCP in Claude Code
$ claude mcp add --env 'KAVAL_API_KEY=<YOUR_KAVAL_API_KEY>' kaval -- npx -y @usekaval/mcpInstall Kaval MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"kaval": {
"command": "npx",
"args": [
"-y",
"@usekaval/mcp"
],
"env": {
"KAVAL_API_KEY": "<YOUR_KAVAL_API_KEY>"
}
}
}
}Install Kaval MCP in VS Code
.vscode/mcp.json
{
"servers": {
"kaval": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@usekaval/mcp"
],
"env": {
"KAVAL_API_KEY": "<YOUR_KAVAL_API_KEY>"
}
}
}
}Install Kaval MCP in VS Code CLI
$ code --add-mcp '{"name":"kaval","type":"stdio","command":"npx","args":["-y","@usekaval/mcp"],"env":{"KAVAL_API_KEY":"<YOUR_KAVAL_API_KEY>"}}'Install Kaval MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"kaval": {
"command": "npx",
"args": [
"-y",
"@usekaval/mcp"
],
"env": {
"KAVAL_API_KEY": "<YOUR_KAVAL_API_KEY>"
}
}
}
}Install Kaval MCP in Codex
$ codex mcp add kaval --env 'KAVAL_API_KEY=<YOUR_KAVAL_API_KEY>' -- npx -y @usekaval/mcpInstall Kaval MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.kaval] command = "npx" args = ["-y", "@usekaval/mcp"] [mcp_servers.kaval.env] KAVAL_API_KEY = "<YOUR_KAVAL_API_KEY>"
Install Kaval MCP in Gemini CLI
$ gemini mcp add -s user -e 'KAVAL_API_KEY=<YOUR_KAVAL_API_KEY>' kaval npx -- -y @usekaval/mcpInstall Kaval MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"kaval": {
"command": "npx",
"args": [
"-y",
"@usekaval/mcp"
],
"env": {
"KAVAL_API_KEY": "<YOUR_KAVAL_API_KEY>"
}
}
}
}Kaval MCP tools 40
Detected from the READMEcheckget_receiptprepare_contract_uploadingest_contractget_contractlist_contract_claimslist_contract_extraction_issuesreview_contract_claimimport_factsget_fact_importlist_bulletinsget_bulletin
Show all 40 toolsShow fewer tools
list_bulletin_extraction_attemptsget_bulletin_extraction_attemptlist_training_jobsget_training_joblist_training_feedbackrecord_training_feedback_consentcreate_extraction_schemalist_extraction_schemascreate_extraction_runget_extraction_runlist_extraction_runslist_extraction_packageslist_publisherscreate_publisherget_publisherupdate_publisheradd_sourcelist_sourcesremove_sourceupdate_sourceget_source_version_contentreport_outcomeverifyerrortool_retiredtimeoutnetwork_unreachablerequest_ambiguous
Configuration
KAVAL_API_KEYRequiredSecretBring-your-own Kaval bearer key (kv_live_…). Create one at https://usekaval.com.
KAVAL_BASE_URLPoint at a self-hosted or staging Kaval API instead of the hosted one. Defaults to https://api.usekaval.com.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableusekaval/kaval-clients is public and reachablegithub.com/usekaval/kaval-clients ↗Pass
- Package names this repository as its source@usekaval/mcp names usekaval/kaval-clients as sourcenpmjs.com/package/@usekaval/mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @usekaval/mcpnpmjs.com/package/@usekaval/mcp/v/0.8.2#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-10github.com/usekaval/kaval-clients ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @usekaval/mcpPass
- No critical advisory in the package or its dependencies100 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model40 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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 answers410 tool_retiredfor the old routes and this server translates that into an error that tells the agent to callcheck. 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
| Tool | What it does |
|---|---|
check |
The one that does the work. Send the action you are about to take (or the claims it rests on) → ALLOW / REVIEW / BLOCK, per-fact status, and a signed receipt. |
get_receipt |
The full signed document behind a check's receipt.id — per-fact evidence basis, decision-rule version, signing key. What an agent attaches when it blocks. |
prepare_contract_upload |
Create a private PDF upload target. |
ingest_contract |
Queue canonical text, an HTTPS document, or an uploaded PDF for extraction. |
get_contract |
Get contract processing status, candidate counts, and extraction issue state. |
list_contract_claims |
List extracted candidates with exact evidence spans. |
list_contract_extraction_issues |
List deterministic extraction failures that need customer review. |
review_contract_claim |
Approve, correct, or reject one candidate with immutable version control. |
import_facts |
Queue up to 400 reviewed facts for warm checks. |
get_fact_import |
Get one bulk import and every item result. |
list_bulletins |
Soft-deprecated — filter structured bulletins by payer, policy, code, date, or status. Prefer list_extraction_runs for new integrations. |
get_bulletin |
Soft-deprecated — get one structured bulletin with field evidence. Prefer get_extraction_run. |
list_bulletin_extraction_attempts |
Soft-deprecated — list customer-readable bulletin extraction status and failures. Prefer list_extraction_runs. |
get_bulletin_extraction_attempt |
Soft-deprecated — get one bulletin extraction attempt by source-version id. Prefer get_extraction_run. |
list_training_jobs |
List read-only training and evaluation status. |
get_training_job |
Get one read-only training job. |
list_training_feedback |
List reviewed feedback and its effective training-use state. |
record_training_feedback_consent |
Record an explicit training-use decision for one reviewed feedback item. |
create_extraction_schema |
Register a JSON Schema Kaval extracts structured records against. Requires policy-update:manage. |
list_extraction_schemas |
List the extraction schemas registered in this workspace. |
create_extraction_run |
Request a one-off publisher + period extraction run against a bound schema. Requires policy-update:manage. |
get_extraction_run |
Get one extraction run by id — status, schema, and result once it succeeds. |
list_extraction_runs |
List extraction runs with publisher/period/time filters, cursor pagination, and nested document chrome (pass expand_document: false to omit). |
list_extraction_packages |
List the monthly PDF + manifest rollups extraction runs are packaged into. |
list_publishers |
List org-owned publishers for this workspace's billing account. |
create_publisher |
Create an org-owned publisher (UUID identity; renameable display name). |
get_publisher |
Get one org-owned publisher by UUID. |
update_publisher |
Rename an org-owned publisher. UUID identity is unchanged. |
add_source |
Tell Kaval what to watch — requires publisher_id (org publisher UUID). A URL, a named authority to resolve, or a document you will push in. |
list_sources |
What Kaval currently watches for this workspace, including sources it auto-registered after a check cited them. |
remove_source |
Stop watching a source and forget it. The only thing that frees a registered/resolved workspace slot (auto-registered citations count there; discovered children use a separate per-parent ceiling). |
update_source |
Bind (or unbind) an extraction schema and/or set publisher_id on a watched source. Pass reprocess: true to fill-missing re-extract prior versions. Requires policy-update:manage. |
get_source_version_content |
Fetch the captured content of one fetched source version, as raw text or pre-split sections. |
report_outcome |
Report what actually happened after a prior check (by receipt.id), so Kaval can calibrate. |
verify |
Deprecated pilot alias: one conclusion + explicit evidence_refs → a signed ProofPacket receipt. Use check. |
Resources
The server publishes these JSON resources:
kaval://bulletinskaval://bulletins/extraction-attemptskaval://training-jobskaval://training-feedbackkaval://contracts/{contract_id}kaval://contracts/{contract_id}/claimskaval://contracts/{contract_id}/extraction-issueskaval://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:
| field | meaning |
|---|---|
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 |
latency_ms |
{ compile, lookup, live, total } |
mode: "fast" answers only from stored state and reports anything unknown as unknown;
"standard" (default) may research a stale or novel fact within max_wait_ms. A fact that misses
the budget comes back unknown — it does not warm the next check, because that check recompiles
the action and asks about different fact fingerprints.
The budget. The API's own default is 100000 ms, because a cold action check with several novel
premises routinely needs 50–100s of live research. MCP cannot spend that: an MCP client cancels a
tool call after 60s. So this server sends max_wait_ms: 45000 explicitly and caps the argument
there, and gives its HTTP client a 55s deadline so the timeout fires here — as
{"error":"timeout"} with a recovery move — rather than as a cancelled request. Pass a smaller
max_wait_ms when a bounded REVIEW beats waiting; 0 disables research entirely, which is what
mode: "fast" does. Direct HTTP and SDK callers are not bound by any of this and get the full
100000.
A fact already backed by a watched source is answered from stored state with zero model calls and
zero fetches, so calling check on every consequential action is cheap. A fact Kaval has
never seen has to be researched first, and that takes seconds.
Keeping checks warm
add_source is what makes a check a database read instead of a research run. Registering the name
of an authority is usually enough:
{ "kind": "entity", "name": "Aetna", "intent": "payer policy bulletins" }
Kaval resolves that to the pages that publish it and watches them adaptively. kind: "url" watches
one page; kind: "push" is a document your own system sends to POST /v1/events. Registering is
optional — a source a check cites is auto-watched — but registering first is what makes the first
check on a fact fast.
That auto-watching is why remove_source exists. Capacity is two ceilings, not one:
- up to 200 active
registered/resolvedsources per workspace (auto-registered citations count here; discovered children do not) - up to 200 active
discoveredchildren per parent
Only deletion frees a slot — pausing does not. An agent that registers per task and never removes will eventually fill the workspace registered/resolved ceiling, after which new citations are dropped silently and checks that used to be warm go back to researching. Remove what a task registered when the task is done.
Extractions
create_extraction_schema registers a JSON Schema; bind its id to a watched source with
update_source({ id, extraction_schema_id }) and every document that lands on that source afterward
is extracted against the schema automatically — no polling. Pass reprocess: true to also
fill-missing re-extract versions that already ran under another schema; those webhooks carry
source_change: "schema_changed" (join the original extract on source_version_id). For a one-off
run against a publisher + period instead of waiting for the next document, call create_extraction_run
directly. Either way,
get_extraction_run / list_extraction_runs report the run's lifecycle
(processing → retry → succeeded / review_required / failed), and
list_extraction_packages lists the monthly PDF + manifest rollups each publisher/period is packaged
into. Each package's pdf_href is a durable Kaval URL — GET (or HEAD) it and follow the 302
to a short-lived signed PDF (MCP does not expose a separate download tool; use HTTP with redirects).
get_source_version_content fetches the canonical text (or format: "sections") an extraction run
was computed from.
This is the schema-bound successor to the free-text bulletin tools (list_bulletins, get_bulletin,
list_bulletin_extraction_attempts, get_bulletin_extraction_attempt), which are soft-deprecated but
keep working.
Delta webhooks are not an agent tool
Watched sources are only half the mechanism: when a source changes, Kaval re-evaluates the dependent
facts and pushes a fact_state.delta webhook naming what flipped; a source with a bound extraction
schema also pushes extraction.document (and, monthly, extraction.package) with the
extracted records (nested evidence on each record) and optional section page/bbox for PDF highlighting.
extraction_run.period is the publication / newsletter month. Those subscriptions are
deliberately not exposed as MCP tools. They are
one-time deployment configuration — each mints a standing outbound callback bound to an https
endpoint and a signing secret that must be stored, which is a deploy-time decision for a human or a
service, not an in-loop choice for an agent that owns neither the endpoint nor the secret.
Configure them once from the SDK (kaval.subscribeFactStateDeltas({ callback_url }) /
kaval.subscribeExtractions({ callback_url }) in Node, kaval.subscribe_fact_state_deltas(…) /
kaval.subscribe_extractions(…) in Python), from POST /v1/webhooks with
subscription_kind: "fact_state" or "extraction" (policy_update is rejected on create), or from
the dashboard. The agent then just
calls check (or reads list_extraction_runs), and it is already fast and already current.
Migrating from 0.5
| 0.5 tool | 0.6 |
|---|---|
currentness_check |
check — { action } or { claims: ["…"] } |
currentness_verify |
check — branch on decision === "ALLOW" instead of act === true |
currentness_extract_and_check |
check — pass the paragraph as action/context; Kaval compiles the facts itself |
currentness_scan_store |
check — { claims: [...] }, up to 20 per call |
currentness_monitor |
add_source + a fact_state webhook subscription (see above) — deltas are pushed to you |
proof_audit |
check — the receipt is the proof; get_receipt returns the signed document |
proof_gate |
check — the warm path re-checks from stored state, so there is nothing to re-apply |
report_outcome |
report_outcome (unchanged; pass receipt.id) |
verify |
verify, now deprecated → move to check |
Status mapping: current + act: true → decision: "ALLOW" with every fact holds;
stale/contradicted → a fact changed (REVIEW or BLOCK by materiality);
unsupported/insufficient/conflicting → a fact unknown (REVIEW, or BLOCK if critical).
A 0.5 client calling a removed route gets 410 {"error":"tool_retired","replacement":"/v1/check"},
which this server surfaces as {"error":"tool_retired","message":"this capability was folded into the check tool …","status":410}.
Idempotency
Contract uploads, contract creation, claim reviews, fact imports, create_extraction_schema,
create_extraction_run, and verify carry operation keys. The server creates a key when you omit
one. Reuse the returned key after an ambiguous failure.
check deliberately carries none: it is a read of current state, so a retry recomputes rather than
replays and cannot double-count.
Tool errors
A failed tool call returns isError: true and a JSON body naming what happened, so an agent can
branch on it rather than parse prose.
error |
what to do |
|---|---|
any API code (unauthorized, subscription_required, bad_request, …) |
returned verbatim with status and the API's message |
tool_retired |
410 — the message names the route that replaced the one you called |
timeout |
retry with mode: "fast" or a smaller max_wait_ms |
network_unreachable |
the API was never reached — check KAVAL_BASE_URL and network access |
request_ambiguous |
an idempotent call whose outcome is unknown; retry with the returned idempotency_key |
Signed receipts
Check receipts are Ed25519-signed and self-derivable: because the decision table is published, the
receipt's own fact list re-derives the verdict offline, byte for byte, with no server. Verify one
with @usekaval/kaval/verify — a dependency-free subpath of the Node SDK this package already
depends on, plus the kaval-receipt-verify CLI that SDK ships. It answers cryptographic validity,
key trust, and freshness separately, needs no Kaval account and no API key, and reads the public
keys from the unauthenticated GET /v1/proof-verification-keys/:kid — or from a keyset you archived
beside the receipt, which is the fully offline path.
npx -p @usekaval/kaval kaval-receipt-verify verify receipt.json \
--key-url https://api.usekaval.com/v1/proof-verification-keys
check returns only { id, signature, signed_at }. Call get_receipt with that id for the
document that was actually signed — every fact with its state, the evidence basis under it (source
locator, content digest and what the digest covers, fetch and publication time), the decision-rule
version, and the signing key id. That is the artifact to attach to a BLOCK you escalate.
Honest boundaries: demo results carry no organizational authority; a production ALLOW requires
a customer-bound action policy and applicable empirical calibration; REVIEW is never permission to
act.
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 |
Both are declared in server.json and smithery.yaml, so a registry install can point at a
self-hosted deployment rather than only at the hosted API.
The marketing site uses KAVAL_API_URL for its /api/verify proxy — not KAVAL_BASE_URL.
Kaval MCP questions
How do I add Kaval MCP to Claude Code?
Run claude mcp add --env 'KAVAL_API_KEY=<YOUR_KAVAL_API_KEY>' kaval -- npx -y @usekaval/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Kaval MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Kaval MCP provide?
It exposes 40 tools, including check, get_receipt, prepare_contract_upload, ingest_contract, get_contract.
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.