Install the gate. Or call the network.

For server-side agents, custom orchestrators, anything outside an MCP client.

# trust: does this tool do what it claims? (per-server or per-tool)
curl "https://mcpindex.ai/api/v1/trust/server/<slug>"

# screen: paste a description, get a live verdict (POST)
curl -X POST "https://mcpindex.ai/api/v1/screen" \
  -H "content-type: application/json" \
  -d '{"description":"Reads a file and returns its contents."}'

# discovery: find a tool for a task
curl "https://mcpindex.ai/api/v1/recommend?task=read+pdf+to+s3"

# pre-flight: discovery + the rank-1 server's verdict in one call
curl "https://mcpindex.ai/api/v1/preflight?task=read+pdf+to+s3"

# search: full-text registry search (?q= required; &category= &limit= optional)
curl "https://mcpindex.ai/api/v1/search?q=postgres&limit=10"

# diff: what changed in the registry since a date
curl "https://mcpindex.ai/api/v1/diff?since=2026-06-01"

# server: the full record for one server by slug
curl "https://mcpindex.ai/api/v1/server/<slug>"

# fleet drift query: has this tool's contract drifted? (crawler-corroborated)
curl "https://mcpindex.ai/api/v1/drift/any?fp=<tool_fingerprint>"

# drift ledger: contract changes the crawler observed (fingerprint-only)
curl "https://mcpindex.ai/api/v1/ledger"

trust returns a stored verdict (REVIEW or UNVERIFIED today; ALLOW / DENY are reserved in the contract); screen runs the live LLM judge on a pasted description and returns a fresh PARTIAL verdict; recommend returns ranked picks; preflight composes the two - the top servers plus the rank-1 server's advisory verdict in one round trip (verdict is null when that server is not yet screened - treat as not-cleared); search and diff query the registry; server returns one full record; drift/any answers whether a tool's contract drifted (crawler-corroborated; powers warns-you-on-call-1) and ledger lists the public drift record. All JSON, same shapes an MCP client gets.

For Claude Desktop, Cursor, Cline, Zed. Install once, the agent finds the rest from inside the loop.

npm install -g mcp-server-mcpindex

The package is a thin client to the same API. Zero config in most clients - see the wiring step below.

For platforms (Composio, Mastra, Toolhouse, IDE plays) that want MCP discovery as a feature.

// Server-side, your code:
const res = await fetch("https://mcpindex.ai/api/v1/recommend?task=" +
  encodeURIComponent(userTask));
const { recommendations } = await res.json();

Attribution appreciated. Email hello@mcpindex.ai if you want a higher rate limit.

For READMEs and server listings - a live SVG that always agrees with the verdict page.

<!-- Markdown (GitHub-style; extension-less, keys off Content-Type) -->
[![mcpindex](https://mcpindex.ai/api/v1/badge/<slug>)](https://mcpindex.ai/server/<slug>)

The badge reads the same verdict the site pages and the trust API use, so the three never disagree. States are screened / flagged / review / re-check due, and a fail-closed gray not screened for an unknown slug - never green, never a fake pass, never a broken image.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcpindex": {
      "command": "npx",
      "args": ["-y", "mcp-server-mcpindex@latest"]
    }
  }
}

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "mcpindex": {
      "command": "npx",
      "args": ["-y", "mcp-server-mcpindex@latest"]
    }
  }
}

Cline (VS Code)

Cline settings panel → MCP Servers → Add

Command:  npx
Args:     -y mcp-server-mcpindex@latest

Zed

~/.config/zed/settings.json

{
  "context_servers": {
    "mcpindex": {
      "command": "npx",
      "args": ["-y", "mcp-server-mcpindex@latest"]
    }
  }
}

Install (Claude Desktop / Cursor / Cline / Zed)

The auditable path: install the package, then let the wizard rewrite your host config so each MCP server launches behind the gate. The curl | shone-liner does the same thing in one step — inspect it first if you prefer:

# auditable path — install the package, then run the wiring wizard
uv tool install mcpindex-preflight

# convenience: the same install + host-config rewrite in one command.
# inspect it before you run it — it only rewrites your MCP host config,
# and uninstall.sh restores it:
curl -fsSL https://mcpindex.ai/install.sh | less   # read it first
curl -fsSL https://mcpindex.ai/install.sh | sh     # then run it

# Windows (PowerShell): https://mcpindex.ai/install.ps1

Prefer to wire it by hand? Rewrite each MCP server entry so the agent launches that server behindthe gate: keep the server’s original command as the gate’s argument. The example below wraps a stdio server (before → after); the same shape works in Cursor (.cursor/mcp.json) and Zed (~/.config/zed/settings.json). Restart the client after editing.

# claude_desktop_config.json — route an existing server through the gate

// before: the agent talks to the server directly
"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
}

// after: the gate launches the server and checks each tool's contract in-path.
// The original command becomes --upstream-command; each original arg becomes a
// separate --upstream-arg=VALUE (the =VALUE form is required — a dash-leading
// arg like -y does not survive a bare passthrough).
"filesystem": {
  "command": "uvx",
  "args": ["--from", "mcpindex-preflight", "python", "-m", "tooling.cse.proxy",
           "--mcpindex-stdio",
           "--upstream-command", "npx",
           "--upstream-arg=-y",
           "--upstream-arg=@modelcontextprotocol/server-filesystem",
           "--upstream-arg=/data"]
}

Easier: let the one-click installer write this for you — it rewrites every server entry, which is fiddly to do by hand. The gate forwards to your original server and checks the contract on every call. Zero credentials change hands: a stdio server’s original env and an http server’s original headersride through to your server untouched — the gate reads only the public tool contracts, never your tokens. The one-click installer (install.sh / install.ps1) does this rewrite for you across every detected host.

Remote / HTTP MCP servers

The example above wraps a stdio server. An http / url entry (a remote server like a hosted GitHub MCP) is routed through a local gateway instead: the gate rewrites the entry to point your client at a loopback gateway, and the gateway forwards to the upstream with your original headersthreaded through untouched — same zero-custody posture, just over HTTP.

One boundary to know: today the gateway gates only HTTPS upstreams that resolve to a public IP. A plain-http, localhost, or LAN upstream is rejected (ssrf_blocked), not silently passed through — gating those is on the roadmap. So a remote HTTPS server is gated like any stdio one; a local HTTP server is not yet covered.

SDK: wrap an already-authenticated session

For a server-side agent or custom orchestrator, wrap the MCP client session you already authenticated. One line; no per-server config, no token handling — the wrapper reuses the session’s own transport. list_tools / call_tool stay drop-in.

// TypeScript — npm i @mcp-index/sdk
import { wrap, PreflightPin } from "@mcp-index/sdk";

const guarded = wrap(session, { pin: new PreflightPin(), serverId: "your-server" });
// use guarded.list_tools() / guarded.call_tool(...) exactly as before

# Python
from tooling.cse.preflight_intercept import wrap
from tooling.cse.preflight import PreflightPin

session = wrap(session, pin=PreflightPin(), server_id="your-server")

Pass PreflightPin(path=…) to persist the baseline across restarts (so drift while the agent is offline is still caught on the next call). On a hold the wrapper raises (or calls your on_hold handler) with the structured verdict; the wrapped session is never called on a hold.

Postures and what a HOLD does

• Monitor— notify and proceed (awareness, no friction).
• Guard(default) — hold the unambiguously breaking and dangerous changes; auto-accept a proven-benign drift (added optional param, byte-identical description) and re-pin so cosmetic churn never raises a false alarm.
• Strict— hold on any drift.

A HOLD stops the call before your agent acts and surfaces what changed (the exact ChangeKind, the before/after on a description change). It is fail-closed: a tool the gate cannot verify holds rather than proceeds. You review, then re-pin if the change is expected. On an ambiguous change, the third-door behavioral verifier — a built in-path seam that is held off by default and requires explicit opt-in — can exercise the changed tool to clear or refute the change. It clears or refutes; it does not prove a tool safe.

Blast-radius grade (on by default)

Alongside the contract-diff, the gate labels what each call would do before your agent acts — action_type (read, write, delete, send), whether it can be undone (reversibility), and whether it leaves the machine (egress) — plus a static autonomy ceiling. A read and an irreversible delete look identical to an agent until something labels them; this is that label. It is on by default in @mcp-index/sdk and mcpindex-preflight.

The grade is read statically from the tool’s declared contract — it never runs the tool — so it is deterministic, needs no network, and carries no argument values (every field is a typed enum or hash). It is advisory and fail-closed: when the contract is ambiguous it grades toward the more dangerous class. It says what a call would do, not whether the contract is safe; your orchestrator owns whether to allow, pause, or require approval.

Ambient presence (on by default)

The clients leave a quiet trace that mcpindex is working: the first time each tool is used in a session, one dim line on stderr — mcpindex · noted github/delete_repo — delete, irreversible— then silence on every repeat call, plus a one-line session summary. It is local-only: no network, nothing persisted, and it never touches stdout or changes a gate decision.

The first line shows how to turn it off (silence: MCPINDEX_AMBIENT_NOTICE=off); the cadence tunes via MCPINDEX_AMBIENT_NOTICE_MODE (first_touch / summary / every / off), and it stays quiet in CI and under DO_NOT_TRACK. To render it in your own UI instead, pass an on_invocation callback (Python) / onInvocation (TS) to wrap().

Drift network (opt-in, off by default)

mcpindex crawls the public MCP registry every day and records which tool contracts silently change. Turn the network on with MCPINDEX_DRIFT_TELEMETRY=detection(off by default) and the gate asks it, on each pin, whether the crawler already caught this contract drifting — warning you on the first call. A contract-diff advisory: it rides alongside the verdict and never moves PROCEED or HOLD. Surfaced by renderVerdict and the fleetAdvisory field on the verdict.

Under the same flag the gate emits one one-way salted-fingerprint signal on a pin or a drift and queries /api/v1/drift/any; it never sends a schema, argument, description, URL, or server/tool name, and fails open (never blocks a call). Every drift the crawler catches is public in the /ledger. Full disclosure on privacy.