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.

What status tells you (0.11.0)

mcpindex-config-wire status reports enforcement, not merely that our proxy is in the launch line:

• [x] requires that nothing is un-wired, unreadable, or non-enforcing. Before 0.11.0 the mark appeared as soon as one server was wired and could never turn off.
• [!] means real coverage gaps, and names them by host.
• notify-only counts servers launched with --posture monitor, which never blocks. It is a legitimate choice, but it is not protection, so it is never counted as such.
• will not start (bad gate command) (0.13.2) counts servers whose launch line the proxy rejects outright, so the server never starts and you lose the server as well as the protection. Nothing we wire produces this; it comes from a hand edit to the config. Fix it by un-wiring that host and wiring it again, which rebuilds the launch line from scratch.
• keeps its baseline outside mcpindex (0.13.4) counts servers whose config entry points --pin-store at a file outside ~/.mcpindex/pins/. That server may well still hold, but against a baseline nothing else here can read, and one whose deletion the gate can no longer detect, because the record of what was pinned lives beside the store and moves with it. Wiring never writes that flag, so an entry only carries one because something edited your config. It is not counted as protection, and mcpindex-config-wire wire --repin moves the baseline back. In 0.13.3 and earlier these servers were counted as fully enforcing.
• hosts scanned: N is stated because project-scoped configs (a repo's own .mcp.json, .cursor/mcp.json, .vscode/mcp.json, …) are not scanned yet. The total is a floor, not a census.

If the gate HOLDs on your baseline

A HOLD whose reason names the baseline rather than a tool contract means the pin store for that server was present but unreadable, or was deleted after having been pinned. The gate refuses to proceed rather than silently re-learning the contract from whatever the server is serving right now. This holds in every posture and regardless of fail_open, because neither is consent to trust a baseline that may have been rewritten.

To recover deliberately, delete that server's file under ~/.mcpindex/pins/ and restart the host. That re-pins from the current contract — a fresh trust-on-first-use — so do it only when you know why the store was unreadable (an interrupted write, a restored backup, a machine migration).

Honest limit: this is tamper-evident, never tamper-proof. A process running as you that replaces the store with a well-formed one carrying its own baseline is still trusted. No same-user control prevents that: any secret the gate can read, a process running as you can read too.

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

Project config scanning (local read, ON by default)

mcpindex-config-wire counts the MCP servers you actually run. Many of them are not in your global host config: they are declared per-project, in a repo's own .mcp.json, .cursor/mcp.json, .vscode/mcp.json, .gemini/settings.json or .zed/settings.json. A gate that cannot see them reports a coverage number that is a floor, not a census — on one real machine it said 25 servers while 35 were loaded.

To find those repos it reads the project list Claude Code already keeps in ~/.claude.json. This widens what the tool reads from about ten fixed paths in your home directory to every repository you have opened in Claude Code. It is a local, read-only scan; nothing about it is sent anywhere, and it obeys the same zero-egress default as the rest of the gate.

Detect-only. Project configs are counted and reported, never wired. They are version-controlled and shared, so wiring one would commit a change pointing your teammates at a gate they have not installed — and every server would fail for them. Wiring one is possible, but it takes an explicit --config <path>, after you have read the file.

To turn the scan off, or to add a repo Claude Code does not know about:

mcpindex-config-wire status --no-project-scan      # or: export MCPINDEX_PROJECT_SCAN=off
mcpindex-config-wire status --project ~/work/my-repo   # repeatable; for Cursor / Gemini / Zed users

With the scan off, the server count is a floor and status says so rather than printing a smaller number without the caveat.

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) | lookup | detection | contribute

• off — the default. Sends nothing, asks nothing.
• lookup — read-only. Asks whether a tool's contract has already drifted, so the gate can warn you on the first call. Sends a salted fingerprint per tool and reports none of your own catches back.
• detection — lookup, plus each tool you pin and each contract drift sends one one-way signal.
• contribute — reserved for a future richer tier; behaves identically to detection today.

Each tier is a superset of the one before it. See https://mcpindex.ai/privacy and https://mcpindex.ai/docs for exactly which fields leave the machine.

Where the setting lives (v0.13.0+)

For servers you wired through the gate, set it with the wiring command rather than in your shell — the wired entry is what the proxy actually launches with:

mcpindex-config-wire --drift-telemetry lookup    # or detection / contribute / off

Your choice is recorded in ~/.mcpindex/consent.json and re-applied on every later re-wire, including on servers already wired.

0.13.2 and earlier: this did not work. Wiring skipped servers it had already wired, so on an already-configured machine --drift-telemetry off reported success and cleared nothing. On those versions you must pass --repin. Fixed in 0.13.3.

Before v0.13.0 the setting lived only in the host config entry, where the gate could not tell your own opt-in from one something else had written — so wiring cleared it, and a scripted re-wire (--yes, an editor auto-wire) silently turned your setting off.

The record holds the mode, a label for how it was set, when, and — when the setting was carried over from an existing wired config — the host label it came from. No paths, no server or tool names. (In 0.13.1 and 0.13.2 that field held a file path from your machine instead.) It is local, is never sent anywhere, and is not a security boundary: anything running as your user can edit it, exactly as it can edit your host config. What it buys is that your setting survives, and that a wired entry which disagrees with it gets reported instead of silently obeyed.

To turn everything off and clear it from every wired entry:

mcpindex-config-wire wire --drift-telemetry off