mcp-trust

MCP Trust Registry

Check before you connect. A neutral, public danger grade for the MCP servers

your AI agents rely on.

Live: mcp-trust.vercel.app

Not yet published to PyPI. Install from source using the Quickstart below.

Use as an MCP server

mcp-trust runs as a read-only MCP server so an agent can check a server's danger grade *before connecting* — it serves a baked snapshot of real scan grades with explicit per-record provenance, so no database or network is needed.

mcp-trust mcp-serve          # from a source/dev install (works today)

uvx mcp-trust mcp-serve # once published to PyPI

The MCP runtime admits the packaged catalog only after deterministic schema-v2 validation, including duplicate-key rejection, required field/type checks, unique slugs and source coordinates, supported enums, sandbox/scan-mode agreement, and timezone-aware scan timestamps. Admission also binds grade to danger score, transparency to annotation coverage, and critical findings to the grade cap. Raw JSON is limited to 1 MiB, with deterministic server, finding, tool, and public-string ceilings. Schema v2 preserves additive unknown fields; missing or invalid required fields and unknown schema versions fail closed.

If catalog admission fails, list_servers and check_server serve zero records and return mcp-trust-mcp-error.v1 with status UNKNOWN, error code CATALOG_SNAPSHOT_INVALID, sorted reason codes, and server_count_served: 0. get_methodology remains available. This boundary checks internal consistency; it does not prove snapshot authenticity, authorship, immutability, or freshness.

Offline consumers can add those missing publication checks with mcp-trust verify-snapshot: a detached Ed25519 statement binds the exact snapshot bytes, publisher ID, bounded issue/expiry window, monotonic publication ID, and prior consumer checkpoint. The consumer must independently pin the trust-root SHA-256 and preserve the returned checkpoint for rollback resistance. Invalid, expired, unknown-signer, forked, or rolled-back inputs return only UNKNOWN reason codes and no grades. See docs/OFFLINE-SNAPSHOT-TRUST-V1.md. Statement freshness proves recent publication authorization, not a recent scan; the per-record scan timestamp and 90-day stale policy remain separate checks.

No production trust root, signing key, statement, or checkpoint ships today, so the built-in MCP snapshot remains structural-only unless a consumer separately supplies and pins those inputs. Test fixture keys are not publication keys.

Connecting an MCP server hands it influence over what your agent does. Tool poisoning, prompt injection, over-broad permissions, and rug-pull tool mutations are documented attack classes -- and today there's no quick way to vet a server before you wire it in. MCP Trust Registry scans public MCP servers and gives each one a single readable danger grade (A-F), a separate transparency signal, and the findings behind them.

Think OSV.dev / Socket.dev / haveibeenpwned, scoped to MCP servers.

Prerequisites

• Python 3.12 or newer; .python-version pins 3.15.0 for local setup
• uv (used for dependency management and running the project)

The project requires uv==0.13.0. Run the commands below from the repository root; uv sync creates the project virtualenv using the committed lockfile.

MCP config portability studio

Render one versioned, secret-placeholder-only MCP connection intent into staged Codex, Claude Code, Claude Desktop, or VS Code configuration and receive an explicit semantic loss/widening report:

uv run --frozen --extra dev mcp-trust portability validate \

tests/fixtures/portability/local-stdio.json uv run --frozen --extra dev mcp-trust portability round-trip \ tests/fixtures/portability/local-stdio.json --host codex

The studio is local-only. It never discovers or edits a real host config, launches an MCP server, contacts a URL, or emits modeled secret values. Generated configuration proves only documented host-format compatibility, not a runtime connection or adoption. See docs/MCP-CONFIG-PORTABILITY-STUDIO.md.

How it works

register a server  ->  scan via engine  ->  derive grade  ->  persist  ->  serve at a stable URL

The registry does not reimplement vulnerability detection. It orchestrates a pluggable scan engine -- the shipping backend wraps the public mcp-audits (>=2.7.0,<3) package -- and owns the catalog, the public trust-grade normalization, persistence, and the lookup API.

Quickstart

git clone https://github.com/saagpatel/mcp-trust.git

cd mcp-trust uv sync --frozen --extra dev

demo_dir="$(mktemp -d)" uv run --no-sync mcp-trust seed --db "$demo_dir/registry.db" env -u MCP_TRUST_RECEIPTS_DIR uv run --no-sync mcp-trust scan \ mcp-reference-time --engine stub --db "$demo_dir/registry.db" uv run --no-sync mcp-trust check mcp-reference-time --db "$demo_dir/registry.db"

After dependency installation, this demo uses only a new temporary SQLite database and the explicit StubEngine; it launches no catalog server and its grades are demo data. --db avoids the default database and any operator MCP_TRUST_DB override; clearing MCP_TRUST_RECEIPTS_DIR avoids writing into an operator receipt directory.

To view this demo through the local API, optionally start a loopback-only, read-only server and stop it with Ctrl-C when finished:

MCP_TRUST_ENGINE=stub MCP_TRUST_PUBLIC_READONLY=1 \

MCP_TRUST_MASKED_GRADES="$PWD/masked-grades.json" \ uv run --no-sync mcp-trust serve --db "$demo_dir/registry.db" \ --host 127.0.0.1 --port 8000

Real-engine scans require the separately prepared [engine] environment, reviewed target, sandbox decision, and current qualification/preflight evidence in the operator runbook. They can launch server processes or contact remote endpoints and are outside this local demo and routine verification. See local development and verification for fixture checks.

API

Every server has two orthogonal signals: a danger grade (A-F) and a transparency level (high/medium/low, from annotation coverage). Automated grades are not endorsements, certifications, or claims that a server is malicious. A low grade on a low-transparency server means "cannot verify safe," not "known dangerous."

HTTP scan triggering is fail-closed by default. Public deployments should set MCP_TRUST_PUBLIC_READONLY=1, which makes POST /servers/{slug}/scan return 403 before any engine can run. Operator scans should normally run through the CLI against the persistent registry DB, not through public traffic.

For local API demos with the deterministic StubEngine, set MCP_TRUST_ALLOW_UNAUTHENTICATED_STUB_SCANS=1. Do not set that in public. Token-gated API scan triggering is still available for private operator surfaces by setting MCP_TRUST_SCAN_TOKEN and passing it as Authorization: Bearer or X-MCP-Trust-Scan-Token.

If the newest stored scan row is unreadable, API, web, static, badge, and snapshot projections fail closed to UNKNOWN; they never resurrect an older grade. Stored source/risk/finding/evidence JSON has a 1 MiB per-field admission ceiling, with bounded finding/tool collections and content-free diagnostics. An unreadable older row leaves a readable latest grade intact but makes scan history and grade-change claims explicitly UNKNOWN. Snapshot construction stops until unreadable history is repaired or dispositioned.

All public surfaces use one fail-closed freshness projection. Exactly 90 days after a scan is still FRESH; any later instant is STALE. Missing, malformed, or future scan times are UNKNOWN, with verdict fields withheld. Unscanned entries are NOT_APPLICABLE. Operator masking applies even when no scan exists and is never inferred from scan state. Static pages and badges are immutable historical evidence with a scan date or validity boundary; they do not promise request-time freshness. Danger, transparency, and evidence quality remain separate signals, and a grade is never an endorsement.

Set MCP_TRUST_RECEIPTS_DIR=/data/mcp-trust/receipts during real scan runs to archive a JSON receipt for each scan and store its portable artifact filename in report_ref.

Remote authorization metadata preflight

Remote Registry candidates can be checked for discoverable MCP authorization metadata without contacting the MCP endpoint or handling credentials. First build a candidate manifest from a previously saved official Registry response, then select one exact stable_id:

uv run python scripts/plan_registry_corpus.py \

--input path/to/saved-registry-response.json > /tmp/registry-candidates.json

uv run mcp-trust auth-posture com.example/remote@1.0.0 \ --manifest /tmp/registry-candidates.json \ --pretty

If a public WWW-Authenticate: Bearer challenge has already been obtained by a separate operator workflow, pass its value with --www-authenticate. Otherwise the command tries the MCP-required protected-resource well-known paths, followed by RFC 8414 and OpenID Connect authorization-server discovery in specification order.

The command emits McpAuthorizationPostureV1 JSON (contract 1.1.0, additive). It reads against the MCP 2026-07-28 authorization profile and still accepts servers that only meet 2025-11-25. Per authorization server it records whether RFC 9207 iss support is advertised, whether Client ID Metadata Documents are supported, and that the metadata issuer matched; a server that offers only Dynamic Client Registration (deprecated in 2026-07-28) gets a deprecated_registration note, not a failure. Exit 0 and state=metadata-ready mean only that at least one authorization server exposes the endpoints and PKCE S256 metadata needed for policy review. They do not prove authorization, credential availability, runtime security, scan eligibility, or a trust grade. Unknown or invalid evidence exits 1 and stays blocked; an invalid local manifest binding exits 2.

The network boundary is deliberately narrow: HTTPS metadata GETs only, no ambient proxies, redirects, credentials, endpoint session, or writes. DNS is resolved once per request; every answer must be globally routable, and the connection is pinned to an accepted address while TLS validation and SNI remain bound to the original hostname. Response bodies are size-bounded, validated, and represented in output only by byte count and SHA-256. Successful metadata