correctover-ccs-mcp

Correctover CCS MCP Server — local-first MCP/Agent security tooling, exposed as MCP tools for Claude Desktop, Cursor, Cline, Windsurf, and any MCP client.

Zero network egress. Zero third-party dependencies. Data never leaves your machine.

---

Why this exists

Every verification tool in this space gives you the same two-word answer: PASS or FAIL.

That is not enough when you actually have to resolve an incident. When a signed agent decision record has been altered, you do not need to know that something changed — you need to know which field, on which layer, changed from what to what.

This server exposes four tools, one of which does exactly that.

Tool	What it does	Who else does it
ccs_locate_tampering	Field-level tamper localization — returns RFC 6901 JSON-Pointer paths, before/after values, and severity grading	❌ Nobody (see below)
ccs_verify_receipt	Ed25519 signature + RFC 8785 JCS + SHA-256 + schema verification	✅ Many
ccs_audit_batch	Batch audit up to 200 receipts, pass rate, tamper index list, optional hash-chain check	⚠️ Few
ccs_checkup_mcp_config	14-rule static security checkup on MCP/Agent configs	⚠️ Some

The differentiator, concretely

Given an original receipt and a suspect copy, ccs_locate_tampering returns this — not a boolean:

  critical  path=/checks/security/detail   (dotted: checks.security.detail)
  critical  path=/checks/security/status   (dotted: checks.security.status)
  high      path=/reason                   (dotted: reason)
  critical  path=/verdict                  (dotted: verdict)

Sigstore, C2PA, and comparable tools return only signatureValid: false. That tells you the artifact is bad. It does not tell you what to fix, or what to argue in a dispute.

---

Install

pip install correctover-ccs-mcp

Or from source:

git clone https://github.com/DSHCorrectover/ccs-conformance-vectors
cd ccs-conformance-vectors/ccs-mcp-server/correctover-ccs-mcp
pip install -e .

Configure your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "correctover-ccs": {
      "command": "correctover-ccs-mcp"
    }
  }
}

Cursor / Cline / Windsurf use the same mcpServers shape. If you prefer to run it without installing:

{
  "mcpServers": {
    "correctover-ccs": {
      "command": "python",
      "args": ["/absolute/path/to/correctover_ccs_mcp/server.py"]
    }
  }
}

Providing public keys

CCS receipts carry public_key_id, not an inline public key — a self-declared key is not a trust root. Supply the key in whichever way fits your setup:

Method	How
Tool argument	public_key_pem parameter on ccs_verify_receipt / ccs_audit_batch
Environment variable	CCS_PUBLIC_KEY — the PEM text directly
Key directory	CCS_PUBKEY_DIR — looks up <public_key_id>.pem

If no key resolves, verification fails closed with a message telling you the public_key_id to fetch. It never assumes.

---

Usage examples

Localize tampering

"Compare original.json and suspect-receipt.json and tell me exactly what was changed."

{
  "name": "ccs_locate_tampering",
  "arguments": {
    "original": { "...": "..." },
    "suspect":  { "...": "..." }
  }
}

Audit a batch with hash-chain checking

{
  "name": "ccs_audit_batch",
  "arguments": {
    "batch": { "receipts": [ "...", "..." ] },
    "check_chain": true
  }
}

Returns total / valid / invalid / pass_rate / tampered_indexes / fail_reason_distribution, plus chain_check when requested.

Check up an MCP config before you run it

{
  "name": "ccs_checkup_mcp_config",
  "arguments": { "config": { "mcpServers": { "...": {} } } }
}

Returns risk_level plus per-finding rule_id, severity (CRIT/HIGH/MED/LOW), evidence, and remediation.

---

Verify this package yourself

Nothing here asks for your trust. Three commands:

# 1. Offline self-test — runs all four tools against bundled examples
python -m correctover_ccs_mcp.server --selftest

# 2. Full test suite (42 tests, incl. real MCP subprocess handshake)
python -m pytest tests/ -v

# 3. Inspect the tool contracts without connecting a client
python -m correctover_ccs_mcp.server --list-tools

All four tools are exercised in both directions — valid inputs must pass, and tampered, wrong-key, and missing-key inputs must be rejected, not silently allowed.

---

Tool reference

ccs_verify_receipt

Required	receipt (object)
Optional	public_key_pem (string)
Returns	valid, verdict, public_key_source, full result.evidence (JCS byte count, SHA-256 digest, content-hash match, Ed25519 status, schema check)

ccs_audit_batch

Required	batch (array, or {"receipts": [...]})
Optional	check_chain (bool, default false), public_key_pem (string)
Limit	200 receipts per call — hard cap, oversized batches are rejected, never truncated
Returns	total, valid, invalid, pass_rate, tampered_indexes, fail_reason_distribution, per-receipt results, plus chain_check when requested

ccs_checkup_mcp_config

Required	config (object)
Accepts	{"mcpServers": {...}}, {"config": {"mcpServers": {...}}}, or a bare {name: {...}} map
Returns	risk_level, summary (per-severity counts), findings[] with rule_id / severity / evidence / remediation

Covers hardcoded credentials, arbitrary command execution, writable filesystem mounts, SSRF surface, cleartext HTTP, unpinned package runners, and more.

ccs_locate_tampering

Required	original (object), suspect (object)
Returns	tampered (bool), changes[] with path (RFC 6901 JSON-Pointer), path_dotted (original form), change type, original / suspect values, severity, remediation

---

Design decisions worth knowing

Fail-closed, not fail-open. Missing public key, unparseable config, oversized batch, malformed diff input — every one of these returns an explicit error. There is no path where a malformed input produces an affirmative verification result.

No network imports. The server source imports no HTTP or socket libraries. This is enforced by a test, not just a promise: test_no_network_imports fails the build if one is introduced.

Evidence, not verdicts. ccs_verify_receipt returns the JCS canonical byte count, the recomputed SHA-256, the content-hash comparison result, and the raw Ed25519 status. You can audit our reasoning rather than accept our conclusion.

JSON-Pointer at the boundary. The engine internally uses dotted paths; the MCP boundary normalizes to RFC 6901 and keeps the dotted form in path_dotted. Converted, not replaced.

No third-party dependencies. Ed25519, JCS canonicalization, and SHA-256 are implemented against the Python standard library. pip install pulls nothing else.

---

What this tool does NOT do

• It does not establish trust in a public key. It verifies that a signature matches a key you supplied. Where that key came from is your problem, and rightly so.
• It does not prove business impact. A receipt can be cryptographically pristine and describe something that should never have happened. Signature validity and correctness of the underlying action are different questions.
• It does not replace human audit. The 14-rule checkup is a fast static triage over config documents. Runtime behavior, tool implementation code, permission boundaries, and data flows require manual review.
• It does not provide third-party dated attestation. That is a separate, optional service. Everything here runs locally and produces a local verdict.

---

License

Elastic License 2.0 — see LICENSE.

Open standard, proprietary engine. You may use, copy, distribute, and modify this software. You may not provide it to third parties as a hosted or managed service.

---

Support

• Documentation — https://correctover.com/docs
• Issues — https://correctover.com/support

---

Correctover — AI Reliability