{
  "markdown": "# kcp-harness\n\n### 🧾 See it run — [interactive KCP playground](https://cantara.github.io/pi-kcp/playground/) · [read the reveal](https://wiki.totto.org/blog/2026/07/22/the-ai-agent-that-keeps-the-receipts/)\n\n\n**Deterministic knowledge governance for any AI agent.**\n\n> *Your agent can read every file in your project. Can it prove why it read what it read?*\n\nKCP Harness is an MCP compliance proxy that sits between an AI coding agent and its tools. It\nintercepts knowledge-related calls, routes them through the\n[kcp-agent](https://github.com/Cantara/kcp-agent) deterministic planner (14-gate cascade, no LLM),\nand produces compliance artifacts — decision traces, audit logs, budget ledgers — as a side effect\nof normal agent operation.\n\nThe agent can't bypass governance because it only talks to the proxy's MCP interface. The proxy\ndecides what knowledge is accessible, tracks spend, and logs every decision. **Fail-closed: if the\nharness can't verify a request, the agent gets nothing.**\n\n```\nAgent (Claude Code / Cursor / Copilot / Windsurf / Cline / Crush / OpenClaw / ...)\n  │\n  │  MCP tool call\n  v\n┌─────────────────────────────────────────────────────────┐\n│  kcp-harness                                            │\n│                                                         │\n│  classify → govern (14 gates) → execute → audit         │\n│                                                         │\n│  Side outputs:                                          │\n│  · Decision traces     (per-request, deterministic)     │\n│  · Audit log           (append-only JSONL)              │\n│  · Budget ledger       (itemized, ceiling-enforced)     │\n│  · Temporal drift      (plan validity over time)        │\n│  · Approval tickets    (named-human sign-off, durable)  │\n│  · Confidence verdicts (post-synthesis gate)            │\n└─────────────────────────────────────────────────────────┘\n  │\n  v\nKnowledge manifests (knowledge.yaml)\n```\n\n**[Documentation →](https://cantara.github.io/kcp-harness/)**\n\n## Why\n\nEnterprises need agents that are *defensible* — auditable, reproducible, budget-controlled,\ntemporally pinned. Today's agents can't prove why they read what they read. The harness adds a\ncompliance layer without replacing the agent.\n\n| What you keep | What the harness adds |\n|---|---|\n| Your agent (Claude Code, Cursor, Copilot, ...) | Deterministic knowledge selection |\n| Your workflow (coding, reviewing, shipping) | Decision traces (14 gates per unit) |\n| Your tools (MCP servers, shell, browser) | Budget enforcement (ceiling, per-currency) |\n| | Temporal governance (drift detection) |\n| | Append-only audit log |\n| | Replay / cross-examination |\n| | Human-approval gates (named reviewer + policy citation) |\n| | Confidence gating (post-synthesis, route-to-human) |\n\n**You sell the compliance layer. The agents are pluggable.**\n\n## Install\n\n```bash\nnpm install -g kcp-harness\n```\n\nOr use without installing:\n\n```bash\nnpx kcp-harness --help\n```\n\n### Native executables\n\nPre-built binaries (no Node/Deno required) for Linux x64/arm64, macOS x64/arm64, and Windows x64\n— grab them from a [release](https://github.com/Cantara/kcp-harness/releases). To build one yourself:\n\n```bash\nnpm ci && npm run build\ndeno compile --allow-read --allow-env --allow-net --allow-run \\\n  --node-modules-dir=auto --output kcp-harness dist/cli.js\n```\n\n## Quick start\n\n### 1. Initialize\n\n```bash\nkcp-harness init          # creates harness.yaml\n```\n\n### 2. Generate agent integration\n\n```bash\nkcp-harness integrate claude-code    # or: pi, cursor, copilot, windsurf, cline, continue, crush, openclaw\n```\n\n### 3. Start coding\n\nYour agent now routes knowledge access through the harness. Every decision is logged.\n\n## Supported agents\n\n| Agent | Config | Integration |\n|---|---|---|\n| **Claude Code** | `.mcp.json` + PreToolUse hooks | `kcp-harness integrate claude-code` |\n| **Cursor** | `.cursor/mcp.json` + `.mdc` rules | `kcp-harness integrate cursor` |\n| **GitHub Copilot** | `.vscode/mcp.json` (uses `\"servers\"` key) | `kcp-harness integrate copilot` |\n| **Windsurf** | global config + `.windsurfrules` | `kcp-harness integrate windsurf` |\n| **Cline** | MCP settings + `.clinerules` | `kcp-harness integrate cline` |\n| **Continue** | `.continue/mcpServers/*.yaml` | `kcp-harness integrate continue` |\n| **Crush** | `crush.json` + PrepareStep | `kcp-harness integrate crush` |\n| **OpenClaw** | `openclaw.json` + plugin hooks | `kcp-harness integrate openclaw` |\n| **Pi** | `.pi/mcp.json` + project skills | `kcp-harness integrate pi` |\n\nEach agent has its own MCP config format, rules file, and quirks. The `integrate` command handles\nthem all — one governance layer, any agent.\n\n## How it works\n\nEvery tool call flows through a five-stage pipeline:\n\n```\n1. RECEIVE      MCP JSON-RPC request from agent\n2. CLASSIFY     Knowledge-navigation or pass-through?\n3. GOVERN       14-gate cascade (audience → temporal → budget → ...)\n4. EXECUTE      Call downstream tool / return content\n5. AUDIT        Log decision to append-only audit log\n```\n\n### Classifier\n\nThe classifier examines each tool call and determines whether it targets governed knowledge.\n`Read(\"docs/api.md\")` where `docs/` is governed? Route through the planner. `Read(\"package.json\")`\nwhere `package.json` isn't governed? Pass through. KCP tools (`kcp_plan`, `kcp_load`) are always\ngoverned.\n\n### Governor\n\nTwo automated modes, plus a human gate that outranks both:\n\n- **Plan-first (fast path)** — the agent calls `kcp_plan` first. The harness caches the approved\n  plan. Subsequent reads are checked against the cached plan — no re-planning.\n- **Auto-plan (fallback)** — the agent reads a governed path without planning. The harness runs\n  the planner automatically. Slower, but governance is enforced even for agents that don't know\n  about `kcp_plan`.\n- **Human approval** — calls matching a `governance.approvals` rule are held for a named\n  reviewer (`pending`), no matter what the automated paths would decide. Tickets survive\n  restarts and resolve via the `kcp-harness approvals` CLI (or any custom `ApprovalProvider`\n  channel). Resolutions require a named reviewer *and* a policy citation.\n\n### The 14-gate cascade\n\nEvery knowledge unit is evaluated through 14 deterministic gates, in order:\n\n```\naudience → not_for → temporal → deprecated → supersession → relevance →\nskill_eligibility → attestation → payment → access → strict → max_units →\nmoney_budget → context_budget\n```\n\nA unit must pass **all** gates. The gate that blocks it is recorded in the decision trace. Same\ninputs → same plan. No model involved.\n\nFor the `skill_eligibility` gate's subject matter — governed `kind: skill` units — the\nauthoring conventions, linter, and conformance vectors live in\n[Cantara/kcp-skill](https://github.com/Cantara/kcp-skill).\n\n## MCP tools\n\nOnce connected, agents can use these governance tools:\n\n| Tool | Description |\n|---|---|\n| `kcp_plan` | Deterministic load plan — which units, in what order, which skipped and why |\n| `kcp_load` | Plan + load eligible unit content |\n| `kcp_trace` | Full 14-gate decision trace |\n| `kcp_validate` | Lint a `knowledge.yaml` |\n| `harness_status` | Current governance state |\n| `harness_session` | Approved plans + known units for this session |\n| `harness_budget` | Itemized spend tracking |\n| `harness_temporal_check` | Plan drift detection |\n| `harness_approvals` | Human-approval tickets (pending / approved / dismissed / expired) |\n| `harness_assess` | Confidence-gate a synthesized answer before acting on it |\n\n## Compliance artifacts\n\n### Audit log\n\nAppend-only JSONL. Every decision — governed or pass-through — is logged with sequence number,\ntimestamp, tool, targets, and governance decision:\n\n```bash\ncat .kcp-harness/audit.jsonl | jq 'select(.governed == true)'\n```\n\n### Budget ledger\n\nAppend-only itemized spend tracking. Per-currency running totals. Ceiling enforcement — a load\nthat would exceed the budget is rejected atomically (no partial loads).\n\n### Temporal governance\n\nPlans are registered with a temporal watcher. On subsequent calls, the watcher re-evaluates\nagainst the current time. If units have drifted (expired, newly valid), the harness emits a drift\nevent. Long-running sessions stay honest.\n\n### Approval tickets\n\nCalls matching an approval rule open a durable ticket\n(`pending_review → approved | dismissed | expired`). The ticket store survives restarts —\nsessions are ephemeral, human review is not. Every resolution records *who* approved,\n*when*, and *which policy* it satisfies — evidence generated at approval time, never\nreconstructed from logs.\n\n### Confidence verdicts\n\n`harness_assess` runs [kcp-agent](https://github.com/Cantara/kcp-agent)'s post-synthesis\n`assess()` over a synthesized answer before it may be acted on. The planner gates *loading*,\ngrounding gates *asserting*, this gates *acting*. Below-threshold verdicts on routed configs\nopen an approval ticket with the full verdict embedded as evidence.\n\n## Configuration\n\n```yaml\n# harness.yaml\nversion: \"1.0\"\n\ngovernance:\n  domains:\n    - manifest: \"./knowledge.yaml\"\n      paths: [\"docs/\", \"src/\"]\n\n  policy:\n    fail_closed: true\n    audit_all: true\n    max_units: 5\n    budget:\n      amount: 1.00\n      currency: USDC\n\n  confidence:                  # optional post-synthesis gate (harness_assess)\n    threshold: 0.7\n    severity: critical\n    route_to_role: account-owner\n\n  approvals:                   # optional human-approval gates\n    provider: file\n    rules:\n      - match: { tools: [Write, Edit], paths: [records/] }\n        required_role: account-owner\n        expires_after: 72h\n        policy_ref: POL-7.2\n\naudit:\n  path: \".kcp-harness/audit.jsonl\"\n```\n\n## CLI\n\n```\nkcp-harness serve  [--config harness.yaml]   Start the MCP proxy\nkcp-harness init                             Create a harness.yaml template\nkcp-harness check  [--config harness.yaml]   Validate configuration\nkcp-harness integrate <agent> [options]       Generate agent integration files\nkcp-harness integrate --list                  List supported agents\nkcp-harness export   [options]               Export compliance evidence (SOC 2 / ISO 27001)\nkcp-harness dashboard [options]              Launch the live compliance dashboard\nkcp-harness approvals list [--state s]        List human-approval tickets\nkcp-harness approvals approve <id> --reviewer <name> --policy-ref <ref>\nkcp-harness approvals dismiss <id> --reviewer <name> --policy-ref <ref>\n```\n\n## Library\n\n```ts\nimport { classify, govern, BudgetLedger, TemporalWatch } from \"kcp-harness\";\nimport { generate, listAgents } from \"kcp-harness\";\n\n// Classify a tool call\nconst result = classify(\"Read\", { file_path: \"docs/api.md\" }, governedDomains);\n\n// Generate integration files\nconst output = generate(\"claude-code\", { manifest: \"./knowledge.yaml\", paths: [\"docs/\"] });\n```\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────┐\n│  Layer 3: Integration Packages               │\n│  Agent-specific configs + rules files        │\n│  (claude-code, cursor, copilot, ...)         │\n├──────────────────────────────────────────────┤\n│  Layer 2: KCP Compliance Harness             │  ← THIS\n│  MCP proxy — deterministic governance        │\n├──────────────────────────────────────────────┤\n│  Layer 1: kcp-agent (planner core)           │\n│  14-gate cascade, decision traces            │\n└──────────────────────────────────────────────┘\n```\n\n**Forking agents puts you in competition. A harness puts you in composition.**\n\n## Tests\n\n```bash\nnpm test     # 314 tests across 20 test files\n```\n\nCovers the classifier, governor (incl. approval precedence), approval state machine + providers,\nconfidence-gate wiring, proxy, audit, budget ledger, temporal watch, evidence export, dashboard,\nand all agent integrations.\n\n## License\n\nApache-2.0 · By [eXOReaction AS](https://www.exoreaction.com), hosted under\n[Cantara](https://github.com/Cantara).\n",
  "bytes": 11891,
  "sha": "f0d375bf56a041769b15554d701152edf04f586151dcc1484a8c85c1066d7685",
  "repo_slug": "cantara/kcp-harness",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_no_cantara_kcp_harness_8b9d7836/readme"
}