MCP Sentinel

Runtime call-chain anomaly monitor for MCP servers. Sentinel watches what an MCP server actually does across a whole agent session — not just what a single tool definition says — and catches the emergent attacks that static scanners miss.

Why this exists

There are already a dozen MCP static scanners — they read a server's tool definitions once and flag injection strings. But the real damage in agentic systems is emergent across calls: read a secret → POST it to a URL → delete the log. Each call looks fine alone. No open-source tool sequences the calls and flags the pattern. Sentinel does.

It also closes the rug-pull gap: a server passes review, then silently mutates its tool descriptions after install so the agent re-reads poisoned instructions next session. Sentinel cryptographically pins every tool definition and flags any post-approval change.

Related MCP server: MCP Splunk

Install

pip install mcp-sentinel          # zero-dependency core (CLI)
pip install "mcp-sentinel[server]"  # + the MCP-server entrypoint

Use

1. Pin a server's tools, then detect rug-pulls

sentinel pin examples/tools.json --lock sentinel.lock   # trust on first use
sentinel verify examples/tools.json --lock sentinel.lock # later sessions
# DRIFT [mutated] get_weather   *** RUG-PULL SUSPECT ***   (exit 1)

2. Analyze a recorded call-chain

sentinel analyze examples/chain_exfil.json
# [HIGH  ] SENT001  Data read by 'read_file' (seq 0) flows into network tool 'http_post' (seq 1) - possible exfiltration.
# [HIGH  ] SENT002  Destructive tool 'delete_file' (seq 2) runs after read 'read_file' (seq 0) across a server boundary - read-then-destroy pattern.

3. Grade it (CI gate — exit 0 for A/B, 1 otherwise)

sentinel grade examples/chain_exfil.json
# GRADE D  (50/100)  findings=2 drifts=0   (exit 1)

4. As an MCP server (agents self-audit)

sentinel-mcp     # exposes analyze_chain, check_drift, grade_server

Built-in anomaly rules

Rules are plain functions (CallChain) -> list[Finding]; add your own by passing them to AnomalyEngine(rules=[...]).

Design

agent ──calls──> [ Sentinel ] ──forwards──> target MCP server
                     │
                     ├─ pin tool defs on first connect (sentinel.lock)
                     ├─ record every call into a CallChain
                     └─ run anomaly rules + grade

Capability tags (read / write / network / destructive) drive the rules. They come from MCP tool annotations (readOnlyHint, destructiveHint) and fall back to name/description heuristics when a server omits them — which most do.

Status

v0.1 — pinning, the three anomaly rules above, grading, CLI, and the MCP-server interface are implemented and tested. The transparent stdio proxy that records a live chain automatically is on the roadmap (today you feed it a recorded chain or wire CallChain.record() into your client).

License

MIT © Antonio Delgado