Schema drift detection for MCP servers. Sentinel snapshots your MCP tool schemas into a lockfile, then tells you when a server changes a tool in a way that may break agents.
npx -y @wannavf/mcp-sentinel init
npx -y @wannavf/mcp-sentinel discover --write
npx -y @wannavf/mcp-sentinel doctor
npx -y @wannavf/mcp-sentinel snapshot
npx -y @wannavf/mcp-sentinel check
npx -y @wannavf/mcp-sentinel diffSentinel creates sentinel-lock.json for your MCP server tool schemas. When a tool changes later, sentinel check exits non-zero for CI and sentinel diff shows what changed.
Already have MCP servers configured in Claude, Cursor, Windsurf, VS Code, or local MCP config files?
npx -y @wannavf/mcp-sentinel discover --writeDiscovery shows candidate servers and lets you choose which ones to add to sentinel.config.json.
MCP servers expose tools, but the protocol does not give every tool schema its own version. A server can change a parameter from optional to required, remove an enum value, or tighten a constraint. Your agent may only discover that break at runtime.
Sentinel gives you:
- A deterministic lockfile for MCP tool schemas
- MAJOR, MINOR, and PATCH schema drift classification
- Console, JSON, Markdown, and SARIF reports
- GitHub Action support for CI
- Config discovery for common MCP clients and project files
- Stdio, Streamable HTTP, and SSE transport support
- A terminal dashboard for local inspection
npm install -g @wannavf/mcp-sentinelOr use it without installing:
npx -y @wannavf/mcp-sentinel --helpCreate sentinel.config.json and an empty sentinel-lock.json.
sentinel initThe default example uses the official filesystem MCP server and watches the current directory (.).
Find MCP server configs on your machine and optionally import them.
sentinel discover
sentinel discover --write
sentinel discover --jsonDiscovery scans common MCP config locations plus MCP-shaped JSON files in the current project. If a server is not stored in a config file, add it manually.
Validate config, server entries, and lockfile readiness.
sentinel doctor
sentinel doctor --config sentinel.config.json --lockfile sentinel-lock.jsonConnect to configured MCP servers and record current tool schemas.
sentinel snapshot
sentinel snapshot --server filesystemCompare live tool schemas against the lockfile. Exit code is 0 when clean and non-zero when drift meets the configured failure severity.
sentinel check
sentinel check --fail-on MINOR
sentinel check --server githubShow detailed schema changes.
sentinel diff
sentinel diff --format json
sentinel diff --format markdown
sentinel diff --format sarifAccept the current live schemas as the new baseline.
sentinel update
sentinel update --server filesystemPoll servers and report schema drift.
sentinel watch
sentinel watch --interval 10Score schema quality, including missing descriptions and weak type coverage.
sentinel audit
sentinel audit --server filesystemCompare two lockfiles without connecting to live servers.
sentinel lockfile-diff --old sentinel-lock.old.json --new sentinel-lock.json
sentinel lockfile-diff -o old.json -n new.json --format markdownOpen the interactive terminal dashboard.
sentinel dashboard
sentinel dbKeys: s snapshot selected, a snapshot all, c check selected, C check all, d print recent diff, / filter activity, space pause activity, q quit.
sentinel.config.json:
{
"compatibility": "BACKWARD",
"failOn": "MAJOR",
"servers": {
"filesystem": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}
},
"rules": {
"DESCRIPTION_SEMANTICS_CHANGED": "PATCH"
}
}Each servers entry is one MCP server Sentinel can connect to.
{
"servers": {
"my-server": {
"transport": "stdio",
"command": "node",
"args": ["C:\\path\\to\\my-mcp-server.js"]
}
}
}{
"servers": {
"remote": {
"transport": "http",
"url": "http://localhost:3000/mcp"
}
}
}{
"servers": {
"legacy-remote": {
"transport": "sse",
"url": "http://localhost:3000/sse"
}
}
}After adding servers:
sentinel doctor
sentinel snapshot
sentinel checkMAJOR examples:
- Tool removed
- Required parameter removed
- Parameter type changed
- Optional parameter made required
- Constraint tightened, such as
minimum: 0tominimum: 1 - Enum value removed
- Output field removed
MINOR examples:
- Optional parameter removed
- Default value changed
- Annotation changed
- Output field added as required
PATCH examples:
- Optional parameter added
- Tool added
- Enum value added
- Description updated
sentinel-lock.json is deterministic and git-friendly:
{
"formatVersion": 2,
"generatedAt": "2026-05-08T20:00:00.000Z",
"generatedBy": "@wannavf/mcp-sentinel@1.0.0",
"contentHash": "sha256:...",
"servers": {
"filesystem": {
"transport": "stdio",
"protocolVersion": "0.6.2",
"serverInfo": {
"name": "filesystem",
"version": "0.6.2"
},
"snapshotAt": "2026-05-08T20:00:00.000Z",
"schemaHash": "",
"tools": {
"read_file": {
"hash": "sha256:...",
"description": "Read the complete contents of a file",
"inputSchema": {
"type": "object",
"properties": {
"path": { "type": "string" }
},
"required": ["path"]
},
"outputSchema": null,
"annotations": {}
}
}
}
}
}name: MCP Schema Check
on: [pull_request]
jobs:
drift:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: Wannavf/mcp-sentinel@main
with:
fail-on: MAJOR- run: npx -y @wannavf/mcp-sentinel diff --format sarif > sentinel.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: sentinel.sarifsentinel/
src/
cli/ 11 commands
core/ lockfile, transport, hashing, types
diff/ schema diff engine and rules
reporters/ console, JSON, Markdown, SARIF
test/ node:test coverage
action.yml
sentinel.config.json
package.json
v1.0.0 is focused on practical schema drift detection. Formal compatibility proofs with generated counterexamples and richer PR comment automation are planned future work.
MIT