Install mcp-vault

Three ways to run the same check: in CI, before each commit, or on your laptop. All three are offline by default — no network call, no token, no telemetry — and all three read the same MCP configs: .mcp.json (Claude Code), .cursor/mcp.json (Cursor) and .vscode/mcp.json (VS Code).

1. GitHub Action (CI)

# .github/workflows/mcp-vault.yml
name: mcp-vault

on:
  pull_request:
    paths:
      - '**/.mcp.json'
      - '**/.vscode/mcp.json'
      - '**/.cursor/mcp.json'
      - '.mcp-vault.policy.json'

permissions:
  contents: read

jobs:
  mcp-vault:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1   # v7.0.1
        with:
          persist-credentials: false
      - uses: froggychips/mcp-skills-vault@449bac6f1f66f240f906d6ad25cc1da909169677 # v0.16.0
        with:
          paths: '**/.mcp.json **/.vscode/mcp.json **/.cursor/mcp.json'
          # sarif: true   # findings in code scanning; needs security-events: write

Why a SHA and not @v0.16.0: a tag can be moved, a commit cannot. The action runs its own checkout, and the CLI has no dependencies, so nothing is installed from npm and no install script runs — pinning the action by SHA pins the gate by SHA. Keep the version in the comment so Dependabot or Renovate can update both.

By default the job fails on anything that could not be checked (unpinned, not in the vault, a local command); fail-on: error fails only on a deny, fail-on: warning on warnings too. A policy file can raise the bar, never lower it. Every input, output and the SARIF setup are in the Action docs.

2. pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/froggychips/mcp-skills-vault
    rev: 449bac6f1f66f240f906d6ad25cc1da909169677   # v0.16.0 — `pre-commit autoupdate --freeze` writes it
    hooks:
      - id: mcp-vault
      # - id: mcp-vault
      #   args: [--strict]

Runs mcp-vault check --fail-on unknown on staged .mcp.json, .vscode/mcp.json and .cursor/mcp.json, offline. A plain-text secret is stopped before it reaches git history, where it would have to be rotated.

3. CLI, locally

Node 18 or newer. No clone, no global install needed.

Check this repository

The same check the Action and the hook run, over the configs in the current directory. Nothing from your home directory is read.

npx -y @froggychips/mcp-vault check
npx -y @froggychips/mcp-vault check --strict    # warnings fail too

Check your machine: start with status

One command, about fifteen lines: what is installed, what is wrong with it, and what this project is missing. It makes no network calls — every claim comes from evidence already on disk, with the date it was established. Exit 1 means something installed must not run; exit 2 means a host config could not be read, so the report is incomplete and says which.

npx -y @froggychips/mcp-vault status

Servers are matched by artifact identity, not by the name in your config, and the version is compared separately: stored evidence about x@1.0.0 is not a finding about x@2.0.0 in either direction. A server on a version nobody verified gets no tier at all, and an unpinned npx -y pkg is reported as what it is.

Prefer it on PATH for repeated use: npm i -g @froggychips/mcp-vault, then drop the npx -y prefix.

Look closer where it pointed

status summarises; these answer in full. verify --installed re-hashes what your hosts actually launch, against the live registries. explain <name> prints one entry’s evidence with dates, the policy in force, and the rule that decided it. scan reads the project’s stack.

npx -y @froggychips/mcp-vault verify --installed
npx -y @froggychips/mcp-vault explain mcp-server-fetch
npx -y @froggychips/mcp-vault scan --cwd .

Ask why, before you argue with it

Every dimension with the date it was established, the policy in force, each rule with its outcome, and the rule that decided it. --record appends the decision as one JSON line, which is the audit trail a policy engine gets asked for months later.

npx -y @froggychips/mcp-vault explain <name>

When something has an advisory

The shortest version that clears every advisory against the pin — not the newest release — with the candidate checked too, because “fixed in 2.1.30” means fixed for that one advisory.

npx -y @froggychips/mcp-vault upgrade

Freeze what actually runs

npx -y pkg@1.2.3 re-resolves that package’s dependency tree at every start: a pinned root does not pin its tree. lock records npm’s own lockfile per server, --check diffs a fresh resolve against it, and --vendor installs the locked tree so nothing resolves at launch.

npx -y @froggychips/mcp-vault lock
npx -y @froggychips/mcp-vault lock --check

Optional: verify the vault database offline

For air-gapped smoke checks. It validates the stored pins only and makes no registry or advisory call.

npx -y @froggychips/mcp-vault verify --offline

Optional: install the vault as a Claude Code skill

If you want Claude to call the vault by itself when you ask “what MCP should I add?”, drop the skill folder into your skills directory.

git clone https://github.com/froggychips/mcp-skills-vault.git
mkdir -p ~/.claude/skills
cp -r mcp-skills-vault/mcp-ecosystem-intelligence ~/.claude/skills/

Looking for mcp-trace? It is an experimental sister project installed from git; its page has the steps.

CLI reference · Action docs · GitHub · npm