@mcp-index/sdk

Pre-flight MCP tool-contract drift interceptor. One line — wrap() an MCP client session and the gate HOLDs a tool call before your agent acts the moment the tool's contract silently changes from what you pinned. In-path, on your host; no credentials, no egress.

Install

npm i @mcp-index/sdk

Peer dependency: @modelcontextprotocol/sdk >= 1.0.0.

Use

import { wrap } from '@mcp-index/sdk';

// wrap an already-connected MCP client session
const guarded = wrap(session);   // pins each tool's contract on first use (TOFU)

// use `guarded` exactly like `session`; a drifted contract is HELD before the call
// fires. A PreflightHold surfaces (Guard/Strict) so you can route the agent to
// Review / Re-pin / Validate.

What it does

• Pins each MCP tool's contract trust-on-first-use (TOFU), persisted across restarts.
• Runs a deterministic contract-diff (the ChangeKind taxonomy: added-required-param, constraint-narrowed, annotation-flip-to-destructive, output-schema-changed, type/enum/removed, …) plus an injection/exfil marker scan over input and output schema.
• HOLDs the call with the ⬡ banner when the contract drifted; PROCEEDs silently on a benign change (no false alarm).
• Postures: Monitor (notify + proceed) / Guard (default; hold dangerous) / Strict (hold any drift).
• Grades each call's blast radius (Tier-0a action classification) on the verdict: action type (read / write / delete / send / …), reversibility, egress, and a static autonomy ceiling, computed locally from the live contract. Advisory — it rides alongside the decision and never moves HOLD/PROCEED. On by default; opt out with MCPINDEX_ACTION_CLASSIFICATION_ENABLED=0.

What it is NOT

The verdict is a contract-diff, not a safety oracle — it tells you the contract changed versus your pin, not that the new contract is safe. It does not "block attacks" or "guarantee safe." You decide what a HOLD means for your agent.

Drift telemetry (opt-in, OFF by default)

The SDK can report that a tool's contract drifted — so mcpindex can track drift on servers it can't crawl itself (private / auth-gated). It is off by default and sends nothing unless you turn it on:

export MCPINDEX_DRIFT_TELEMETRY=detection   # off (default) | detection | contribute

When enabled, each tool you pin and each contract drift sends one one-way signal:

• What it sends: salted (HMAC) fingerprints of the server/tool id, the contract hashes, the change type (the fixed ChangeKind vocabulary), a safety flag, an hour-rounded timestamp, a random install id (a token that links one machine's signals so distinct installs can be counted — not derived from you), and a client SDK tag (py or ts).
• What it NEVER sends: tool schemas, arguments, descriptions, URLs, server/tool names, or any of your data. The payload has no free-text field by construction, and the ingest rejects anything that isn't the closed shape.
• Fail-open: telemetry never blocks, slows, or changes a tool call. Losing a signal is always preferred to perturbing the gate.

detection enables the closed signal above; contribute is reserved for a future, separately opt-in richer tier (it behaves identically today). The full notice is exported as DRIFT_TELEMETRY_NOTICE. Unset the variable any time to stop.

License

PolyForm Noncommercial 1.0.0 — © Bhartis LLC. Free for noncommercial use; commercial use requires a separate license. See LICENSE and https://mcpindex.ai.