TrustDex MCP server

TrustDex

A local-first trust and provenance gate for AI agent tools.

TrustDex helps decide which MCP servers, skills, and plugins an AI agent should be allowed to use. Instead of treating every discovered extension as trusted, TrustDex evaluates observable evidence and returns one of three outcomes:

• ALLOW - matches an explicit trust policy
• ASK - needs human review
• BLOCK - not trusted under the current policy

TrustDex is security-related infrastructure, not a malware scanner, sandbox, or certification service. An ALLOW result only means the inspected evidence matched your policy.

Project status: TrustDex is early-stage and seeking pilot users. The security boundary is documented, changes are tested on supported Node.js versions, and compatibility may still evolve before 1.0. See the roadmap, governance, and support guide.

Why TrustDex?

AI agents increasingly rely on third-party MCP servers, skills, and plugins that may receive credentials, access files, connect to remote services, or execute local programs. A package being installable does not mean it should automatically become available to an agent.

TrustDex adds a decision layer before tool exposure:

User request
    |
    v
AI agent / Codex
    |
    v
TrustDex policy + provenance gate
    |-- ALLOW -> tool may be exposed
    |-- ASK   -> require human review
    `-- BLOCK -> keep tool unavailable

TrustDex deliberately does not infer "official" status from names, stars, or branding. Provenance must come from explicit, reviewable evidence.

What the current code can do

• inspect MCP server entries locally without uploading configuration
• distinguish package, remote, local, and unknown sources
• detect trust-relevant signals such as floating versions, install-on-run launchers, shell execution, filesystem-looking arguments, secret-like environment variable names, and remote endpoints
• inspect SKILL.md files and plugin manifests for trust-relevant metadata/instructions
• apply built-in strict, official-first, and development policy packs
• attach explicit publisher/provenance assertions from a local trust store
• output ALLOW / ASK / BLOCK decisions
• generate a filtered MCP config containing only policy-approved tools
• create snapshots and detect source, provenance, decision, and capability drift
• create Ed25519-signed trust records for reviewed snapshots
• run as a GitHub Action in CI
• fingerprint MCP entries, skills, and plugin manifests without storing secret values
• inspect and filter Codex config.toml MCP sections
• inspect Codex approval, sandbox, network, writable-root, web-search, and subagent settings without retaining path values
• inspect and filter Claude Code MCP JSON with explicit transport validation and header execution controls
• inspect Claude Code permission settings for automatic shell, filesystem, network, MCP, and subagent grants without retaining rule values
• perform explicit provenance lookups against GitHub, npm, and the official MCP Registry
• verify whether the latest GitHub release tag/commit has a GitHub-verified signature
• create signed review bundles and automatically require re-review when trust-relevant state drifts
• redact credentials, paths, and query values from remote endpoint details in reports
• block embedded URL credentials and insecure remote transport under strict policies
• recognize Windows executable paths and command wrappers consistently across hosts
• fail closed on unsupported Codex MCP keys and subsections
• verify user-supplied package bytes against npm SRI or MCP Registry SHA-256 metadata
• bind integrity-backed trust evidence to the configured package version and block mismatches
• bind each Claude/Codex MCP source decision and provenance state to its automatic tool grant without retaining tool names or rule values
• reconcile explicit, value-free runtime MCP inventories with reviewed bindings and detect blocked or unexpected loaded servers
• authenticate short-lived runtime inventories with Ed25519 producer attestations, expiry, and optional capture-age limits
• verify review records and runtime attestations against a strict keyset allowlist with key purposes, validity windows, rotation, and revocation
• inspect VS Code-compatible editor extensions (VS Code, Cursor) by exact version and installed-file digest, and require re-review when an extension is added, updated, or modified
• emit a versioned, fail-closed JSON decision contract for agents and automation, and validate policy files strictly against a published schema

Compatibility

TrustDex requires Node.js 20 or newer. CI exercises the full test and gate workflow on Ubuntu with Node.js 20 and 22, and on current Windows and macOS runners with Node.js 22. The checked-out composite GitHub Action has a dedicated end-to-end smoke test.

Quick start

Requires Node.js 20+.

Run directly from npm:

npx trustdex@0.13.1 --help
npx trustdex@0.13.1 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json

Or work from a source checkout:

git clone https://github.com/grigent/trustdex.git
cd trustdex
npm test
npm run check

node ./bin/trustdex.mjs inspect ./examples/mcp.json \
  --pack strict \
  --policy ./examples/trustdex.policy.json

The example intentionally includes an unknown server, so a strict inspection exits non-zero.

Exit codes for inspection:

• 0 - all entries allowed
• 1 - at least one entry needs review
• 2 - at least one entry is blocked, or the command failed

Reproducible defensive research

TrustDex includes an inert adversarial benchmark for testing the policy boundary without contacting or executing third-party services. The fixtures use reserved .invalid domains, placeholder credentials, and configuration data only; TrustDex inspects them statically and never launches the listed servers.

npm run test:research

node ./bin/trustdex.mjs inspect \
  ./examples/adversarial/mcp-config.json \
  --pack strict \
  --policy ./examples/adversarial/policy.json

The direct inspection intentionally exits with code 2: the checked-in expectation is one ALLOW, one ASK, and five BLOCK decisions. The automated test also verifies that placeholder secret values do not appear in results and that a newly introduced secret-bearing environment variable invalidates the previous review state.

See the defensive AI-agent security use case, defensive security research policy, evaluation record, and adversarial fixture guide.

Built-in policy packs

node ./bin/trustdex.mjs policy strict
node ./bin/trustdex.mjs policy official-first
node ./bin/trustdex.mjs policy development

official-first does not maintain a hard-coded list of supposedly official vendors. It allows sources only when they have explicit provenance evidence in your trust store (or when you explicitly allowlist them), while unknown third-party sources remain blocked by default.

See Trust store and provenance.

Filter tools before agent use

node ./bin/trustdex.mjs gate ./examples/mcp.json \
  --pack official-first \
  --out .trustdex/gated-mcp.json

By default, only ALLOW entries are written to the gated configuration. ASK entries stay out until reviewed.

This is the core TrustDex boundary: the agent receives the filtered configuration instead of the unreviewed source configuration.

Inspect skills and plugins

node ./bin/trustdex.mjs inspect-skill ./path/to/SKILL.md --pack strict
node ./bin/trustdex.mjs inspect-plugin ./path/to/plugin.json --pack strict

These checks surface observable trust signals. They do not prove that the extension is safe.

Inspect IDE extensions

Editor extensions such as the Claude Code extension for VS Code and Cursor run with your local privileges and update automatically. TrustDex inventories an extensions directory you name, digests every installed file, and only allows extensions pinned to an exact version:

node ./bin/trustdex.mjs inspect-ide-extensions ~/.cursor/extensions \
  --pack strict --policy ./ide-policy.json
node ./bin/trustdex.mjs approve-ide-extensions ~/.cursor/extensions \
  --private trustdex-private.pem --dir .trustdex/ide-review --policy ./ide-policy.json
node ./bin/trustdex.mjs recheck-ide-extensions ~/.cursor/extensions \
  --review-dir .trustdex/ide-review --public trustdex-public.pem

An unreviewed update, such as a pinned 2.1.312 becoming 2.1.313, is never ALLOW (BLOCK under strict and official-first, ASK under development) and is reported as NEEDS_REVIEW by recheck-ide-extensions. Nothing is executed and no network request is made. See IDE extensions for signals, policy fields, and limits.

Use from agents and automation

Inspection commands accept --decisions to print a versioned, value-free JSON decision report (schemas/trustdex-decisions-v1.schema.json). Its exit code always matches the decision, and if inspection fails it still prints a BLOCK report, so a harness cannot fail open. Policy files are validated strictly: unknown fields and invalid actions are rejected. See Agent integration for how to read the report safely, and for how to keep the policy, trust store, and signing key out of an agent's reach.

Codex config.toml

Current Codex clients store MCP configuration under [mcp_servers.<name>] tables in config.toml. TrustDex has a focused adapter for those MCP sections:

node ./bin/trustdex.mjs inspect-codex ./examples/codex.config.toml --pack strict

node ./bin/trustdex.mjs gate-codex ./examples/codex.config.toml \
  --pack strict \
  --out .trustdex/gated-codex.toml

The gate removes non-approved MCP sections while preserving unrelated TOML sections. TrustDex intentionally parses only the MCP-related TOML constructs it needs; unsupported MCP syntax fails rather than being silently trusted.

Inspect the agent's execution boundary separately from its MCP tools:

node ./bin/trustdex.mjs inspect-codex-settings \
  ./examples/codex.permissions.toml \
  --pack strict

This reports approval policy, sandbox class, network access, additional writable-root count, web-search mode, and explicit subagent enablement. It does not retain writable paths or values from unrelated settings. To inspect the documented merged precedence, provide each active source explicitly; repeat --project from repository root toward the current directory:

node ./bin/trustdex.mjs inspect-codex-settings-stack \
  --system ./review/system.toml \
  --user ./review/user.toml \
  --project ./review/root-project.toml \
  --project ./review/closest-project.toml \
  --cli ./review/cli-overrides.toml \
  --pack strict

See Using TrustDex with Codex for a step-by-step gating workflow and for how this project uses Codex in its own review process.

Claude Code MCP configuration

Claude Code uses the mcpServers JSON shape. Use the Claude-specific commands so transport changes, authentication header metadata, and header helper commands are included in inspection and signed review:

node ./bin/trustdex.mjs inspect-claude ./.mcp.json --pack strict
node ./bin/trustdex.mjs gate-claude ./.mcp.json --pack strict --out .trustdex/claude-mcp.json
claude --strict-mcp-config --mcp-config .trustdex/claude-mcp.json

Check the gate's result before starting Claude. Only ALLOW entries are exposed by default; ASK entries require review. The adapter rejects settings it cannot inspect instead of silently trusting them. These commands are available in npm 0.5.0 and later, and from a source checkout. Use npx trustdex@0.13.1 in place of node ./bin/trustdex.mjs to run the published CLI.

See Using TrustDex with Claude for supported settings, PowerShell error handling, signed review, and the Claude Desktop workflow.

Claude Code project and user settings can also grant actions without prompting. Inspect the documented permissions object and nearby executable settings separately:

node ./bin/trustdex.mjs inspect-claude-settings \
  ./.claude/settings.json \
  --pack strict

The command reports structural capability evidence only. It does not print or fingerprint permission specifiers, directory values, hook commands, domains, credential-helper values, or environment values. To calculate the documented file precedence and list merging, pass the sources explicitly:

node ./bin/trustdex.mjs inspect-claude-settings-stack \
  --user ./review/user.settings.json \
  --project ./.claude/settings.json \
  --local ./.claude/settings.local.json \
  --session ./review/session.settings.json \
  --managed ./review/managed-settings.json \
  --pack strict

The stack inspector remains a static review aid, not a runtime sandbox. It does not discover files, environment overrides, or organization policy automatically; only supplied sources are evaluated.

Permission posture drift

Record a value-free structural baseline for either runtime, then compare it after an agent or policy change:

node ./bin/trustdex.mjs snapshot-claude-settings \
  ./.claude/settings.json \
  --pack strict \
  --out .trustdex/claude-posture.json

node ./bin/trustdex.mjs snapshot-codex-settings \
  ~/.codex/config.toml \
  --pack strict \
  --out .trustdex/codex-posture.json

node ./bin/trustdex.mjs snapshot-claude-settings-stack \
  --user ./review/user.settings.json \
  --project ./.claude/settings.json \
  --managed ./review/managed-settings.json \
  --pack strict \
  --out .trustdex/claude-stack-posture.json

node ./bin/trustdex.mjs diff-permissions \
  .trustdex/approved-posture.json \
  .trustdex/current-posture.json \
  --json

diff-permissions exits 1 when automatic grants, writable scope, network access, subagents, policy semantics, or another unclassified setting expands. A change that is only more restrictive exits 0 with status restricted. Snapshots contain counts, documented enums, capability categories, risk signals, and a policy-semantics digest; they omit input paths, rule specifiers, writable paths, domains, commands, environment names and values, and unrelated setting values. Same-count changes to redacted rule contents cannot be detected, so this is an advisory CI review gate rather than runtime enforcement.

Machine consumers can validate --json output against schemas/permission-posture-v1.schema.json and schemas/permission-posture-diff-v1.schema.json. Merged-source snapshots and their diffs use schemas/permission-posture-v2.schema.json and schemas/permission-posture-diff-v2.schema.json. Schema changes require a new integer schemaVersion; fields are not silently repurposed.

Tool provenance and automatic permission bindings

Review an MCP source and the automatic permission granted to it as one value-free record:

node ./bin/trustdex.mjs snapshot-claude-bindings ./.mcp.json \
  --settings ./.claude/settings.json \
  --trust-store ./trust-store.json \
  --out .trustdex/claude-bindings.json

node ./bin/trustdex.mjs snapshot-codex-bindings ~/.codex/config.toml \
  --trust-store ./trust-store.json \
  --out .trustdex/codex-bindings.json

node ./bin/trustdex.mjs diff-bindings \
  .trustdex/approved-bindings.json \
  .trustdex/current-bindings.json \
  --json

Claude stack source flags can replace --settings. A scoped grant can be bound only when its MCP source is ALLOW; wildcard/all-tool grants, ASK sources, changed provenance, unmatched rules, and ambiguous server-name matches require review or are blocked. Codex default_tools_approval_mode = "approve" is treated as an all-tool grant. Reports retain server names and structural counts, but omit endpoint paths, permission specifiers, and tool names. Validate them with schemas/tool-permission-bindings-v1.schema.json and schemas/tool-permission-bindings-diff-v1.schema.json. This is review evidence, not runtime permission enforcement.

Effective runtime tool evidence

An authorized runtime adapter can emit a minimal inventory containing only runtime, capture method, server names, and tool counts. TrustDex reconciles that explicit input with a binding snapshot without searching private files or intercepting tool calls:

node ./bin/trustdex.mjs keygen \
  --private .trustdex/runtime-producer-private.pem \
  --public .trustdex/runtime-producer-public.pem

node ./bin/trustdex.mjs sign-runtime-inventory \
  ./runtime-tool-inventory.json \
  --private .trustdex/runtime-producer-private.pem \
  --out .trustdex/runtime-attestation.json \
  --ttl-seconds 300

node ./bin/trustdex.mjs snapshot-runtime-tools \
  .trustdex/claude-bindings.json \
  ./runtime-tool-inventory.json \
  --attestation .trustdex/runtime-attestation.json \
  --public .trustdex/runtime-producer-public.pem \
  --max-age-seconds 120 \
  --require-authenticated \
  --out .trustdex/runtime-tools.json

node ./bin/trustdex.mjs diff-runtime-tools \
  .trustdex/approved-runtime-tools.json \
  .trustdex/current-runtime-tools.json \
  --json

Observed BLOCK sources and unexpected servers produce block; observed ASK or broad automatic-grant bindings produce needs-review; configured servers absent from the inventory are restriction-only. Tool-count growth and newly observed servers require review. An unauthenticated schema-v2 inventory is always at least needs-review. Authentication verifies the exact inventory, pinned producer key, expiry, and optional capture-age limit; it does not prove completeness or adapter safety. The schemas are schemas/runtime-tool-inventory-v1.schema.json, schemas/runtime-tool-inventory-attestation-v1.schema.json, schemas/effective-runtime-tools-v2.schema.json, and schemas/effective-runtime-tools-diff-v2.schema.json. Legacy v1 effective reports remain readable. Because the contract retains counts instead of tool names, same-count tool-set substitutions remain outside this comparison. See Authenticated runtime evidence for verification, key rotation, and threat-boundary guidance.

Every verifying command (verify, recheck*, verify-runtime-inventory, snapshot-runtime-tools) also accepts --keyset keyset.json instead of --public: a strictly validated trustdex-keyset allowlist with per-key purpose, validity windows, overlapping keys for rotation, and revocations (schemas/trustdex-keyset-v1.schema.json). node ./bin/trustdex.mjs key-id key.pem prints the key ID to list. See Keysets for the revocation-timing rules and rotation procedure.

Online provenance observations

Normal inspection remains local-only. These commands perform an explicit network lookup only when invoked:

node ./bin/trustdex.mjs provenance github modelcontextprotocol/servers
node ./bin/trustdex.mjs provenance github-release owner/repository
node ./bin/trustdex.mjs provenance npm @scope/package
node ./bin/trustdex.mjs provenance mcp io.github.user/server

A lookup is evidence, not trust. To turn evidence into a local trust-store claim, the user must explicitly name the publisher:

node ./bin/trustdex.mjs trust-source mcp io.github.user/server \
  --publisher "Example Publisher" \
  --out ./trust-store.json

For github-release, TrustDex refuses to create a trust claim unless GitHub reports the release tag or target commit signature as verified.

Verify exact package bytes

Registry metadata can identify an expected digest, but metadata alone does not prove that a downloaded file matches it. Supply the exact package archive or artifact you reviewed:

node ./bin/trustdex.mjs trust-source npm @scope/package \
  --publisher "Example Publisher" \
  --artifact ./scope-package-1.2.3.tgz \
  --out ./trust-store.json

node ./bin/trustdex.mjs trust-source mcp io.github.user/server \
  --publisher "Example Publisher" \
  --artifact ./downloaded-package \
  --out ./trust-store.json

TrustDex reads the file locally and compares its bytes with npm SRI metadata or an MCP Registry SHA-256 digest. It does not download or execute the artifact. Integrity-backed evidence is version-bound; a different configured package version receives artifact-version-mismatch and is blocked.

Provenance trust store

Example:

{
  "version": 1,
  "claims": [
    {
      "type": "package",
      "subject": "example-mcp-server",
      "publisher": "Example Publisher",
      "status": "verified",
      "evidence": {
        "kind": "manual-review",
        "reference": "https://example.invalid/security-review"
      }
    }
  ]
}

Then:

node ./bin/trustdex.mjs inspect ./mcp.json \
  --pack official-first \
  --trust-store ./trust-store.json

Here, verified means verified according to the evidence maintained in that trust store. It does not mean OpenAI, TrustDex, GitHub, npm, or another platform certified the extension.

Capability and provenance drift

Save a baseline:

node ./bin/trustdex.mjs snapshot ./examples/mcp.json \
  --pack strict \
  --out .trustdex/baseline.json

Save another snapshot after an update and compare them:

node ./bin/trustdex.mjs diff .trustdex/baseline.json .trustdex/current.json

TrustDex reports newly added signals, source changes, provenance changes, decision changes, and content/configuration fingerprint changes.

For a review workflow, generate a signing key once and approve a non-blocked configuration:

node ./bin/trustdex.mjs keygen \
  --private .trustdex/private.pem \
  --public .trustdex/public.pem

node ./bin/trustdex.mjs approve ./examples/mcp.json \
  --private .trustdex/private.pem \
  --dir .trustdex/review \
  --pack development

Later, re-evaluate the current configuration against that signed review:

node ./bin/trustdex.mjs recheck ./examples/mcp.json \
  --review-dir .trustdex/review \
  --public .trustdex/public.pem

The result is APPROVED, NEEDS_REVIEW, or INVALID. A fingerprint, source, provenance, signal, or policy-relevant change invalidates the previous state match.