Allows an AI agent to check the danger grade and transparency of public MCP servers before establishing a connection.
Also known as saagpatel/mcp-trust
- Stars
- 0
- Tools
- 3
- Downloads, 30 days
- 238
- Latest version
- 0.1.1
- Last commit
- Nov 13, 2026
- License
- MIT
What is trust MCP?
trust allows an AI agent to check the danger grade and transparency of public MCP servers before establishing a connection. It exposes 3 tools, such as list_servers, check_server, get_methodology.
Summary generated from the project's README
About trust MCP server
mcp-trust provides a security layer for AI agents by offering a public registry of danger grades and transparency scores for MCP servers. It allows developers and agents to evaluate the risk of a server before establishing a connection, helping to prevent issues like tool poisoning or over-broad permissions. The server functions as a read-only provider that serves a baked snapshot of scan results, meaning it does not require a live database or network connection during client use.
Users can interact with the registry through specific tools like list_servers to see all graded servers, check_server to retrieve detailed risk dimensions for a specific slug, and get_methodology to understand how grades are calculated. The system uses a deterministic schema to ensure data integrity and includes a 90-day freshness policy to mark results as stale. For advanced security, offline consumers can use the verify-snapshot command with Ed25519 signatures to ensure the authenticity of the catalog.
What you can do with it
- 1Pre-connection risk assessmentAn AI agent can check the danger grade of a server before it is wired into the runtime.
- 2Audit server transparencyDevelopers can evaluate how much information a server provides through its transparency signal.
- 3Verify snapshot authenticity offlineUsers can use detached signatures to confirm that a local catalog has not been tampered with.
- 4Validate configuration portabilityDevelopers can test how MCP connection intents translate across different host configurations.
Written from the project's README. Every use case is checked against a quote from it.
How to install trust MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall trust MCP in Claude Code
$ claude mcp add mcp-trust -- uvx mcp-trust mcp-serveInstall trust MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-trust": {
"command": "uvx",
"args": [
"mcp-trust",
"mcp-serve"
]
}
}
}Install trust MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-trust": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-trust",
"mcp-serve"
]
}
}
}Install trust MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-trust","type":"stdio","command":"uvx","args":["mcp-trust","mcp-serve"]}'Install trust MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-trust": {
"command": "uvx",
"args": [
"mcp-trust",
"mcp-serve"
]
}
}
}Install trust MCP in Codex
$ codex mcp add mcp-trust -- uvx mcp-trust mcp-serveInstall trust MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-trust] command = "uvx" args = ["mcp-trust", "mcp-serve"]
Install trust MCP in Gemini CLI
$ gemini mcp add -s user mcp-trust uvx -- mcp-trust mcp-serveInstall trust MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-trust": {
"command": "uvx",
"args": [
"mcp-trust",
"mcp-serve"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for mcp-trust 0.1.1 in an isolated container with no network and no keys. It answered and listed 3 tools.
trust MCP tools 3
Read from the server with tools/listlist_serversList every graded MCP server with its trust grade. Returns JSON.
check_serverLook up the full trust grade, dimensions, and findings for one server by slug.
get_methodologyExplain how trust grades are computed and the honesty model behind them.
Configuration
MCP_TRUST_DBMCP_TRUST_ENGINEMCP_TRUST_MASKED_GRADESMCP_TRUST_PUBLIC_READONLY
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesaagpatel/mcp-trust is public and reachablegithub.com/saagpatel/mcp-trust ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Sigstore attestation for mcp-trustpypi.org/project/mcp-trust/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/saagpatel/mcp-trust ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mcp-trustPass
- No critical advisory in the package or its dependencies39 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMCP 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
| Tool | Description |
|---|---|
list_servers |
Every graded MCP server with its A-F grade, transparency, and danger score. |
check_server |
Full grade, risk dimensions, and findings for one server by slug. |
get_methodology |
How the A-F grade and transparency axis are computed, plus the honesty model. |
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-versionpins 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.
Importing Trust Before Connect verdicts (experimental)
mcp-trust import-card card.json [--pin pin.json] stores a verdict card from
MCPAudit's experimental mcp-audit trust command as a catalog entry, graded by
this registry's rubric. Imported verdicts stay demo-classified and are not
published by importing. See docs/trust-card-import.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
| Method | Path | Purpose |
|---|---|---|
GET |
/ |
web -- public catalog page (grade + transparency per server) |
GET |
/ui/servers/{slug} |
web -- server detail page + README badge-embed snippet |
GET |
/healthz |
liveness |
GET |
/servers |
catalog + latest grade, provenance, and staleness per server (JSON) |
GET |
/servers/{slug} |
full latest scan record + provenance/staleness and metadata (JSON) |
POST |
/servers/{slug}/scan |
operator scan trigger; public deployments disable this route |
GET |
/servers/{slug}/badge.json |
shields.io-compatible README badge |
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 (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
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
trust MCP questions
How do I add trust MCP to Claude Code?
Run claude mcp add mcp-trust -- uvx mcp-trust mcp-serve in your terminal. Add --scope user to make it available in every project.
How do I add trust MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does trust MCP provide?
It exposes 3 tools, including list_servers, check_server, get_methodology.
What does mcp-trust do?
It scans public MCP servers and provides a readable danger grade (A-F), a transparency signal, and the findings behind them.
Does a high grade mean a server is safe?
No, automated grades are not endorsements or certifications; a low grade on a low-transparency server simply means the server cannot be verified as safe.
How can I use it as an MCP server?
You can run it as a read-only MCP server so an agent can check a server's danger grade before connecting.