MCP-Sentinel

A safety check for AI assistants. When an AI assistant tries to do something on your behalf — read a file, run a database query, send data somewhere — MCP-Sentinel inspects that action first and says SAFE, SUSPICIOUS, or BLOCK, and explains why in plain terms.

The problem it solves

Modern AI assistants (like Claude or Cursor) can now take real actions through connectors called MCP servers — touching your files, databases, and accounts. That's powerful, but almost nothing checks whether an action is actually safe.

In 2026 attackers started abusing exactly this: hiding secret commands inside tools, tricking assistants into leaking sensitive data, and exploiting MCP servers that ship with no security. These attacks often look completely normal — each step is allowed, but together they add up to something harmful.

MCP-Sentinel is the missing guard that sits in the middle and checks every action before it runs.

Related MCP server: Carapace MCP Server

What makes it different

• It catches brand-new attacks, not just known ones. Most tools only recognize attacks they've seen before. MCP-Sentinel also spots never-before-seen ("zero-day") attacks by watching how an action behaves.

• It always explains itself. Every decision comes with the exact reason and evidence — not just a number — so you can trust and verify it.

• It runs anywhere. Fully self-contained, works offline with free local AI models, and plugs directly into AI assistants like Claude Desktop.

How it works — two "brains"

• Brain 1 (the memory): compares the action against a library of known attacks, kept fresh from real threat-intelligence feeds.

• Brain 2 (the detective): watches how the action behaves — what it touches, when, where it sends data — to catch suspicious patterns even if it's never seen them.

• The referee: runs both brains, always sides with the more cautious one (so nothing slips through), and sends genuinely unclear cases to a human.

flowchart TD
    A["AI assistant tries an action"] --> B["MCP-Sentinel"]
    B --> C["Brain 1: known attacks"]
    B --> D["Brain 2: behavior / zero-days"]
    E["Live threat feeds"] --> C
    C --> F["Referee: pick the more cautious verdict"]
    D --> F
    F --> G{"Result"}
    G -->|SAFE| H["Allow it"]
    G -->|BLOCK| I["Stop it + alert you"]
    G -->|SUSPICIOUS| J["Ask a human"]

What it's built with

• Python — the whole tool

• ChromaDB — stores the threat-intelligence library

• OpenAI or Ollama — the AI models (Ollama is free and runs on your own computer)

• FastMCP — turns it into an MCP server any AI assistant can call

• FastAPI — the simple web page for testing

• Threat intelligence — CISA KEV, MITRE ATLAS, OWASP LLM Top 10, and curated attack patterns

• MITRE ATT&CK — every verdict is mapped to a recognized attack technique

How to install and use it

You'll need Python installed. Each line below is a command you run in a terminal.

1. Download it and set it up:

git clone https://github.com/roshini111/MCP-vulnerability-detection.git
cd MCP-vulnerability-detection
python -m venv venv
source venv/bin/activate          # on Windows use:  venv\Scripts\activate
pip install -r requirements.txt

2. Choose how it runs the AI (or skip — it still works with a safe fallback):

• Free, on your own computer: install Ollama, then in a file called .env set EMBEDDING_PROVIDER=ollama.

• Using OpenAI: copy .env.example to .env and paste your OPENAI_API_KEY into it.

3. Try it — three ways:

python -m src.webapp          # opens a web page at http://localhost:8000 — paste an action, click Scan
python app.py --file call.json   # check a single action from a file
python src/mcp_server.py         # run it as an MCP server for an AI assistant to call

Connect it to your AI assistant (Claude Desktop)

This makes MCP-Sentinel protect you in every Claude chat automatically.

1. Generate the setup snippet:

python scripts/generate_claude_desktop_config.py

2. Copy the snippet it prints into Claude Desktop's config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Fully quit and reopen Claude Desktop. Now you can ask Claude to check any action, and you'll get a desktop pop-up if something's dangerous (turn alerts on with NOTIFY_ON=block,suspicious).

Making it enterprise-ready

MCP-Sentinel is a learning/prototype tool. To run it as real company infrastructure, you'd add:

• Automatic inline checking — route every action through it, not one at a time.

• Smarter baselines — learn each AI agent's normal behavior from real traffic to reduce false alarms.

• SIEM/SOAR integration — send alerts to enterprise security tools (Splunk, Microsoft Sentinel) and trigger automatic responses.

• A central dashboard with user roles and full audit logs — a real security operations view.

• More threat feeds — add paid or dark-web intelligence sources for deeper coverage.

• High availability — run it with redundancy and speed guarantees for production.

Note: MCP-Sentinel is a teaching/prototype project, not a production-grade defense. Real deployments should pair it with proper authentication, logging, and human review.