DEV Community

Wannavf
Wannavf

Posted on

MCP Sentinel v1.0 Is Out: A Lockfile for MCP Tool Schemas

#mcp #ai #opensource #devtools

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
Enter fullscreen mode Exit fullscreen mode

Since then, I shipped MCP Sentinel v1.0.0.

GitHub:

https://github.com/Wannavf/mcp-sentinel
Enter fullscreen mode Exit fullscreen mode

npm:

npm install -g @wannavf/mcp-sentinel
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

v1.0 now has a fuller workflow.

sentinel init
sentinel discover --write
sentinel doctor
sentinel snapshot
sentinel check
sentinel diff
Enter fullscreen mode Exit fullscreen mode

Discovery

You can now ask Sentinel to find MCP servers from common config locations:

sentinel discover
sentinel discover --write
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

or:

sentinel db
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Reports

Sentinel can output diffs in multiple formats:

sentinel diff --format json
sentinel diff --format markdown
sentinel diff --format sarif
Enter fullscreen mode Exit fullscreen mode

SARIF can be uploaded to GitHub Code Scanning.

Transports

v1.0 supports:

stdio
Streamable HTTP
SSE
Enter fullscreen mode Exit fullscreen mode

Example stdio config:

{
  "compatibility": "BACKWARD",
  "failOn": "MAJOR",
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Example HTTP config:

{
  "servers": {
    "remote": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Examples of safer changes:

optional parameter added
tool added
enum value added
description updated
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

With a lockfile:

MCP server changes
CI detects drift
you review the contract change
you decide whether to accept it
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

or:

npx -y @wannavf/mcp-sentinel --help
Enter fullscreen mode Exit fullscreen mode

GitHub:

https://github.com/Wannavf/mcp-sentinel
Enter fullscreen mode Exit fullscreen mode

npm:

https://www.npmjs.com/package/@wannavf/mcp-sentinel
Enter fullscreen mode Exit fullscreen mode

I would especially like feedback from people using MCP with database, filesystem, infrastructure, or internal admin tools.

Top comments (0)