mcp-seatbelt

# MCP Seatbelt — Runtime Guardrails for AI Agent Tools

**Block dangerous MCP tool calls at the protocol layer. Scan, proxy, enforce.**

[![CI](https://github.com/KryptosAI/mcp-seatbelt/actions/workflows/mcp-seatbelt.yml/badge.svg)](https://github.com/KryptosAI/mcp-seatbelt/actions/workflows/mcp-seatbelt.yml)
[![npm version](https://img.shields.io/npm/v/@kryptosai/mcp-seatbelt?color=blue)](https://www.npmjs.com/package/@kryptosai/mcp-seatbelt)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
[![Node: ≥22](https://img.shields.io/badge/node-%E2%89%A522-339933)](https://nodejs.org)
[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg)](#contributors)
[![Tests](https://img.shields.io/badge/tests-485-brightgreen)]()
[![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fkryptosai%2Fmcp--seatbelt-blue)](https://github.com/KryptosAI/mcp-seatbelt/pkgs/container/mcp-seatbelt)
[![OWASP LLM](https://img.shields.io/badge/OWASP_LLM-Top_10-purple)]()
[![RBAC](https://img.shields.io/badge/RBAC-casbin-orange)]()

> **Part of the MCP Security Platform.** Scan before you trust with [mcp-observatory](https://github.com/KryptosAI/mcp-observatory) (236★), then enforce at runtime with mcp-seatbelt. 📄 [Read the technical whitepaper](marketing/whitepaper.md).

🌐 **Website:** [kryptosai.github.io/mcp-seatbelt](https://kryptosai.github.io/mcp-seatbelt/) — demo, comparison, pricing

<img src="docs/demo.gif" alt="MCP Seatbelt demo" width="700"/>

<!-- ![Demo](docs/demo.gif) -->

---

## The Problem

AI coding agents (Cursor, Claude, VS Code, ChatGPT, Windsurf, and others) connect to MCP servers that expose file systems, shell interpreters, network access, and environment variables. Static scanners tell you you're exposed — but they act after the fact. By the time a scanner flags a risky server, the agent may have already run a destructive command, exfiltrated credentials, or reached out to an untrusted endpoint.

**MCP Seatbelt adds a runtime enforcement layer.** It acts as a policy proxy between the agent and every MCP server, evaluating each JSON-RPC tool call against rules you control and denying dangerous requests before they reach the upstream. It does not operate at the TCP level — it inspects and gate-checks every call at L7 (the MCP protocol layer) before forwarding.

---

## What It Does

### Detection & Proxy

- **Detects MCP configs across 8 clients** — Automatically discovers MCP server configurations from Cursor, Claude Desktop, VS Code (user + workspace), ChatGPT Desktop, Codex, JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.), Windsurf, and project-local files (`.mcp.json`, `.mcp/config.json`). No manual wiring required.

- **Runtime proxy with policy enforcement** — Starts a transparent JSON-RPC 2.0 proxy on port 9420. Every tool call, resource access, and prompt request is intercepted, evaluated against your policy, and allowed, denied, warned, or redacted. Three modes: `default-deny` (zero-trust), `allowlist` (whitelist known-good), and `audit` (log only, no blocking).

- **13 built-in risk rules** — Covers shell interpreters (`bash`, `sh`, `zsh`, `python`, `node`), sandbox bypass (`--no-sandbox`, `--disable-web-security`), credential exposure in environment variables, Docker privileged containers, raw network tools (`curl`, `nc`, `telnet`), process spawning, destructive filesystem operations, remote URL access, risky package runners (`npx`, `uvx`), privilege escalation (`sudo`, `chmod`), and sensitive filesystem paths.

- **Policy engine with time-windowed rules, learning mode, rule inheritance, and context awareness** — Rules support regex pattern matching, exact-match, and substring containment. Restrict tool access by day of week and hour range (`timeWindow`). Condition rules on client identity or request rate (`contextCondition`). Policies can `extend` parent templates. The `audit` mode serves as a learning mode: run it to observe actual tool usage before switching to `enforce`.

- **Live dashboard, SARIF reports, CI/CD integration, and observatory bridge** — A real-time HTML dashboard shows request stats, block rates, connected clients, and recent blocked calls. Generate SARIF 2.1.0 reports for GitHub Code Scanning. Import security findings from [mcp-observatory](https://github.com/KryptosAI/mcp-observatory) and automatically convert them to policy rules. `mcp-seatbelt check` exits non-zero in CI when critical risks are detected.

- **Per-call timeouts** — Hung tool calls are killed and return a clean JSON-RPC error instead of a raw 503. Configurable per-rule (10s for shell commands, 60s for safe tools).

### Advanced Security

- **OWASP LLM Top 10 mapping** — Every blocked call is tagged with OWASP categories (LLM01 Prompt Injection, LLM06 Excessive Agency, etc.)
- **Compliance framework mapping** — Policy rules carry SOC2, HIPAA, GDPR, ISO 27001, and PCI-DSS control tags
- **Multi-step attack chain detection** — XState-based state machine tracks call sequences: recon → execution → persistence → exfiltration
- **Honeytoken injection & detection** — Plants decoy credentials (AWS keys, GitHub tokens, DB URLs) in tool responses, alerts on access
- **Forensic session capture** — Records full request/response pairs as `.mcpcap.json` for incident analysis
- **Schema-aware argument validation** — Validates tool arguments against declared JSON Schemas, detects path traversal and injection
- **Threat intelligence integration** — Queries ThreatFox IOC database for IP/domain reputation checks
- **Input fuzzing** — Generates edge-case payloads against policy rules to find bypasses
- **Role-based access control** — Per-agent permissions with casbin. Admin can execute all tools, agents get scoped access
- **Response DLP** — Scans upstream responses for secret patterns (API keys, tokens, private keys) and redacts them

---

## Quick Start

```bash
npm install -g @kryptosai/mcp-seatbelt  # or: brew install mcp-seatbelt
npx @kryptosai/mcp-seatbelt init        # scan all clients, assess risk, generate policy
npx mcp-seatbelt proxy         # start the enforcing proxy on port 9420
npx mcp-seatbelt dashboard     # view live stats at http://localhost:9421
```

On first run, `init` creates `.mcp-seatbelt/policy.yml` (your editable ruleset) and `.mcp-seatbelt/risk-report.md` (a summary of every server and its risk flags). The proxy starts in `audit` mode by default — observe actual tool usage, then switch to `enforce` when ready.

```bash
mcp-seatbelt fuzz --policy .mcp-seatbelt/policy.yml --iterations 200    # find policy bypasses
mcp-seatbelt record --output .mcp-seatbelt/sessions                      # forensic recording mode
mcp-seatbelt rbac-init -o .mcp-seatbelt                                  # init RBAC model + policy files
```

### Docker

Images are automatically built and published on every release via GitHub Actions.

```bash
docker run -p 9420:9420 -v $(pwd)/.mcp-seatbelt:/app/.mcp-seatbelt ghcr.io/kryptosai/mcp-seatbelt:latest proxy
```

### GitHub Action

Run MCP Seatbelt as a CI security gate with the official GitHub Action — it checks detected MCP configs, simulates your policy against representative tool calls, and fails the build on critical risks.

#### CI/CD Integration

```yaml
- uses: KryptosAI/mcp-seatbelt@v0.4
  with:
    mode: enforce
    fail-on-critical: true
```

See [action.yml](./action.yml) for all inputs, outputs, and enforcement options.

---

## How It Works

```
┌─────────┐     JSON-RPC 2.0     ┌────────────────────────────────────┐     JSON-RPC 2.0     ┌─────────────┐
│  Agent  │ ────────────────────▶ │         MCP Seatbelt Proxy        │ ────────────────────▶ │  MCP Server │
│ (Cursor) │                      │          (localhost:9420)          │                       │  (filesystem)│
└─────────┘                      │                                    │                      └─────────────┘
                                 │  ┌──────────────┐  ┌───────────┐  │
                                 │  │ Policy Engine│──│Interceptor │  │
                                 │  │   ┌───────┐  │  │  ┌──────┐ │  │
                                 │  │   │ Rules  │  │  │  │Allow?│ │  │
                                 │  │   │Allowlist│  │  │  │Deny? │ │  │
                                 │  │   │Templates│  │  │  │Redact│ │  │
                                 │  │   │TimeWin │  │  │  │Warn? │ │  │
                                 │  │   └───────┘  │  │  └──────┘ │  │
                                 │  └──────────────┘  └─────┬─────┘  │
                                 │                          │        │
                                 │                    ┌─────▼─────┐  │
                                 │                    │ Transport │  │
                                 │                    │  Client   │  │
                                 │                    └───────────┘  │
                                 └────────────────────────────────────┘
```

- **Proxy** — Listens for inbound JSON-RPC 2.0 requests from the AI agent. Manages server registration, proxied URL routing, and connection lifecycle.
- **Policy Engine** — Evaluates each request against the loaded policy. Checks tool name, arguments, and description against rules. Returns `allow`, `deny`, `warn`, or `redact` with reasons.
- **Interceptor** — Applies the engine's decision. Allowed calls are forwarded. Denied calls receive an MCP error response. Warned calls proceed but are logged. `redact` replaces argument values matching credential patterns with `***`.
- **Transport Client** — Forwards allowed requests to the real upstream MCP server and streams responses back to the agent.

The proxy never returns a raw upstream error to the agent. If a call exceeds its timeout, the child process is killed and the agent receives a clean error message — no 503s, no hanging connections.

Every request flows through an **11-stage pipeline**: RBAC → Schema Validation → Path Safety → Policy Engi