Skip to content
Back to search

getvda

MarketplaceWorks with Claude CodeGitHub

getvda.ai plugins for safer agents: MCP Drift Guard and the MCP Drift Observatory.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/getvda-ai--mcp-drift-guard/badge.svg)](/listings/getvda-ai--mcp-drift-guard)

HTML

<a href="/listings/getvda-ai--mcp-drift-guard"><img src="/api/listings/getvda-ai--mcp-drift-guard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx mcp-drift-guard lock     # probe your servers, write mcp-tools.lock.json, then commit it
npx mcp-drift-guard check    # exit 1 if anything changed
npx mcp-drift-guard update   # accept the change after you've reviewed it (then check the git diff)
npx mcp-drift-guard observe https://mcp.example.com/mcp   # any public server, no config needed

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "name": "getvda",
  3. "owner": {
  4. "name": "getvda.ai",
  5. "url": "https://getvda.ai"
  6. },
  7. "plugins": [
  8. {
  9. "name": "mcp-drift-guard",
  10. "source": "./plugin",
  11. "description": "Lockfile for MCP tool definitions: warns when a server's tools change and flags tool-poisoning signals."
  12. },
  13. {
  14. "name": "mcp-drift-observatory",
  15. "source": "./directory",
  16. "description": "Read-only: ask Claude whether a public MCP server changed its declared tools, and see what changed."
  17. }
  18. ],
  19. "description": "getvda.ai plugins for safer agents: MCP Drift Guard and the MCP Drift Observatory."
  20. }
README.md · README · 127 lines · 1 finding marked
  1. # MCP Drift Guard
  2. **A lockfile for the tools your MCP servers declare.** It fails CI, or warns you when a Claude Code session starts, as soon
  3. as a server you depend on changes its tool names, descriptions or schemas.
  4. Tool definitions go straight into your agent's prompt. A server that rewrites a description (a "rug pull") changes
  5. what your agent does, and nothing in your repo changes. `npm` has `package-lock.json`. Your MCP tools now have
  6. `mcp-tools.lock.json`.
  7. ```text
  8. ⚠️ local stdio 3 tools drifted
  9. - added send_notes 🚩 exfil_wording
  10. - changed get_weather: description 🚩 instruction_tags, conceal_from_user, sensitive_paths
  11. ```
  12. - Works with **every** server you can reach: remote (Streamable HTTP, legacy SSE) and local (stdio), including
  13. servers behind auth. Your secrets stay in your CI.
  14. - **And the public ones you can't.** When this run can't read a remote server (no secret in this job, blocked from the
  15. runner, down right now), it falls back to the MCP Drift Observatory's last nightly observation and compares hashes.
  16. You can even pin a server you have never connected to. See [Observatory fallback](#observatory-fallback).
  17. - Reads `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor) and `.vscode/mcp.json` (VS Code), with `${VAR}` expansion.
  18. - Shows a field-level diff (`description`, `inputSchema`, `annotations`…) and flags known tool-poisoning tells:
  19. hidden instructions, `<IMPORTANT>` tags, "don't tell the user", sensitive paths, exfiltration wording, invisible
    • Warning: Contains a <important> block, a common wrapper for instructions hidden in a tool description
    • Line 23 on GitHub
  20. Unicode, cross-tool overrides, descriptions that more than double in length. These are signals, not verdicts.
  21. - Hashes are byte-identical to the [MCP Drift Observatory](https://drift.getvda.ai)'s `drift_hash` (`canon_version` 1), so you can compare your
  22. pins with a public, independent record.
  23. ## Quick start
  24. ```bash
  25. npx mcp-drift-guard lock # probe your servers, write mcp-tools.lock.json, then commit it
  26. npx mcp-drift-guard check # exit 1 if anything changed
  27. npx mcp-drift-guard update # accept the change after you've reviewed it (then check the git diff)
  28. npx mcp-drift-guard observe https://mcp.example.com/mcp # any public server, no config needed
  29. ```
  30. ## GitHub Action
  31. ```yaml
  32. - uses: actions/checkout@v6
  33. - uses: getvda-ai/mcp-drift-guard@v0
  34. env:
  35. EXAMPLE_API_KEY: ${{ secrets.EXAMPLE_API_KEY }} # anything your .mcp.json references as ${VAR}
  36. ```
  37. Run it on pull requests **and on a daily schedule**: servers change without a commit on your side. See
  38. [`examples/mcp-drift-guard.yml`](examples/mcp-drift-guard.yml), which also opens an issue when the nightly run finds drift.
  39. | Input | Default | |
  40. |---|---|---|
  41. | `mode` | `check` | `check`, `update` or `lock` |
  42. | `lockfile` | `mcp-tools.lock.json` | |
  43. | `config` | the three files above | comma- or newline-separated |
  44. | `fail-on` | `any` | `any`, `signals` (only changes that carry a poisoning signal) or `never` |
  45. | `stdio` | `true` | `false` checks remote servers only |
  46. | `timeout-ms` | `30000` | per server |
  47. | `observatory` | `true` | fall back to the observatory for remote servers this run can't read |
  48. | `public-feed` | `true` | the public history cross-check below |
  49. | `reader-card` | | your A2A Agent Card URL, if you have one |
  50. Outputs: `drift`, `signals`, `report` (Markdown, also written to the job summary) and `json`.
  51. `stdio: true` runs the commands in your MCP config, as Claude Code or Cursor would. A pull request that edits
  52. `.mcp.json` can therefore run code in CI, as it already can through your test scripts. Use `stdio: false` on
  53. untrusted pull requests if that matters for your repo.
  54. ## Claude Code plugin
  55. ```text
  56. /plugin marketplace add getvda-ai/mcp-drift-guard
  57. /plugin install mcp-drift-guard@getvda
  58. ```
  59. - **At session start** it checks your remote servers against the lockfile. It stays silent unless something drifted;
  60. then it tells you, and tells Claude to treat the changed descriptions as unreviewed.
  61. - **A skill** that locks, checks and explains drift on request, and never accepts a change without you.
  62. - **The MCP Drift Observatory's tools** (`drift_check`, `drift_diff`, `drift_probe`, `drift_status`, `drift_hash`) for public
  63. servers. The skill asks before sending a server URL to them.
  64. ## Observatory fallback
  65. A remote server can't be read from a run when its secret isn't in that job, when a firewall blocks the runner, or when
  66. it's down. Before, that server just showed "not checked". Now, for public `https` servers, mcp-drift-guard asks the
  67. [MCP Drift Observatory](https://drift.getvda.ai) what it saw at its last nightly crawl (`drift_check`, plus `drift_diff`
  68. when there were changes) and compares that hash with your pin. The hashes are the same bytes, so the comparison is exact.
  69. | Locally | Observatory | Result |
  70. |---|---|---|
  71. | read OK | (not asked) | full diff, as before |
  72. | can't read | knows it, same hash as your pin | ✅ unchanged (via observatory, with the date it was seen) |
  73. | can't read | knows it, different hash | ⚠️ drifted, with the observatory's change summary and a link to its tool-level diff |
  74. | can't read | doesn't know it | not checked |
  75. - `lock` pins such a server from the observatory's hash alone. There is no stored definition to diff yet, so the first
  76. `update` after you can read it stores the full definitions.
  77. - Observations older than 7 days are marked **stale**.
  78. - **What leaves the run:** each such server's origin and path, for example `https://mcp.example.com/mcp`. Never the
  79. query string, headers, credentials or tool definitions. Hosts that look private (`localhost`, `10.x`, `192.168.x`,
  80. `.internal`, `.corp`…), plain `http`, and URLs with an unexpanded `${VAR}` in the host or path are never sent.
  81. - It covers what the observatory can see: public servers that answer without auth. Turn it off with `observatory: false`,
  82. `--no-observatory` or `DRIFT_GUARD_OFFLINE=1`.
  83. ## The public history cross-check, over RSS-A
  84. The [MCP Drift Observatory](https://github.com/mikerawsonnz/mcp-drift-observatory) crawls public MCP servers every night,
  85. hashes what each declares and publishes every change as a **signed feed**. It uses [RSS-A](https://github.com/getvda-ai/rssa)
  86. (RSS for Agents), an open protocol: an ordinary Atom/RSS feed that is linked from the publisher's A2A Agent Card,
  87. with every entry signed by the publisher's key.
  88. On each run, mcp-drift-guard reads the last 14 days of that feed, **verifies every signature**, and adds a public history
  89. to the report, for example "this server changed its tools on 6 of the last 14 days". Only the feed is fetched: your
  90. server list, config and tool definitions never leave the run. The request carries a short anonymous client id (a hash
  91. of the repository name in CI, a random id locally) so the publisher can count distinct readers, never who they are.
  92. Turn it off with `public-feed: false`, `--no-public-feed` or `DRIFT_GUARD_OFFLINE=1`.
  93. You can subscribe to the same feed in any feed reader:
  94. <https://hub.rssa.getvda.ai/network/@getvda-mcp-drift-observa-e131.atom>
  95. ## What it can't see
  96. It compares **declarations**, not behaviour. A server that keeps its tool list byte-identical while changing what the
  97. tools do is invisible to this check, and to every other client-side check. Servers that are unreachable or need
  98. credentials you didn't provide are reported as "not checked", never as "unchanged".
  99. ## Licence and privacy
  100. Apache-2.0. Maintained by [getvda.ai](https://getvda.ai) (Rawson Consulting B.V.). See [PRIVACY.md](PRIVACY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.