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.

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.