mcp-seatbelt
About
Runtime guardrails for AI agent MCP tools. Blocks dangerous tool calls at runtime with a default-deny policy proxy.
Details
- Author
- kryptosai
- Categories
- Developer Tools
Jump to
Setup
Install mcp-seatbelt in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/kryptosai/mcp-seatbelt
Follow the installation instructions in the repository README, then restart your MCP client.
MCP Seatbelt — Runtime Guardrails for AI Agent Tools
Block dangerous MCP tool calls at the protocol layer. Scan, proxy, enforce.
Part of the MCP Security Platform.Scan before you trust withmcp-observatory(236★), then enforce at runtime with mcp-seatbelt. 📄Read the technical whitepaper.
🌐Website:kryptosai.github.io/mcp-seatbelt— demo, comparison, pricing
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.
-
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), andaudit(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 canextendparent templates. Theauditmode serves as a learning mode: run it to observe actual tool usage before switching toenforce.
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 frommcp-observatoryand automatically convert them to policy rules.mcp-seatbelt checkexits 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).
- 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.jsonfor 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
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,initcreates.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 inauditmode by default — observe actual tool usage, then switch toenforcewhen ready.
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
Images are automatically built and published on every release via GitHub Actions.
docker run -p 9420:9420 -v $(pwd)/.mcp-seatbelt:/app/.mcp-seatbelt ghcr.io/kryptosai/mcp-seatbelt:latest proxy
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.
- uses: KryptosAI/mcp-seatbelt@v0.4 with: mode: enforce fail-on-critical: true
Seeaction.ymlfor all inputs, outputs, and enforcement options.
┌─────────┐ 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. Returnsallow,deny,warn, orredactwith reasons.
- Interceptor— Applies the engine's decision. Allowed calls are forwarded. Denied calls receive an MCP error response. Warned calls proceed but are logged.redactreplaces 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 an11-stage pipeline: RBAC → Schema Validation → Path Safety → Policy Engine → Threat Intel → Honeytokens → Attack Chains → Proxy → Response DLP → Forensics → Audit Log.
| Feature | mcp-seatbelt | mcp-firewall | mcp-guardian | Prismor | mcp-proxy | |---|---|---|---|---|---|---| | Runtime blocking | ✓ | ✓ | ✓ | ✓ | ✗ | | Pre-install scanning | ✓ | ✗ | ✗ | ✗ | ✗ | | 8+ client detection | ✓ | ✗ | ✗ | ✗ | ✗ | | Argument redaction | ✓ | ✗ | ✗ | ✗ | ✗ | | Learning mode | ✓ | ✗ | ✗ | ✗ | ✗ | | Live dashboard | ✓ | ✗ | ✓ | ✗ | ✗ | | SARIF / GitHub Code Scanning | ✓ | ✗ | ✗ | ✗ | ✗ | | mcp-observatory integration | ✓ | ✗ | ✗ | ✗ | ✗ | | Per-call timeouts | ✓ | ✗ | ✗ | ✗ | ✗ | | OWASP LLM Top 10 mapping | ✓ | ✗ | ✗ | ✗ | ✗ | | Compliance tagging (SOC2/HIPAA) | ✓ | ✗ | ✗ | ✗ | ✗ | | Attack chain detection | ✓ | ✗ | ✗ | ✗ | ✗ | | Honeytoken/injection detection | ✓ | ✗ | ✗ | ✗ | ✗ | | Schema-aware validation | ✓ | ✗ | ✗ | ✗ | ✗ | | Threat intel (IOC lookup) | ✓ | ✗ | ✗ | ✗ | ✗ | | RBAC (per-agent access) | ✓ | ✗ | ✗ | ✗ | ✗ |
Seatbelt is the only tool that combines pre-install scanning with runtime enforcement, covers all major AI agent clients, redacts credential arguments inline, and bridges static analysis results from mcp-observatory into live policy rules.
mcp-seatbelt includes a defense-in-depth security pipeline that evaluates every tool call through multiple layers:
mcp-seatbelt fuzzgenerates randomized tool call arguments usingjson-schema-faker, injects edge-case payloads (path traversal, command injection, SQL injection, Log4Shell), and evaluates each payload against your policy. Bypasses are reported with the specific payload and rule that should have blocked them.
mcp-seatbelt fuzz --policy .mcp-seatbelt/policy.yml --iterations 200 --json
mcp-seatbelt init --policy enforce # generate an enforcing policy mcp-seatbelt proxy --config my.yml # start proxy with custom policy mcp-seatbelt report --sarif # SARIF 2.1.0 output for CI mcp-seatbelt check # exit 1 if critical risks found mcp-seatbelt diff old.yml new.yml # compare two policy files mcp-seatbelt import-observatory # convert observatory findings to rules
Templates can be extended via theextendsfield in your policy file:
version: '1' mode: enforce extends: - pci-compliance rules: - id: custom-rule target: network match: pattern values: ['.'] action: deny
rules: - id: example-rule # unique identifier description: What this blocks # human-readable explanation target: command # command | file | network | env | process match: pattern # exact | pattern | contains values: # list of strings or regex patterns - '^rm\s+-rf' action: deny # allow | deny | warn | redact timeWindow: # optional — restrict by day/hour days: [Monday, Tuesday, Wednesday, Thursday, Friday] startHour: 9 endHour: 17 contextCondition: # optional — restrict by client or rate clientIn: [cursor, claude-desktop] maxRequestsPerMinute: 60
Entries in the allowlist bypass all deny rules. Use after runninginitto whitelist known-good tools, paths, hosts, and environment variables:
allowlist: tools: [safe-tool, read-only-fs] paths: [/home/user/projects/] hosts: [api.github.com] envVars: [NODE_ENV, PATH]
After starting the proxy, update each client's MCP configuration to route throughlocalhost:9420. The proxy prints a table of proxy URLs on startup — copy and paste them.
{ "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } }
Claude Desktop—~/Library/Application Support/Claude/claude_desktop_config.json
{ "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } }
VS Code—.vscode/mcp.jsonor User settings
{ "servers": { "my-server": { "url": "http://localhost:9420/my-server" } } }
{ "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } }
Codex / JetBrains / Windsurf— Same pattern: replace thecommand/argstransport with"url": "http://localhost:9420/<server-name>".
The observatory bridge (mergeObservatoryPolicy) can merge findings into an existing seatbelt policy without overwriting your custom rules.
Measured on Apple M3, Node.js 22, macOS — 1,000 requests at concurrency 10 against an instant-response upstream (median of 3 runs, zero failed requests):
Policy size (1 → 20 rules) has no measurable end-to-end impact; per-rule cost is ~0.25 µs, far below transport I/O. Full methodology and per-scenario tables:docs/benchmarks.md. Runmcp-seatbelt benchmarkon your own hardware.
- Observatory Cloud: hosted scanning, private registries, team dashboards
- Seatbelt: on-machine proxy with policy enforcement, redaction, and live monitoring
- Together: scan at rest + enforce at runtime = complete MCP security lifecycle
- Multi-client detection (8 clients)
- Runtime JSON-RPC 2.0 proxy with request interception
- Policy engine with regex/exact/contains matching, time windows, context conditions
- Risk assessment engine (13 rules)
- Live dashboard web UI with auto-refresh
- SARIF 2.1.0 and markdown report generation
- mcp-observatory integration bridge
- CI/CD check command (mcp-seatbelt check)
- OWASP LLM Top 10 mapping and compliance framework tagging
- Multi-step attack chain detection (XState state machine)
- Honeytoken injection and detection
- Forensic session capture (.mcpcap.json)
- Schema-aware argument validation
- Threat intelligence integration (ThreatFox IOC lookup)
- Input fuzzing against policy rules
- Role-based access control (casbin RBAC)
- Policy diff and migration tooling (#12)
- Prometheus/metricsendpoint for observability stacks (#15)
- OPA/Rego policy integration (#18)
- Per-tool granularity — allow tool A but deny tool B on the same server (#20)
- Persistent audit trail and request logging with SQLite (#22)
- Plugin system for custom risk rules (#25)
SeeCONTRIBUTING.mdfor development setup, testing instructions, and pull request guidelines. Security issues should follow the process inSECURITY.md.
- 485 tests**across 18 test suites (CLI, detectors, policy engine, proxy server, proxy interception, reports, security modules, RBAC, threat intel, LLM judge, forensics, honeytokens, attack chains, schema validator, audit, notifications, baseline, integration)
- npm testruns the full Vitest suite;npm run typecheckverifies TypeScript
- PRs should include tests for new rules, detectors, or policy features
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
Create crafted UI components inspired by the best 21st.dev design engineers.
Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server
An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .
MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent
ALAPI MCP Tools,Call hundreds of API interfaces via MCP
AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform
MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references.
APIMatic MCP Server is used to validate OpenAPI specifications using APIMatic. The server processes OpenAPI files and returns validation summaries by leveraging APIMatic’s API.
One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.
Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
