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 <token> 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. 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 responses must also carry a valid HTTP Date; declared cache freshness is honored up to a 24-hour policy cap, while missing, future-dated, or stale source evidence remains unknown. The implementation is based on the MCP authorization specification, RFC 9728, RFC 8414, and OpenID Connect Discovery.

Reusable web release readback

This repository owns the language-neutral WebReleaseReadbackV1 contract and its standard-library reference verifier. A consumer supplies an explicit HTTPS origin plus a versioned route-sentinel manifest:

python scripts/web_release_readback.py \
  --manifest path/to/release-routes.json \
  --target-url https://preview.example.com \
  --pretty

The command emits one structured receipt to stdout and exits nonzero when any status, required or forbidden sentinel, exact body, digest, body bound, timeout, or redirect assertion fails. It implements only GET and HEAD, ignores ambient proxies, accepts no credentials, and has no deployment, alias, DNS, promotion, or rollback capability. The schemas, deterministic artifact manifest, versioning policy, and rollback boundary live under contracts/web-release-readback-v1/.

The owner repository also consumes the contract through deploy/web-release-readback.json. deploy/smoke-readonly.sh emits the shared route receipt before running the registry-specific health, API, badge, portable receipt-reference, and denied scan-POST assertions. This self-adoption is a release readback check only; it neither deploys nor changes an alias.

This generic receipt is additive. Product-specific API, badge, privacy, release lineage, and denied-mutation checks remain owned by each consumer until proven receipt parity justifies removing only their duplicated HTTP assertion plumbing.

Evidence lineage decisions

EvidenceLineageLedgerV1 is a metadata-only, fail-closed contract for MCP corpus admit, refresh, publish, and withdraw decisions. It binds exact identity, digests, portable receipt references, freshness, rights evidence, public projections, supersession, and retention without storing raw logs or secrets. The read-only assessor requires an explicit observation time and emits stable reason codes; only an explicit ALLOWED status can authorize admit or publish.

See docs/EVIDENCE-LINEAGE-LEDGER-V1.md for the schema, decision semantics, three-record packaged-catalog pilot, claim ceiling, and rollback boundary. This source capability does not itself migrate the catalog, publish or withdraw records, run scans, or change deployment state.

Manual refresh candidates

First emit the no-execution inventory, exact source/tool/image preflight, and deterministic repeated fixture receipt:

Runtime refresh commands require a separately prepared frozen [engine] environment. They use its exact interpreter and never hydrate dependencies as part of preflight or candidate creation:

PYTHON=./.venv/bin/python
test -x "$PYTHON"

"$PYTHON" scripts/grade_refresh.py engine-materialization \
  --repo-root "$PWD" \
  --out ./dist/grade-refresh/engine-materialization.json
"$PYTHON" scripts/grade_refresh.py inventory \
  --out ./dist/grade-refresh/inventory.json
"$PYTHON" scripts/grade_refresh.py host-capacity \
  --anchor "$PWD" \
  --out ./dist/grade-refresh/host-capacity.json

# Stop unless the two-reading receipt is READY. Start the separately approved
# Colima instance only after this point, then create the bound preflight.
"$PYTHON" scripts/grade_refresh.py preflight \
  --repo-root "$PWD" \
  --engine-materialization ./dist/grade-refresh/engine-materialization.json \
  --host-capacity ./dist/grade-refresh/host-capacity.json \
  --out ./dist/grade-refresh/preflight.json
uv run --frozen --extra dev python scripts/grade_refresh.py fixture-repeat \
  --out ./dist/grade-refresh/fixture-repeatability.json

The capacity receipt requires at least 5 GiB available and less than 100 percent capacity in two readings at least 30 seconds apart. It is revalidated before Docker, MCP, or registry-database work, expires after 120 seconds, and binds the host filesystem device without recording a host path. The source contract does not itself prove that an operator kept Colima stopped until the receipt passed, or authenticate the observation against same-user replacement; provenance without a separately sealed operator binding remains UNKNOWN. Offline image qualification requires one newly observed, cohort-scoped receipt per invocation. The set is append-only; use the same new reviewed set name for all five cohorts, but never reuse a capacity receipt across cohorts:

: "${MCP_TRUST_QUALIFICATION_RECEIPT_SET:?set a new reviewed task-owned receipt-set name}"
for cohort in reference live-batch batch3 batch4 basic-memory; do
  uv run --frozen python scripts/grade_refresh.py qualification-capacity \
    --operation qualification \
    --receipt-set "${MCP_TRUST_QUALIFICATION_RECEIPT_SET}" \
    --cohort "$cohort" \
    --out "./dist/grade-refresh/qualification-capacity-$cohort.json"
  uv run --frozen python scripts/qualify_refresh_images.py \
    --cohort "$cohort" \
    --host-capacity "./dist/grade-refresh/qualification-capacity-$cohort.json" \
    --receipt-set "${MCP_TRUST_QUALIFICATION_RECEIPT_SET}"
done

The five exact qualification_receipt paths in src/mcp_trust/catalog/refresh_policy.json are authoritative; a version label in documentation is never authority.

The qualifier creates an immutable source/input-bound set manifest and writes a pessimistic append-only attempt intent before the first Docker mutation. It revalidates the bound receipt immediately before every Docker or Buildx subprocess and never renews it. If capacity expires or regresses, no qualification receipt is emitted and the intent remains unresolved, so Docker state and qualification are UNKNOWN. Before retrying that cohort, issue a new receipt with --operation cleanup and run the qualifier with --cleanup-cohort "$cohort"; cleanup acts only on the exact recorded tags and outputs and must append a successful readback receipt. Existing sets without the immutable manifest, unknown artifacts, overwritten receipts, and source or input drift are refused. A successful build appends a qualification completion binding; cleanup completion is required only for an interrupted attempt. A qualification manifest preserves its originating revision as provenance but reopens against a qualification-specific digest map. That map includes the qualifier and its runtime modules, Dockerfiles, dependency inputs, locks, artifact descriptors, and nested source-build evidence. Generated docker/refresh/qualification/ evidence and refresh_policy.json receipt pointers are adoption metadata, so tracking them does not self-invalidate a completed set; dependency-bundle bytes are independently revalidated against their descriptor digests before each build, and receipt and graph integrity remains independently mandatory. Any executable or build-input drift still fails closed. A per-set process lock and attempt-unique temporary tag prevent concurrent qualification from sharing mutation state. Interruption cleanup removes only the intent-recorded OCI, validation-receipt, and digest-bound tool-snapshot residue. It never rewrites the final tag: readback must show either the recorded baseline or the exact task-owned image ID, and any other value remains ambiguous and blocked. Do not execute a catalog server unless preflight returns READY. The receipt binds the 31-entry classification, including the exact derived 22 scannable and 9 blocked execution boundary, source and policy digests, tool versions, local Docker authority, immutable image IDs, and explicit network, filesystem, resource, and secret controls. See docs/GRADE-REFRESH-PROGRAM.md and the operator runbook.

Create a review candidate without mutating the canonical registry, baked snapshot, static site, schedule, or deployment:

"$PYTHON" scripts/refresh_candidate.py create \
  --db ./registry.db \
  --out-dir ./dist/refresh-candidates \
  --qualification-receipt ./dist/grade-refresh/preflight.json

The command refuses local-process scans unless the bound preflight receipt is current and READY, and Docker and every catalog-pinned image are available locally at the recorded immutable IDs. Those sources run through the existing network-off, read-only, capability-dropped, resource-bounded sandbox. Each local container is pre-created and the connector is bound to start only that immutable ID; scan evidence is accepted only after the bound daemon proves it absent. A timeout without that readback remains UNKNOWN. Remote endpoints are probed over their live network transport without a local process sandbox and are labeled accordingly. New immutable bundles use RefreshCandidateV2 and contain self-digested execution-bound receipts, catalog identity, scan times and ages, blocked/masked/failed/timeout/unknown evidence states, attributed scan drift, an honest static snapshot, source/tool bindings, freshness counts and earliest expiry, semantic projection digests, and a content-bound manifest. Legacy V1 bundles remain structurally inspectable but are publication-ineligible.

Candidate creation has no publication or deployment authority. Structural verification reports schema and publication eligibility separately; a valid V1 artifact cannot acquire V2 authority by self-assertion. A current, complete, reviewed-input-bound V2 candidate is only an input to later local admission. Eligibility never grants approval, publication, deployment, rollback, scheduling, or outreach authority.

A separately supplied McpTrustPublicationApprovalV1 can be verified and used to build a deterministic local copy-only package:

uv run --frozen python scripts/build_publication_package.py \
  --verify-approval ./dist/publication-approval.json \
  --candidate ./dist/site-candidates/<name>
uv run --frozen python scripts/build_publication_package.py --build \
  --candidate ./dist/site-candidates/<name> \
  --approval ./dist/publication-approval.json \
  --out ./dist/publication-packages/<name>
uv run --frozen python scripts/build_publication_package.py \
  --verify-package ./dist/publication-packages/<name> \
  --approval ./dist/publication-approval.json

This admission is provider-free and local-only. It binds the V2 candidate, repeatability and triage lineage, exact V38 review, current provider evidence, rollback target, operator statement digest, and the minimum freshness expiry. Every mutation authority remains false. A package is not deployment authority, publication proof, rollback authority, scheduler authority, endorsement, or production-freshness evidence.

The manual static deploy lane requires a separate short-lived McpTrustProductionDeployAuthorizationV4 binding that exact package, content approval, provider and operator receipts, retained rollback bytes, source revision, output, and tool digests. It revalidates before and after live TTY confirmation. After any provider call, freshness remains UNKNOWN until a provider/source-bound McpTrustProductionPublicationReceiptV1 verifies the exact all-route readback receipt. A missing provider artifact digest can never be promoted to FRESH.

Snapshot signing is a separate authority after candidate approval/staging. The refresh process never receives a signing or recovery key, and its SHA-256 manifest is not a publisher identity. Production signing remains disabled until an operator chooses the root, custody, thresholds, publication counter, and checkpoint owner described in the offline trust contract.

Status

Stack

The project uses Python, FastAPI, SQLite, Typer, Pydantic, mcp-audits as an optional scan engine, Ruff, Pyright and pytest. Dependency versions are locked in uv.lock; the project requires Python 3.12 or newer.

Known risks

Live at mcp-trust.vercel.app as a statically generated catalog, regenerated from the local registry. The bundled catalog snapshot contains 23 visible real mcp-audits grades; eight seed entries are absent from it, including the four currently withheld by masked-grades.json. The bundled snapshot labels the visible local-process grades' network and sandbox provenance as unknown; only a receipt-verified refresh candidate may claim network-off execution. Every grade is labeled by provenance, so demo/stub data can never read as a real scan, and an unscanned server never shows a letter grade. The current production deployment is the 31-server static catalog; grades are static since 2026-07-11, when the weekly re-scan lane was disabled and its deploy authority removed (see docs/CAPABILITY-RULING-2026-07-10.md).

The static front door is the low-ops launch path (see DEPLOY-VERCEL.md); a weekly launchd job under deploy/launchd/ is persistently disabled and current host readback shows it unloaded. A dormant installed plist remains and differs from the repository template; treat it as configuration drift and do not load or enable it. The compatibility entrypoint can create a local review candidate only, after no-execution preflight; it cannot publish or deploy. The live FastAPI service + VM path remains documented in DEPLOY-VM.md as an alternative. See SPEC.md for the full contract and LAUNCH-GATE.md for launch history. The deployed catalog reports scan timestamps as its freshness authority; static HTML does not claim to attest machine-local scheduler state.

The deployed catalog may therefore be stale. A live URL response can be served from cache; current catalog content recency is unverified by this repository description. Static HTML freshness does not attest current scheduler state, and local tests do not establish live provider or deployment behavior. Current GitHub Actions status is also unverified by this repository description.

On this macOS host, Python 3.15.0 required a source build of locked pydantic-core 2.46.4; the build completed, but its extension failed to load. The full Python 3.15 CI result is unverified. The supported CI matrix remains 3.12 through 3.15 pending that hosted check.

Next steps

Contributing

uv.lock is intentionally committed to the repository to ensure reproducible installs across environments. When adding or updating dependencies, commit the updated uv.lock alongside your pyproject.toml changes.

Run make setup to install the frozen development dependencies and make check for the aggregate local gate.

Local development and verification

Use make setup from the repository root. This is the same core/dev environment as CI; it does not install the optional real scan engine. Prepare a development shell with a temporary database and no operator scan/receipt overrides:

verification_dir="$(mktemp -d)"
export MCP_TRUST_DB="$verification_dir/registry.db"
export MCP_TRUST_ENGINE=stub
export MCP_TRUST_PUBLIC_READONLY=0
unset MCP_TRUST_MASKED_GRADES MCP_TRUST_RECEIPTS_DIR \
  MCP_TRUST_RUN_INTEGRATION MCP_TRUST_RUN_DOCKER_RUNTIME_READBACK

# Focused CLI/API fixtures; choose the test file or node for your changed module.
uv run --no-sync pytest -q tests/test_cli.py tests/test_api.py
# Aggregate deterministic local gate, as used by CI.
make check

Fixtures use temporary data and mocked runtime/provider boundaries. Keep both integration opt-ins unset: MCP_TRUST_RUN_INTEGRATION=1 launches a real MCP server, and MCP_TRUST_RUN_DOCKER_RUNTIME_READBACK=1 uses Docker. Those checks need separate operator authorization and prerequisites; they are not part of the routine gate. The full suite includes POSIX pseudo-terminal tests; use the Ubuntu CI runner when the local platform cannot provide a pseudo-terminal. MCP_TRUST_TEST_TTY_TIMEOUT adjusts their subprocess budget for a loaded machine without weakening the assertions.

make check runs Ruff lint and format checks, Pyright, pytest and a package build. For web/static/badge changes, focus on tests/test_web.py, tests/test_site_generator.py, tests/test_build_site_script.py and tests/test_api.py, then run the broader gate before delivery.

When HTML, layout, navigation, or displayed trust claims change, also inspect a local browser preview at desktop and narrow widths. Build one with explicit temporary paths and the script's stub-only demo mode:

uv run --no-sync python scripts/build_site.py \
  --db "$verification_dir/preview.db" --out "$verification_dir/site" \
  --demo-fill --base-url http://127.0.0.1:8765
uv run --no-sync python -m http.server 8765 --bind 127.0.0.1 \
  --directory "$verification_dir/site"

Open http://127.0.0.1:8765 and check the catalog, one detail page, navigation, demo/provenance labels, masked grades and badge content. Stop the preview with Ctrl-C. This development build writes only temporary demo data and pages; it is not a publication candidate. Browser checks are conditional on changed user-facing behavior, rather than required for pure documentation changes. The API and web/static guidelines define the trust claims that must remain consistent across surfaces. Local fixture/build/browser results do not establish real-engine, provider, deployment, or production proof.

License

MIT