A few days ago I posted about a problem I hit with MCP tool schema drift.
The short version:
An MCP server changed a parameter from location to city.
My agent kept sending location.
Nothing warned me before runtime.
That first version of MCP Sentinel was just the basic idea:
sentinel init
sentinel snapshot
sentinel check
sentinel diff
Since then, I shipped MCP Sentinel v1.0.0.
GitHub:
https://github.com/Wannavf/mcp-sentinel
npm:
npm install -g @wannavf/mcp-sentinel
The framing changed a bit
The original problem was annoying because it broke my tools silently.
But after feedback, I think the bigger point is this:
MCP tool schemas are contracts.
If a tool changes its parameters, required fields, enum values, return shape, or descriptions, that is not just a small implementation detail.
It changes what an agent can ask for.
It can also change when the agent decides to use that tool.
That matters a lot for MCP servers around:
databases
filesystems
cloud infrastructure
admin tools
internal APIs
A broken weather tool is annoying.
A silently changed database or infrastructure tool can be much worse.
What v1.0 adds
The first version was basically:
snapshot
check
diff
v1.0 now has a fuller workflow.
sentinel init
sentinel discover --write
sentinel doctor
sentinel snapshot
sentinel check
sentinel diff
Discovery
You can now ask Sentinel to find MCP servers from common config locations:
sentinel discover
sentinel discover --write
It can look for MCP-shaped configs and help import servers into sentinel.config.json.
This makes onboarding less manual.
Doctor
There is now a setup check:
sentinel doctor
It checks whether Sentinel can see your config, whether servers are configured correctly, and whether the lockfile exists.
Instead of guessing why something does not work, you get a quick sanity check.
Dashboard
There is also a terminal dashboard:
sentinel dashboard
or:
sentinel db
It lets you inspect configured servers, snapshots, checks, activity, and drift locally.
It is not the main feature, but it is useful when testing MCP servers during development.
CI
The main use case is still CI.
sentinel check
If a server changed its tool contract, CI can fail before the agent discovers the break at runtime.
There is also a GitHub Action:
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
Reports
Sentinel can output diffs in multiple formats:
sentinel diff --format json
sentinel diff --format markdown
sentinel diff --format sarif
SARIF can be uploaded to GitHub Code Scanning.
Transports
v1.0 supports:
stdio
Streamable HTTP
SSE
Example stdio config:
{
"compatibility": "BACKWARD",
"failOn": "MAJOR",
"servers": {
"filesystem": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}
}
}
Example HTTP config:
{
"servers": {
"remote": {
"transport": "http",
"url": "http://localhost:3000/mcp"
}
}
}
What it catches
Sentinel classifies changes as MAJOR, MINOR, or PATCH.
Examples of MAJOR changes:
tool removed
required parameter removed
parameter type changed
optional parameter made required
constraint tightened
enum value removed
output field removed
Examples of safer changes:
optional parameter added
tool added
enum value added
description updated
The goal is not to block every change.
The goal is to make tool contract changes explicit.
Why I think this matters
Without a lockfile:
MCP server changes
agent breaks later
you debug at runtime
With a lockfile:
MCP server changes
CI detects drift
you review the contract change
you decide whether to accept it
That feels like a missing piece in MCP tooling.
Package managers have lockfiles.
APIs have contracts.
MCP tool schemas should have a review point too.
Try it
npm install -g @wannavf/mcp-sentinel
or:
npx -y @wannavf/mcp-sentinel --help
GitHub:
https://github.com/Wannavf/mcp-sentinel
npm:
https://www.npmjs.com/package/@wannavf/mcp-sentinel
I would especially like feedback from people using MCP with database, filesystem, infrastructure, or internal admin tools.
