mcp-kinetic-gain

One MCP server, all twelve Kinetic Gain Protocol Suite specs + the v0.1.0 implementation tooling + the DefenseTech 6-pack semantics (8 tools). Drop into Claude Desktop, Cursor, or any MCP-compatible client with a single config entry. The agent gains 75 tools (47 spec + 16 implementation-preview + 8 DefenseTech + 4 AI Claims Decision Card, v0.9.0): AEO Protocol, Prompt Provenance, Agent Cards, AI Evidence Format, MCP Tool Cards, AI Tutor Cards, Student AI Disclosure, Classroom AI AUP, Clinical AI Disclosure, AI Incident Card, AI Procurement Decision Card, AI Claims Decision Card - plus hash attestation (ed25519), audit-stream event composition + chain verification (offline AND live against a running audit-stream-py via AUDIT_STREAM_URL), cross-spec drift detection, Decision Intelligence preview, and the DefenseTech vault resolver + invariant checkers. New in v0.9.0: the AI Claims Decision Card (InsurTech, claims_card_version) - claims_card_validate, claims_card_inspect, claims_card_sign, claims_card_chain.

This is the agent-facing companion to kinetic-gain-visualizer: the visualizer renders the specs for humans, while this server exposes validation and workflow tools for agents. The optional audit_event_emit tool sends an event to a configured audit-stream service.

Tools

Specs with a well-known URL convention (AEO, Agent Cards, Tool Cards) get fetch tools. Specs without one (Prompt Provenance, AI Evidence - these usually travel inline with answers or in repos, not at fixed paths) get parse tools that take a document_json string.

Network and data boundaries

URL fetch tools make outbound HTTP(S) requests to user-supplied origins. The server rejects local and nonpublic destinations, rechecks redirects, and limits JSON responses to 1 MB. The optional live audit tools require both AUDIT_STREAM_URL and AUDIT_STREAM_TOKEN in the MCP server's environment. The token must match the audit-stream service's bearer token and have at least 32 visible ASCII characters. Use HTTPS for a remote service; HTTP is accepted only for loopback development. Missing or invalid configuration returns an error without sending a request. audit_event_emit sends kind, caller-asserted source, and payload to the configured service and validates its event receipt. The receipt does not prove durable storage or event completeness. Its shared token authenticates this MCP process, not the source label or tenant. Approve the write before calling it; omit secrets and personal data unless the service is approved for them. Hash-chain verification checks continuity only; it does not prove audit completeness.

Schema validation checks the document shape and selected rules. A passing result is not proof of FERPA, COPPA, HIPAA, FDA, EU AI Act, CMMC, export-control status, or other legal compliance. attestation_verify checks a signature against the public key supplied by the caller; it does not establish the key owner's identity. aup_check_compliance evaluates eight disclosed fields only; it does not check policy scope, tool/vendor requirements, parent consent, or Tutor Cards. A true allowed value is not an authorization grant. DefenseTech tools calculate from supplied data; they do not classify materials or verify a person's status or license. Positive Decision Cards require the live policy engine's identity, scope, action, expiry, and trusted-attestation checks before an enforceable bundle can be created.

The DefenseTech 72-hour clock uses the time an incident was discovered, not when it occurred or when an audit event was created. Supply discovered_at and filed_at with time zones; see DFARS 252.204-7012. A report's actual submission and contract applicability require external evidence.

Start with a task

• Review a card: pass a parsed document to claims_card_validate, then use claims_card_inspect to summarize its declared decision. Investigate any validation failure before relying on the summary.
• Compare drafts: call suite_doc_drift with two versions of the same Suite document to see structural changes before publication.
• Check a signature: call attestation_verify with a public key obtained through a trusted channel; separately confirm that the key belongs to the claimed signer.
• Record an event: prepare the payload with audit_event_compose, review it for sensitive data, then call audit_event_emit only when the configured audit-stream service and write are approved.

Install

The commands below install the version currently published on npm. To run this source checkout instead, use npm ci, npm run build, then node dist/server.js. Check npm view mcp-kinetic-gain version before relying on a particular source change.

npm install -g mcp-kinetic-gain

Or run without installing via npx:

npx mcp-kinetic-gain

For a controlled deployment, pin a reviewed package version in the client config (mcp-kinetic-gain@<version>) and upgrade deliberately.

Claude Desktop config

Add to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "kinetic-gain": {
      "command": "npx",
      "args": ["-y", "mcp-kinetic-gain"]
    }
  }
}

Restart Claude. All 75 tools appear in the tools panel. Try:

"Use aeo_inspect on https://mizcausevic-dev.github.io to summarize the entity declaration, then use ai_evidence_verify_hash to check the content_hash of an evidence object against my candidate text."

CLI mode (v0.5.1+)

The same binary doubles as a Suite JSON validator outside any MCP host. Useful in CI, pre-commit hooks, or local sanity-checks.

# Validate a single document
npx mcp-kinetic-gain validate path/to/ai-entity.json

# Validate a tree of well-known files
npx mcp-kinetic-gain validate ".well-known/**/*.json"

# Multiple paths or globs
npx mcp-kinetic-gain validate cards/clinical-*.json cards/incident-*.json

# Other commands
npx mcp-kinetic-gain --version
npx mcp-kinetic-gain --help

The CLI auto-detects which Suite spec each file belongs to via its top-level version field (aeo_version, clinical_ai_card_version, aup_version, etc.) and validates it against the same zod schemas the MCP tools use. Output is GitHub-Actions-aware: when GITHUB_ACTIONS=true, failures emit ::error:: workflow commands so they surface as PR annotations.

Exit codes:

Running mcp-kinetic-gain with no arguments still launches the stdio MCP server - existing Claude Desktop / Cursor configs are unaffected.

Why one server instead of five?

• One Claude Desktop config entry instead of five
• Cross-spec workflows are atomic - an agent can agent_card_tool_disclosure to find a Tool Card URI, then call tool_card_inspect on that URI in the same conversation, all through one server
• Shared schemas + utilities keep the implementation cohesive
• Deprecation path - if mcp-aeo-server (the AEO-only predecessor) gets retired, the AEO tools live on here with the same names and contracts

Architecture

src/
├── server.ts              # MCP entrypoint and handler dispatch
├── cli.ts                 # JSON validation CLI
├── tools.ts               # 75 tool descriptors (JSON Schema inputs)
├── schemas.ts             # Zod schemas for the 12 specs
├── common.ts              # guarded fetch and canonical hashes
└── handlers/              # one module per spec plus cross-spec and live tools

Each handler module is independent and could be split into a separate package if needed.

Hash canonicalization

ai_evidence_verify_hash follows the AI Evidence Format spec's canonical SHA-256 rules:

1. Read content as UTF-8
2. Normalize line endings to \n
3. Strip a single trailing newline
4. SHA-256, lowercase hex, prefixed sha256:

If your candidate_text produces an unexpected mismatch, check CRLF vs LF and trailing newlines first.

Tests

Run the unit and local HTTP tests without an external service:

npm install
npm run typecheck
npm test
npm run build

License

This server: AGPL-3.0. If a modified version serves users over a network, the AGPL requires an offer of Corresponding Source to those users under its terms. See the GNU AGPL FAQ and LICENSE.

The specs themselves: MIT. Maximally permissive. Anyone may implement, validate against, or extend any Kinetic Gain Protocol Suite specification. The dual-license split is deliberate: the protocol stays open, the reference server is copyleft.

Kinetic Gain Protocol Suite

75 tools total across the twelve specs below plus cross-cutting ops (hash attestation, audit-stream events, cross-spec drift) and the DefenseTech tooling. See the Tools catalog above for the full per-tool list (47 spec + 16 implementation-preview + 8 DefenseTech + 4 AI Claims Decision Card).

Suite hub: suite.kineticgain.com Companion visualizer: kinetic-gain-visualizer Red-team bench: prompt-injection-bench Reference library: kgp-verify (npm kinetic-gain-protocol, zero-dep MIT hash/sign/verify for KGP)

Connect: LinkedIn · Kinetic Gain · Medium · Skills