⚒ MCP Tool Cards Kinetic Gain Protocol Suite
v0.1 draft · core spec

Per-tool disclosure for
MCP servers.

MCP Tool Cards is an open JSON spec for declarative per-tool disclosure on Model Context Protocol servers: input schema, safety profile (side-effect class, PII / secrets exposure, approval requirement), tested-LLM matrix with pass rates, performance metrics (p50 / p99 latency), and audit log location.

Read the spec Try the visualizer
  • Detect via tool_card_version
  • Well-known: /.well-known/mcp-tools/<tool_name>.json
  • Cross-referenced from AI Incident Cards on failure

Why per-tool disclosure for MCP?

MCP makes it trivial for an agent to invoke a tool. That same ease is the security problem: an agent talking to an unfamiliar MCP server has no machine-readable way to ask 'is this tool read-only? what PII does it expose? has it been tested with my model?' MCP Tool Cards fills that gap.

Tool identity

server_id, name, semver version, mcp_server_uri, plain-text description. The minimum identifier.

Schema

input_schema_uri or input_schema_inline (JSON Schema). The contract the tool expects.

Safety

side_effect_class (read / mutating / external / destructive), reversible, rate_limited, pii_exposure, secrets_exposure, human_approval_required.

Refusal modes

refusal_modes[] — declared conditions where the tool will refuse (cross-tenant access, rate-limit exceeded, etc.). Procurement reviewers grep this.

Tested-with matrix

Array of { llm, provider, test_suite_uri, pass_rate, tested_at }. Vendors can declare 'this tool was tested with Claude Opus 4-7 at 98% pass rate on suite X'.

Performance + audit

p50_latency_ms / p99_latency_ms / measurement_window, plus audit.log_uri and retention_days. The minimum operational disclosure.

The required sections

  1. tool_card_version — must be "0.1"
  2. tool — server_id, name, version, mcp_server_uri, description
  3. schema — input_schema_inline or input_schema_uri
  4. safety — side-effect class, reversible, rate-limited, PII / secrets exposure, approval
  5. tested_with (optional) — LLM matrix with pass rates
  6. performance (optional) — p50 / p99 latency, measurement window
  7. audit (optional) — log URI, retention days

A canonical example

{
  "tool_card_version": "0.1",
  "tool": {
    "server_id": "kg-billing-mcp",
    "name": "billing-lookup",
    "version": "1.4.0",
    "mcp_server_uri": "https://billing.kineticgain.com/mcp",
    "description": "Looks up a customer's current invoice, plan tier, and usage-to-date. Read-only."
  },
  "schema": {
    "input_schema_inline": {
      "type": "object",
      "required": ["customer_id"],
      "properties": { "customer_id": { "type": "string" } }
    }
  },
  "safety": {
    "side_effect_class": "read",
    "external_systems": ["stripe-api"],
    "reversible": true,
    "rate_limited": true,
    "pii_exposure": "low",
    "secrets_exposure": "none",
    "human_approval_required": false,
    "refusal_modes": ["cross_tenant_access", "rate_limit_exceeded"]
  },
  "tested_with": [
    { "llm": "claude-opus-4-7", "provider": "Anthropic",
      "test_suite_uri": "https://eval.kineticgain.com/suites/mcp-billing-v2",
      "pass_rate": 0.98, "tested_at": "2026-05-08T10:00:00Z" }
  ],
  "performance": { "p50_latency_ms": 120, "p99_latency_ms": 580, "measurement_window": "last_7d" },
  "audit": { "log_uri": "https://audit.kineticgain.com/mcp/billing-lookup", "retention_days": 365 }
}

Tooling around the spec

Specification

mcp-tool-card-spec

Normative spec, JSON Schema 2020-12, canonical examples. AGPL-3.0 for spec text; implementations unrestricted.

View repo →
Visualizer

kinetic-gain-visualizer

Unified visualizer for all 10 specs. Auto-detects via tool_card_version and renders a procurement-grade view.

Open visualizer →
MCP server

mcp-kinetic-gain

34 tools across 8 specs. Drops into Claude Desktop / Cursor / any MCP-compatible client via stdio with one config entry.

View on GitHub →

About the Kinetic Gain Protocol Suite

MCP Tool Cards is one of ten open JSON specifications in the Kinetic Gain Protocol Suite. Five core specs plus the EdTech trio, the HealthTech extension, and the cross-cutting Incident Card. Front door: suite.kineticgain.com.

Executive tools on kineticgain.com

The apex domain hosts four browser-only tool surfaces buyers and operators reach for alongside the Suite specs: /calculators/ — six math-rubric decision calculators (AI build-vs-buy, cloud replatform ROI, compliance cost of delay, security breach exposure, AI use-case prioritizer, vendor renewal decision). /trust/ — the eight-tool Trust Pack (AI System Card Builder, Evidence Locker, Shadow AI Discovery, AI Vendor Intake, AI Incident Tabletop Kit, Executive Risk Register, Subprocessor Disclosure Template, Vendor AI Disclosure Review). /kill-list/ — the eight-category complexity tax audit. /policies/ — the 10-vertical readiness spec aggregator that points back at the specs documented here. Static pages, browser-only, no login, no telemetry.