mcp-guardrails-kit
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-guardrails-kit Triage ticket 1234 and flag any injection risks."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-guardrails-kit
A prompt-injection-aware tool gateway and MCP server, built as a reference implementation for a fictional internal ticket-triage assistant.
This is a portfolio project, not a real product. It exists to demonstrate a concrete, testable pattern for building guardrails around agentic tool use — permission tiers, untrusted-content quarantine, and heuristic injection detection — around a small but real MCP server. The domain (support ticket triage) is generic and interchangeable; the guardrail patterns are the point.
What it demonstrates
Tool permission tiers with explicit confirmation. Every tool is registered as either
read_onlyorsensitive. Sensitive tools (draft_reply,escalate_ticket) never execute a side effect until the caller passesconfirmed=True— every caller in this codebase routes through the gateway's singleinvoke()entry point by construction (seedocs/adr/0001-tool-permission-tiers.mdfor the honest caveat: this is a code-review convention, not a language-enforced boundary).Quarantine of untrusted external content.
fetch_external_pagereturns content fetched from a URL linked inside a ticket — a realistic prompt-injection vector. That content is wrapped and clearly delimited as data, never treated as instructions, before it is handed back to any caller or model.Heuristic injection detection with a verdict. Quarantined (and other) text is scanned for injection patterns and returns one of
ALLOW/FLAG/BLOCK. ABLOCKverdict replaces the payload with a safe refusal instead of the raw text (never a verbatim excerpt — even the scan's ownmatched_patternsare redacted to category labels before crossing a tool boundary). This is backed by a red-team test suite of known injection phrasings.Three independent scan gates, not just one. A
Supervisorwalks a triage → draft → review → escalate pipeline. A ticket's own subject/body — the most directly attacker-controlled input in the system — is scanned right after lookup; the drafted reply is re-scanned before escalation is considered; and the escalationreasona model proposes is scanned again beforeescalate_ticketis ever called. ABLOCKat any of the three halts the pipeline right there.
Related MCP server: production-grade-mcp-agentic-system
Install & run
pip install -e ".[dev]"
pytest
ruff check .No external services or API keys are required to install, test, or lint. See
Scope & non-goals below for what pip install -e ".[live]" adds.
Connecting the MCP server to a real client
After pip install -e . (or pip install mcp-guardrails-kit once published), the
mcp-guardrails-kit command is registered as a console entry point
(see [project.scripts] in pyproject.toml) and speaks the MCP stdio protocol. Point a
real MCP client at it — for example, Claude Desktop or Claude Code — with a config block
like:
{
"mcpServers": {
"guardrails-kit": {
"command": "mcp-guardrails-kit"
}
}
}For Claude Desktop, this goes in claude_desktop_config.json; for Claude Code, add it via
claude mcp add or the equivalent project-level MCP config. No arguments or environment
variables are required for the default (non-live) mode.
Scope & non-goals
Heuristic injection detection is defense in depth, not a guarantee. It is a regex/keyword-based scanner, not a model-backed classifier. It will miss novel or sufficiently obfuscated phrasings — see
docs/adr/0003-heuristic-injection-detection.mdfor the explicit tradeoff. The permission-tier and quarantine layers stay in effect even when detection fails; injection detection is one layer among three, not the only one.There is no real ticketing system behind this.
search_knowledge_baseandlookup_ticketread from small in-memory fixtures. There is no database, no external ticketing API integration, and no persistence.AnthropicModelClientis optional and live-only. It is gated behind theliveextra (pip install -e ".[live]") and is never imported or exercised by the test suite or CI — tests and the default install path have zero dependency on any external LLM API or network access.All data is in-memory and resets on restart. Drafts, escalations, and fetched external content are not persisted anywhere; restarting the server clears all state.
More
Architecture and data flow:
docs/architecture.mdDesign decisions:
docs/adr/
Available Tools
5 toolsdraft_replyA
Draft a reply to a customer for the given ticket. SENSITIVE: call with confirmed=false first (the default) to preview — this creates no draft and returns confirmation_required=True. Only a subsequent call with confirmed=true actually creates the draft.
Inputs: ticket_id (required), draft_body (required), confirmed. Returns: ok, data, scan, tool_name, +2 more
escalate_ticketA
Escalate a ticket to a human agent for the given reason. SENSITIVE: call with confirmed=false first (the default) to preview — this escalates nothing and returns confirmation_required=True. Only a subsequent call with confirmed=true actually escalates.
Inputs: reason (required), ticket_id (required), confirmed. Returns: ok, data, scan, tool_name, +2 more
fetch_external_pageARead-onlyIdempotent
Fetch a web page linked from a ticket. The content is untrusted: it is quarantined and scanned for prompt-injection attempts before being returned, and may be blocked outright if it matches a known injection pattern.
Inputs: url (required). Returns: ok, data, scan, tool_name, +2 more
lookup_ticketARead-onlyIdempotent
Look up a support ticket by its id.
Inputs: ticket_id (required). Returns: ok, data, scan, tool_name, +2 more
search_knowledge_baseARead-onlyIdempotent
Search the internal support knowledge base for articles matching a query.
Inputs: query (required). Returns: ok, data, scan, tool_name, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct, non-overlapping purpose: search knowledge base, lookup ticket, fetch external page (with security features), draft reply, and escalate ticket. No ambiguity between them.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., search_knowledge_base, lookup_ticket, fetch_external_page, draft_reply, escalate_ticket). The convention is uniform and predictable.
Five tools is a well-scoped set for a guardrails kit focused on support workflows. Each tool serves a clear function, and there is no bloat or insufficiency given the narrow domain.
The tool surface covers the main support workflow: search, lookup, secure fetching, drafting replies, and escalation. Minor gaps exist (e.g., no tool to update ticket status or send replies), but these are not critical to the stated guardrails purpose.
Maintenance
Related MCP Connectors
Real-time MCP & A2A prompt-injection, jailbreak, and tool-schema poisoning firewall for AI agents.
AgentGuard — 20-tool AI safety MCP: policy preflight, risk scoring, audit logging, rate limits.
Safety tools for AI agents: safe page reader, prompt-injection, secrets, PII and MCP server scans
Security scanner for AI agents and MCP servers: injection, jailbreak, tool abuse.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server that provides safeguard capabilities to protect against prompt injection and unsafe tool calls.750 PyPI11MIT
- AlicenseNot gradedqualityDmaintenanceA production-grade MCP server designed for multi-tenant, authenticated, and observable AI agent systems, enabling secure tool execution across heterogeneous data sources.68MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that provides tools to scan text and URLs for prompt injection attacks, protecting AI agents from adversarial inputs.1MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server for prompt injection boundary enforcement that scans URL content using a tiered LLM model strategy.-