Metadata-Version: 2.5
Name: mcpindex-gate
Version: 0.14.0
Summary: mcpindex gate - the in-path, zero-egress-by-default trust-to-act client for MCP tool calls, from mcpindex.ai (the MCP server index).
Project-URL: Homepage, https://mcpindex.ai
Author: mcpindex.ai
License-Expression: MIT
Keywords: agent,drift,gate,mcp,security,tools,trust
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: opentimestamps>=0.4.5
Requires-Dist: pydantic<3,>=2.12
Description-Content-Type: text/markdown

# mcpindex-gate

The in-path **drift gate** for agent tool calls — the open-core client of
[mcpindex.ai](https://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.

```python
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

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
mcpindex-config-wire wire --drift-telemetry off
```
