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

Wannavf — Sat, 09 May 2026 08:51:32 +0000

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.

My MCP Tools Broke Silently; So I Built a Lockfile for MCP

Wannavf — Thu, 07 May 2026 11:00:49 +0000

The Problem

I run AI agents that depend on MCP servers. One morning, everything broke. No error message. No warning. Just silent failures.

After 4 hours of debugging, I found it: the MCP server updated and renamed a parameter from location to city. My agent was still sending location. The server returned a cryptic -32602 error.

The MCP spec has 9,400+ servers and 97 million SDK downloads per month. But it has zero per-tool versioning. When a server changes its tool schemas, nothing tells you what changed or whether it matters.

What I Built

MCP Sentinel a lockfile for MCP servers. Think package-lock.json, but for MCP tool schemas.

npm install -g @wannavf/mcp-sentinel

sentinel init          # Setup wizard
sentinel snapshot      # Lock current schemas
sentinel check         # Detect drift → exit code for CI
sentinel diff          # See exactly what changed

GitHub: github.com/Wannavf/mcp-sentinel
npm: npm install -g @wannavf/mcp-sentinel
License: MIT

Issues and PRs welcome.

Forem: Wannavf