mcpindex-gate

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

Renamed: previously published as mcpindex-preflight. That name remains a deprecated alias that depends on this package. New installs should use mcpindex-gate.

What it does

mcpindex-gate 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_gate 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-gate

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

Call receipts (on by default)

After each gated call the gate emits a compact, credential-blind receipt: a hash of the tool identity, the gate verdict, and the action class (read / write / execute). It never includes tool arguments, result content, server names, or URLs. Receipts are linked by a random per-install token stored in ~/.mcpindex/install_id -- pseudonymous, not derived from you or your machine. Keyless installs have no account link; if you sign in on mcpindex.ai and configure an api_key, receipts from that install are associated with your key.

From gate v0.9.0, the first run on a machine prints a one-line disclosure of exactly this behavior to stderr and sends nothing that session -- emission starts on run 2, so no receipt ever leaves before the notice and the opt-out were visible. Earlier versions emit without the runtime notice, per this README.

After 10 gated calls the ambient notifier fires a one-line message on stderr:

mcpindex - 10 tool calls noted - mcpindex.ai/receipts?id=<your-install-id>

That link shows your per-install call log. To suppress receipt egress entirely:

export MCPINDEX_RECEIPT_INGEST_ENABLED=0

Weekly summary line (local, zero egress)

At most once per ISO week the gate prints one line summarizing what it did last week -- calls gated, tools and servers watched, drift seen, holds issued:

mcpindex · week 2026-W29: 240 call(s) gated across 12 tool(s) / 3 server(s), 0 drift - your baseline is holding · mcpindex.ai/receipts?id=<your-install-id>

The counters live only in ~/.mcpindex/weekly_stats.json; nothing about this line is sent anywhere. To silence it:

export MCPINDEX_WEEKLY_SUMMARY=0

Drift telemetry (opt-in, OFF by default)

The gate 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. See https://mcpindex.ai/privacy and https://mcpindex.ai/docs.