mcpindex-preflight 0.5.0

mcpindex pre-flight drift gate — the in-path, zero-egress-by-default trust-to-act client for MCP tool calls (open core).

mcpindex-preflight

The in-path drift gate for agent tool calls — the open-core client of mcpindex.ai. It runs on your host with zero egress and checks every MCP tool definition against your own pinned baseline before a call goes out.

What it does

mcpindex-preflight produces a drift decision — PROCEED / HOLD / INCONCLUSIVE — by diffing the live tool contract against the contract you pinned. If a server silently changes a tool's schema, description, or surface, the gate can HOLD the call and surface why.

from mcpindex_preflight import wrap, PreflightPin, PreflightHold

session = wrap(your_mcp_client_session, pin=PreflightPin(path="~/.mcpindex/pin.json"))

try:
    result = await session.call_tool("transfer_funds", {...})
except PreflightHold as hold:
    # The tool contract drifted from your pin — inspect `hold` and decide.
    print(hold)

wrap() accepts any duck-typed client session; this package does not depend on the mcp SDK.

What it is — and is not

• It is a contract diff, not a safety oracle. It detects that a tool changed; it does not judge whether the change is malicious.
• A HOLD means "this drifted from your pin — look before you act." It is advisory. It does not block attacks, guarantee safety, or make a server tamper-proof.
• It mints no clearance verdict. The offline client can detect drift and HOLD; it can never publish a "SAFE" verdict.

Install

uv tool install mcpindex-preflight

One-click host wiring + a resident auto-onboard watcher are available via the installer at https://mcpindex.ai/install.sh.

Drift telemetry (opt-in, OFF by default)

preflight 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 (a fixed vocabulary), a safety flag, an hour-rounded timestamp, and a random install id (links one machine's signals so distinct installs can be counted — not derived from you).
• 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.

detection enables the closed signal; contribute is reserved for a future, separately opt-in richer tier (identical today). Unset the variable any time to stop.

License

MIT.