Metadata-Version: 2.4
Name: mcpindex-gate
Version: 0.9.0
Summary: mcpindex gate — the in-path, zero-egress-by-default trust-to-act client for MCP tool calls (open core).
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). 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.

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

## 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) | 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.
