# 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.

```mermaid
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](https://www.python.org/downloads/) installed. Each line below is a command you run in a terminal.*

**1. Download it and set it up:**

```bash
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](https://ollama.com), 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:**

```bash
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:

```bash
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.