kcp-harness — KCP compliance proxy

kcp-harness

🧾 See it run — interactive KCP playground · read the reveal

Deterministic knowledge governance for any AI agent.

*Your agent can read every file in your project. Can it prove why it read what it read?*

KCP Harness is an MCP compliance proxy that sits between an AI coding agent and its tools. It intercepts knowledge-related calls, routes them through the kcp-agent deterministic planner (14-gate cascade, no LLM), and produces compliance artifacts — decision traces, audit logs, budget ledgers — as a side effect of normal agent operation.

The agent can't bypass governance because it only talks to the proxy's MCP interface. The proxy decides what knowledge is accessible, tracks spend, and logs every decision. Fail-closed: if the harness can't verify a request, the agent gets nothing.

Agent (Claude Code / Cursor / Copilot / Windsurf / Cline / Crush / OpenClaw / ...)

│ │ MCP tool call v ┌─────────────────────────────────────────────────────────┐ │ kcp-harness │ │ │ │ classify → govern (14 gates) → execute → audit │ │ │ │ Side outputs: │ │ · Decision traces (per-request, deterministic) │ │ · Audit log (append-only JSONL) │ │ · Budget ledger (itemized, ceiling-enforced) │ │ · Temporal drift (plan validity over time) │ │ · Approval tickets (named-human sign-off, durable) │ │ · Confidence verdicts (post-synthesis gate) │ └─────────────────────────────────────────────────────────┘ │ v Knowledge manifests (knowledge.yaml)

[Documentation →](https://cantara.github.io/kcp-harness/)

Why

Enterprises need agents that are *defensible* — auditable, reproducible, budget-controlled, temporally pinned. Today's agents can't prove why they read what they read. The harness adds a compliance layer without replacing the agent.

You sell the compliance layer. The agents are pluggable.

Install

npm install -g kcp-harness

Or use without installing:

npx kcp-harness --help

Native executables

Pre-built binaries (no Node/Deno required) for Linux x64/arm64, macOS x64/arm64, and Windows x64 — grab them from a release. To build one yourself:

npm ci && npm run build

deno compile --allow-read --allow-env --allow-net --allow-run \ --node-modules-dir=auto --output kcp-harness dist/cli.js

Quick start

1. Initialize

kcp-harness init          # creates harness.yaml

2. Generate agent integration

kcp-harness integrate claude-code    # or: pi, cursor, copilot, windsurf, cline, continue, crush, openclaw

3. Start coding

Your agent now routes knowledge access through the harness. Every decision is logged.

Supported agents

Each agent has its own MCP config format, rules file, and quirks. The integrate command handles them all — one governance layer, any agent.

How it works

Every tool call flows through a five-stage pipeline:

1. RECEIVE      MCP JSON-RPC request from agent

1. CLASSIFY Knowledge-navigation or pass-through?
2. GOVERN 14-gate cascade (audience → temporal → budget → ...)
3. EXECUTE Call downstream tool / return content
4. AUDIT Log decision to append-only audit log

Classifier

The classifier examines each tool call and determines whether it targets governed knowledge. Read("docs/api.md") where docs/ is governed? Route through the planner. Read("package.json") where package.json isn't governed? Pass through. KCP tools (kcp_plan, kcp_load) are always governed.

Governor

Two automated modes, plus a human gate that outranks both:

• Plan-first (fast path) — the agent calls kcp_plan first. The harness caches the approved plan. Subsequent reads are checked against the cached plan — no re-planning.
• Auto-plan (fallback) — the agent reads a governed path without planning. The harness runs the planner automatically. Slower, but governance is enforced even for agents that don't know about kcp_plan.
• Human approval — calls matching a governance.approvals rule are held for a named reviewer (pending), no matter what the automated paths would decide. Tickets survive restarts and resolve via the kcp-harness approvals CLI (or any custom ApprovalProvider channel). Resolutions require a named reviewer *and* a policy citation.

The 14-gate cascade

Every knowledge unit is evaluated through 14 deterministic gates, in order:

audience → not_for → temporal → deprecated → supersession → relevance →

skill_eligibility → attestation → payment → access → strict → max_units → money_budget → context_budget

A unit must pass all gates. The gate that blocks it is recorded in the decision trace. Same inputs → same plan. No model involved.

For the skill_eligibility gate's subject matter — governed kind: skill units — the authoring conventions, linter, and conformance vectors live in Cantara/kcp-skill.

MCP tools

Once connected, agents can use these governance tools:

Compliance artifacts

Audit log

Append-only JSONL. Every decision — governed or pass-through — is logged with sequence number, timestamp, tool, targets, and governance decision:

cat .kcp-harness/audit.jsonl | jq 'select(.governed == true)'

Budget ledger

Append-only itemized spend tracking. Per-currency running totals. Ceiling enforcement — a load that would exceed the budget is rejected atomically (no partial loads).

Temporal governance

Plans are registered with a temporal watcher. On subsequent calls, the watcher re-evaluates against the current time. If units have drifted (expired, newly valid), the harness emits a drift event. Long-running sessions stay honest.

Approval tickets

Calls matching an approval rule open a durable ticket (pending_review → approved | dismissed | expired, plus used for a consumed one-shot grant). The ticket store survives restarts — sessions are ephemeral, human review is not. Every resolution records *who* approved, *when*, and *which policy* it satisfies — evidence generated at approval time, never reconstructed from logs.

An approval is a bounded grant, never a standing permission. It covers the session that opened the ticket, the exact tool and target, and the call's arguments digest — and it lapses. Each rule sets grant: once | session | (default session), always capped by governance.approvals.grant_max (default 24h). A call outside a valid grant is denied, audited as grant_denied (expired, wrong_session, used, ...) and opens a *new* ticket. A standing permission is a policy rule, not a click. A grant's window is measured from the store's own clock, not the reviewer-supplied reviewedAt; the first valid resolution of a ticket wins (a dismissed ticket cannot be re-approved by an appended line); with approvals.require_signed_resolutions signatures are verified on every read, not only in resolve(); and approvals.require_args_binding refuses grants from tickets not bound to the call's arguments. What the ticket store does *not* protect — write access to its directory — is stated in the Ticket store trust model. See Governance Model.

Confidence verdicts

harness_assess runs kcp-agent's post-synthesis assess() over a synthesized answer before it may be acted on. The planner gates *loading*, grounding gates *asserting*, this gates *acting*. Below-threshold verdicts on routed configs open an approval ticket with the full verdict embedded as evidence.

Configuration

# harness.yaml

version: "1.0"

governance: domains:

• manifest: "./knowledge.yaml" paths: ["docs/", "src/"]

policy: fail_closed: true audit_all: true max_units: 5 budget: amount: 1.00 currency: USDC

confidence: # optional post-synthesis gate (harness_assess) threshold: 0.7 severity: critical route_to_role: account-owner

approvals: # optional human-approval gates provider: file rules:

• match: { tools: [Write, Edit], paths: [records/] } required_role: account-owner expires_after: 72h policy_ref: POL-7.2 grant: session # once | session | 15m / 4h / 1d (default: session) grant_max: 24h # hard cap on any approval's validity (default 24h)

require_signed_resolutions: true # + trusted_keys: verify signatures on every read (recommended)

require_args_binding: true # refuse grants not bound to the call's arguments (recommended)

audit: path: ".kcp-harness/audit.jsonl"

CLI

kcp-harness serve  [--config harness.yaml]   Start the MCP proxy

kcp-harness init Create a harness.yaml template kcp-harness check [--config harness.yaml] Validate configuration kcp-harness integrate [options] Generate agent integration files kcp-harness integrate --list List supported agents kcp-harness export [options] Export compliance evidence (SOC 2 / ISO 27001) kcp-harness dashboard [options] Launch the live compliance dashboard kcp-harness approvals list [--state s] List human-approval tickets kcp-harness approvals approve --reviewer --policy-ref kcp-harness approvals dismiss --reviewer -