MCP-Bastion
Security middleware for MCP. Blocks prompt injection, PII leakage, and resource exhaustion.
Ask AI about MCP-Bastion
Powered by Claude · Grounded in docs
I know everything about MCP-Bastion. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP-Bastion
Enterprise-Grade Security Middleware for the Model Context Protocol
Releases are published to npm and PyPI via GitHub Actions on tag push.
The Model Context Protocol (MCP) has rapidly become the universally accepted standard for connecting AI agents to enterprise databases and APIs. However, this connectivity introduces a massive new attack surface: unpredictable, non-deterministic agentic behavior.
MCP-Bastion is a lightweight, drop-in security middleware designed to wrap around any existing Python or TypeScript MCP server. Instead of relying on passive logging, human-in-the-loop approvals, or third-party APIs, MCP-Bastion provides an active, 100% local defense layer. It intercepts standard JSON-RPC traffic to stop threats before they cross the enterprise boundary.
Under 5ms proxy overhead. MCP-Bastion provides:
- Prompt Injection Defense: Meta PromptGuard runs locally to block adversarial payloads and jailbreaks.
- PII Redaction: Uses Microsoft Presidio to detect and mask PII before it reaches the LLM context.
- Infinite Loop Protection: Token buckets and cycle detection stop runaway agents from burning API budget.
Secure your MCP server without changing business logic.
Core Features
Zero-Click Prompt Injection Prevention
Integrates Meta's PromptGuard model locally to detect and block malicious payloads, jailbreaks, and adversarial tokenization before they reach your external tools.
PII Redaction
Microsoft Presidio scans outbound tool results and masks PII (redaction, substitution, generalization).
Infinite Loop and Denial of Wallet Protection
Implements stateful cycle detection and configurable FinOps token-bucket algorithms to automatically terminate runaway agents and prevent massive API bill overruns.
100% Local Execution (Data Privacy)
All security classification and data redaction happen entirely within the local memory space of your server. Sensitive data never leaves your enterprise network for third-party safety evaluations.
Low Latency
Drop-in middleware, under 5ms overhead.
Framework Integration
Hooks into MCP SDKs (TypeScript, Python) and FastMCP via standard middleware. No business logic changes.
Complete feature catalog
Deeper context: docs/SECURITY_OBSERVABILITY.md — OWASP MCP Top 10 alignment, attack scenarios, and SIEM/log integrations. Framework add-ons (LangChain, OpenAI, Bedrock, …) are listed under Framework Integrations below.
Threat prevention & content safety
| Feature | What you get |
|---|---|
| Prompt injection defense | Meta PromptGuard scores tool arguments; malicious / jailbreak-style payloads can be blocked before execution (local inference, no third-party API). |
| Content filter | Block shell/code execution patterns, sensitive file paths, and URLs; optional allowlist / denylist regex or substring rules. |
| PII redaction | Microsoft Presidio detects many entity types in outbound tool/resource text (SSN, email, phone, cards, passport, IBAN, licenses, etc.—see Presidio docs). |
Access control, integrity & abuse
| Feature | What you get |
|---|---|
| RBAC | Tool-level allow/deny by role (from request metadata); map roles to tool names in bastion.yaml. |
| Schema validation | Validate tools/call arguments against JSON Schema before the tool runs (block malformed or bypass attempts). |
| Replay guard | Nonce tracking to reject replayed requests (configurable require_nonce). |
| Rate limiting | Token-bucket style limits: max iterations per session, timeout, token budget—stops runaway loops and brute-force patterns. |
| Circuit breaker | Stop calling tools that fail repeatedly (limits blast radius of bad upstreams or poisoned tools). |
FinOps & performance
| Feature | What you get |
|---|---|
| Cost tracker | Per-session and optional per-day USD caps; blocks when budget is exceeded. |
| Semantic cache | Optional similarity-based caching for tool semantics (reduce duplicate expensive calls). |
| Low overhead | Middleware on the hot path targeting <5 ms typical overhead (see docs/METRICS.md). |
Audit, metrics & alerting
| Feature | What you get |
|---|---|
| Audit logging | Structured allow/deny decisions with reason, tool, tenant_id, trace_id, request_id—feed SOC / compliance. |
| Alert sinks | Slack incoming webhook; generic HTTP webhooks (PagerDuty, Teams, custom APIs); multiple URLs; retry, backoff, timeout in bastion.yaml. |
| In-memory metrics | Global MetricsStore: requests, blocks, PII counts, cost, per-tool stats, latency samples, rolling time series buckets. |
| Real-time dashboard | Web UI with KPIs, traffic & block charts, blocked-by-reason/kind, top tools, cost by user, PII by entity, latency P50/P95/P99, forensics table (tenant filter, trace/replay helpers), recent alerts, insights & anomalies (heuristic signals), dark/light theme, Prometheus /metrics, JSON /api/metrics. |
| OpenTelemetry | Optional OTLP span export — pip install mcp-bastion-python[otel] — docs/OTEL.md. |
Policy, packaging & developer experience
| Feature | What you get |
|---|---|
| Policy-as-code | Single bastion.yaml: toggles and knobs for every pillar; load via load_config / build_middleware_from_config. |
| Hot reload | Optional reload bastion.yaml on change without restarting the MCP server (docs/POLICY_AS_CODE.md). |
| Composable middleware | compose_middleware ordering; MCPBastionMiddleware flags for each pillar. |
| CLI | mcp-bastion validate, serve (HTTP MCP), dashboard (optional --reload for UI dev) — docs/CLI.md. |
| Python + TypeScript | mcp-bastion-python on PyPI; @mcp-bastion/core on npm for TypeScript MCP servers (rate limits in-process; prompt/PII via optional sidecar). |
| Containers | Dockerfile, docker-compose profiles (proxy + optional dashboard) — DOCKER.md. |
Real-Time Dashboard and Alerts
Run the optional dashboard for a live view of requests, blocked count, PII redacted, cost, top tools, and recent alerts.
Demo (screen recording):
Open / download the demo (MP4) · in-repo: images/mcp-bastian-mp.mp4
Record shows live KPIs, charts, and theme. If the player is blank, open the link above (GitHub’s README view can be strict about media).
mcp-bastion dashboard --port 7000
# or: PYTHONPATH=src python dashboard/app.py
| URL | What it returns |
|---|---|
| http://localhost:7000/ | Charts, KPIs, forensics, insights & anomalies, alerts, tool drill-down (signal vs global block rate), theme toggle |
| http://localhost:7000/api/metrics | JSON: requests_total, blocked_total, blocked_pct, pii_redacted_total, cost_total, blocked_by_reason, blocked_by_kind, top_tools, tool_stats, cost_by_user, time_series, latency_ms, dashboard_insights, blocked_incidents, alerts, … |
| http://localhost:7000/api/health | {"status": "ok"} |
| http://localhost:7000/metrics | Prometheus text format for Grafana/Datadog |
Dashboard: total requests, blocked count and %, PII redacted, cost; blocked-by-reason bars; top tools; cost by user; recent alerts — open http://localhost:7000/ while mcp-bastion dashboard is running.
- Alerts: Slack webhook and cost-threshold alerts. See dashboard/README.md.
Documentation: Use Cases, Attacks, Metrics, Tutorials
| Doc | Description |
|---|---|
| docs/index.md | GitHub Pages-ready docs home |
| docs/DETAILED_TUTORIAL.md | Step-by-step implementation tutorial for new teams |
| docs/USE_CASES.md | Real use cases: enterprise gateway, LLM products, internal tools, SaaS, compliance |
| docs/ATTACK_PREVENTION.md | Examples showing how MCP-Bastion prevents real attacks (injection, PII leak, rate exhaustion, path traversal, RBAC, replay) |
| docs/REDTEAM.md | Interpreting harness / red-team scores; which bastion.yaml pillars to enable; Node vs Python parity |
| docs/SECURITY_OBSERVABILITY.md | OWASP MCP Top 10 mapping, feature highlights, attack classes, Slack/webhook/Prometheus/OTEL/log integrations |
| docs/METRICS.md | Performance overhead (<5ms) and effectiveness metrics (dashboard, Prometheus, OTEL) |
| docs/TUTORIALS.md | Tutorials: integrating with FastMCP, TypeScript, GitHub MCP, and open-source MCP servers |
| docs/GITHUB_PAGES.md | Publish docs as a GitHub Pages website from this same repo |
One-Line Docker
docker build -t mcp-bastion/proxy .
docker run -p 8080:8080 mcp-bastion/proxy
MCP endpoint: http://localhost:8080/mcp. Use docker-compose up -d for proxy; add --profile with-dashboard for the dashboard. See DOCKER.md.
Policy-as-Code (bastion.yaml)
Single config file controls all pillars. Copy bastion.yaml.example to bastion.yaml, then:
from mcp_bastion import build_middleware_from_config
middleware = build_middleware_from_config()
Tip: set hot_reload.enabled: true in bastion.yaml to apply policy changes without restarting your MCP server when using build_middleware_from_config().
CLI for developers
mcp-bastion validate # validate bastion.yaml
mcp-bastion serve --http 8080 # run MCP server with config
mcp-bastion dashboard --port 7000 # run metrics dashboard
See docs/CLI.md.
OpenTelemetry
Set OTEL_EXPORTER_OTLP_ENDPOINT to export tool-call spans to OTLP. Install optional deps: pip install mcp-bastion-python[otel]. See docs/OTEL.md.
Webhook alerts and external logging
Use Slack (slack_webhook / SLACK_WEBHOOK_URL), a generic HTTP webhook (webhook_url / BASTION_WEBHOOK_URL), or multiple URLs (alerts.webhooks in bastion.yaml). POSTs can drive PagerDuty, Microsoft Teams, Datadog Events, or any HTTP collector your SIEM exposes. Configure retry/backoff in bastion.yaml (retry_attempts, retry_backoff_seconds, retry_backoff_max_seconds, timeout_seconds).
Metrics & traces: scrape the dashboard /metrics (Prometheus) or poll /api/metrics (JSON) for Grafana, Datadog, or custom pollers. Set OTEL_EXPORTER_OTLP_ENDPOINT for traces to Jaeger, Honeycomb, AWS ADOT, etc. (pip install mcp-bastion-python[otel]). Route Python logs (including LoggingAlertSink) through Fluent Bit, Vector, or the CloudWatch agent into Splunk / Elastic / CloudWatch Logs.
See docs/SECURITY_OBSERVABILITY.md for the full integration table and OWASP MCP Top 10 alignment.
Why MCP-Bastion (Competitive Comparison)
Early security packages (mcp-guardian, mcp-shield) focus on logging or static scanning. MCP-Bastion adds an active defense layer.
1. Active Defense vs. Passive Logging
| The Competition | MCP-Bastion |
|---|---|
| Tools like mcp-guardian focus on tracing, logging, human-in-the-loop approvals. | Automated interception. MCP-Bastion scrubs PII before it leaves the server. |
2. Local Inference vs. Third-Party APIs
| The Competition | MCP-Bastion |
|---|---|
| Many guardrail proxies send prompts to external APIs to check for malice. | PromptGuard-86M and Presidio run locally. Data stays on your network. |
3. Stateful Denial of Wallet Protection
| The Competition | MCP-Bastion |
|---|---|
| Most tools focus on static vulns or basic rate limits. | Tracks tool call history per session. Stops runaway loops before they burn API budget. |
4. Drop-in Middleware vs. Standalone Gateway
| The Competition | MCP-Bastion |
|---|---|
| Some solutions need standalone proxy servers. | Library hooks into server.setRequestHandler (TS) or middleware (Python). No extra infra. |
Structure
| Path | Description |
|---|---|
src/mcp_bastion/ | Python package: PromptGuard, Presidio, rate limiting, RBAC, etc. |
packages/core/ | TypeScript package: rate limiting in-process; prompt/PII via sidecar (MCP_BASTION_URL) |
examples/ | Python examples (examples/README.md) |
dashboard/ | Real-time dashboard UI and metrics API (dashboard/README.md) |
bastion.yaml.example | Policy-as-code sample; copy to bastion.yaml (docs/POLICY_AS_CODE.md) |
scripts/validate_checklist.py | Enterprise validation runner |
VALIDATION_CHECKLIST.md | Validation guide and MCP Inspector steps |
SETUP_GUIDE.md | Setup, config, and validation |
DOCKER.md | Docker one-line run and compose |
Example Files
| File | Purpose |
|---|---|
examples/python_server_example.py | Minimal middleware chain |
examples/full_demo.py | All 11 features (rate limit, PII, RBAC, etc.) |
examples/llm_server.py | Shared MCP server for LLM clients |
examples/llm_openai_example.py | OpenAI |
examples/llm_claude_example.py | Claude |
examples/llm_gemini_example.py | Gemini |
examples/llm_mistral_example.py | Mistral |
examples/llm_grok_example.py | Grok (xAI) |
examples/server_with_config.py | Policy-as-code (bastion.yaml) |
Installation
Python
uv add mcp-bastion-python
# or
pip install mcp-bastion-python
# pinned latest
pip install mcp-bastion-python==1.0.15
Prerequisites (recommended)
- PII redaction: Presidio expects the spaCy English model. After install, run:
python -m spacy download en_core_web_sm
Without it, PII analysis can fail at runtime. - Policy-as-Code (
bastion.yaml): install YAML support:
pip install mcp-bastion-python[policy]
(addspyyaml; otherwise you may getImportErrorwhen loading policy files). - PromptGuard fail-open: if the PromptGuard model fails to load or inference errors, MCP-Bastion allows the request and logs a warning. Treat this as a security degradation and fix the model/runtime before production.
The PyPI wheel ships the full mcp_bastion tree (including config, cli, otel, dashboard metrics, and alert sinks). If you use an older wheel that omits modules, upgrade to the current release.
TypeScript
npm install @mcp-bastion/core
Framework Integrations
Drop-in security for your favorite LLM framework. Each package auto-installs mcp-bastion-python:
pip install mcp-bastion-langchain # LangChain agents and tools
pip install mcp-bastion-openai # OpenAI GPT API calls
pip install mcp-bastion-anthropic # Anthropic Claude API calls
pip install mcp-bastion-bedrock # AWS Bedrock runtime
pip install mcp-bastion-gemini # Google Gemini
pip install mcp-bastion-crewai # CrewAI agent crews
pip install mcp-bastion-llamaindex # LlamaIndex RAG pipelines
pip install mcp-bastion-groq # Groq inference
pip install mcp-bastion-mistral # Mistral AI
pip install mcp-bastion-cohere # Cohere
pip install mcp-bastion-azure # Azure OpenAI Service
pip install mcp-bastion-vertexai # Google Cloud Vertex AI
pip install mcp-bastion-huggingface # Hugging Face Inference
pip install mcp-bastion-deepseek # DeepSeek AI
pip install mcp-bastion-together # Together AI
pip install mcp-bastion-fireworks # Fireworks AI
pip install mcp-bastion-fastmcp # FastMCP servers
| Package | Protects | Version | Downloads |
|---|---|---|---|
| mcp-bastion-langchain | LangChain | 0.1.0 | stats |
| mcp-bastion-openai | OpenAI GPT | 0.1.0 | stats |
| mcp-bastion-anthropic | Anthropic Claude | 0.1.0 | stats |
| mcp-bastion-bedrock | AWS Bedrock | 0.1.0 | stats |
| mcp-bastion-gemini | Google Gemini | 0.1.0 | stats |
| mcp-bastion-crewai | CrewAI | 0.1.0 | stats |
| mcp-bastion-llamaindex | LlamaIndex | 0.1.0 | stats |
| mcp-bastion-groq | Groq | 0.1.0 | stats |
| mcp-bastion-mistral | Mistral AI | 0.1.0 | stats |
| mcp-bastion-cohere | Cohere | 0.1.0 | stats |
| mcp-bastion-azure | Azure OpenAI | 0.1.1 | stats |
| mcp-bastion-vertexai | Vertex AI | 0.1.0 | stats |
| mcp-bastion-huggingface | Hugging Face | 0.1.1 | stats |
| mcp-bastion-deepseek | DeepSeek AI | 0.1.1 | stats |
| mcp-bastion-together | Together AI | 0.1.1 | stats |
| mcp-bastion-fireworks | Fireworks AI | 0.1.1 | stats |
| mcp-bastion-fastmcp | FastMCP servers | 0.1.0 | stats |
Publish (PyPI / npm)
- PyPI:
python -m build && twine upload dist/*(or use GitHub Actions on tag). - npm: From repo root,
cd packages/core && npm publish --access public(or use Trusted Publishers). - Version is set in
pyproject.toml(Python),packages/core/package.json(npm), andserver.json(MCP registry). Bump before releasing.
Developer Guide
Integration examples for Python and TypeScript.
Quick Start (Python)
Add MCP-Bastion to an existing MCP server in three steps:
from mcp_bastion import MCPBastionMiddleware, compose_middleware
# 1. Create the security middleware
bastion = MCPBastionMiddleware(
enable_prompt_guard=True,
enable_pii_redaction=True,
enable_rate_limit=True,
)
# 2. Compose with your middleware chain (Bastion runs first)
middleware = compose_middleware(bastion)
# 3. Pass the composed middleware to your MCP server
# (integration depends on your server framework)
Examples:
| Example | Description |
|---|---|
examples/python_server_example.py | Basic middleware chain |
examples/full_demo.py | All features: add, PII, rate limit, prompt injection |
examples/llm_openai_example.py | MCP server for OpenAI |
examples/llm_claude_example.py | MCP server for Claude |
examples/llm_gemini_example.py | MCP server for Gemini |
examples/llm_mistral_example.py | MCP server for Mistral |
examples/llm_grok_example.py | MCP server for Grok (xAI, HTTP only) |
# Windows: $env:PYTHONPATH="src"; python examples/full_demo.py
# Linux/Mac: PYTHONPATH=src python examples/full_demo.py
LLM integration: See docs/LLM_INTEGRATION.md for copy-paste config for OpenAI, Claude, Gemini, Mistral, and Grok.
Enterprise validation:
PYTHONPATH=src python scripts/validate_checklist.py
See VALIDATION_CHECKLIST.md and SETUP_GUIDE.md.
Python Tutorial: FastMCP Server
FastMCP server with MCP-Bastion.
Step 1: Install dependencies
pip install mcp mcp-bastion-python
Step 2: Create your server file (server.py)
from mcp.server.fastmcp import FastMCP
from mcp_bastion import MCPBastionMiddleware, compose_middleware
# Create the MCP server
mcp = FastMCP("My Secure Server")
# Create MCP-Bastion middleware
# It intercepts tool calls and resource reads before they execute
bastion = MCPBastionMiddleware(
enable_prompt_guard=True, # Block malicious prompts via PromptGuard
enable_pii_redaction=True, # Mask PII in outgoing content
enable_rate_limit=True, # Cap at 15 iterations, 60s timeout
)
# Compose middleware chain (pass to your server's middleware config if supported)
middleware = compose_middleware(bastion)
# Register a tool (protected when middleware is wired into your server)
@mcp.tool()
def get_weather(city: str) -> str:
"""Get weather for a city."""
return f"Weather in {city}: 22C, sunny"
# Resource (PII redacted)
@mcp.resource("user://profile/{user_id}")
def get_profile(user_id: str) -> str:
"""Get user profile. PII redacted."""
return f"User {user_id}: John Doe, SSN 123-45-6789, john@example.com"
if __name__ == "__main__":
mcp.run(transport="streamable-http")
Step 3: Run the server
python server.py
MCP-Bastion:
- Scans tool args for prompt injection
- Redacts PII from resource responses
- Blocks sessions over 15 calls or 60s
Alternative: Policy-as-Code
Use bastion.yaml instead of code. Copy bastion.yaml.example to bastion.yaml, then:
from mcp_bastion import build_middleware_from_config
middleware = build_middleware_from_config()
See docs/POLICY_AS_CODE.md and examples/server_with_config.py.
Python: Custom Rate Limits
Custom config example:
from mcp_bastion import MCPBastionMiddleware
from mcp_bastion.pillars.rate_limit import TokenBucketRateLimiter
from mcp_bastion.pillars.prompt_guard import PromptGuardEngine
# Stricter limits
rate_limiter = TokenBucketRateLimiter(
max_iterations=10,
timeout_seconds=30,
token_budget=25_000,
)
# Higher threshold = fewer blocks, more risk
prompt_guard = PromptGuardEngine(threshold=0.92)
bastion = MCPBastionMiddleware(
prompt_guard=prompt_guard,
rate_limiter=rate_limiter,
enable_prompt_guard=True,
enable_pii_redaction=True,
enable_rate_limit=True,
)
# Disable PII redaction if your data has no PII
bastion_no_pii = MCPBastionMiddleware(enable_pii_redaction=False)
Python: Custom Middleware
Extend Middleware to add logging, metrics, or custom logic:
from mcp_bastion.base import Middleware, MiddlewareContext, compose_middleware
class LoggingMiddleware(Middleware):
async def on_message(self, context, call_next):
result = await call_next(context)
# log method, elapsed, etc.
return result
middleware = compose_middleware(bastion, LoggingMiddleware())
See examples/full_demo.py for a complete example.
TypeScript: Wrap an MCP Server
Step 1: Install dependencies
npm install @modelcontextprotocol/sdk @mcp-bastion/core
Step 2: Create your server (server.ts)
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
wrapWithMcpBastion,
wrapCallToolHandler,
} from "@mcp-bastion/core";
const server = new Server({ name: "my-mcp-server", version: "1.0.0" });
// Wrap the server with MCP-Bastion (rate limiting only by default)
// For prompt injection and PII, run the Python sidecar and set sidecarUrl
wrapWithMcpBastion(server, {
enableRateLimit: true,
maxIterations: 15,
timeoutMs: 60_000,
// Optional: enable ML features via Python sidecar
sidecarUrl: process.env.MCP_BASTION_SIDECAR || "",
enablePromptGuard: !!process.env.MCP_BASTION_SIDECAR,
enablePiiRedaction: !!process.env.MCP_BASTION_SIDECAR,
});
// Register tools (handlers are automatically wrapped)
server.setRequestHandler("tools/call" as any, async (request) => {
if (request.params?.name === "get_weather") {
return {
content: [{ type: "text", text: "Sunny, 22C" }],
isError: false,
};
}
throw new Error("Unknown tool");
});
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
}
main();
Step 3: Run with rate limiting only
npx tsx server.ts
Step 4: Run with full ML features (Python sidecar)
For prompt injection and PII redaction, run a Python HTTP service that exposes /prompt-guard and /pii-redact endpoints (see the Python package for sidecar implementation). Then:
# Start the Python sidecar, then the TypeScript server
MCP_BASTION_SIDECAR=http://localhost:8000 npx tsx server.ts
TypeScript: Wrap Individual Handlers
Wrap specific handlers only:
import {
wrapCallToolHandler,
wrapReadResourceHandler,
} from "@mcp-bastion/core";
import {
CallToolRequestSchema,
ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
// Wrap only the tool handler
const safeToolHandler = wrapCallToolHandler(
async (request) => {
// Your tool logic
return { content: [{ type: "text", text: "OK" }], isError: false };
},
{ enableRateLimit: true, maxIterations: 10 }
);
// Wrap only the resource handler (for PII redaction)
const safeResourceHandler = wrapReadResourceHandler(
async (request) => {
const contents = await fetchResource(request.params.uri);
return { contents };
},
{ sidecarUrl: "http://localhost:8000", enablePiiRedaction: true }
);
server.setRequestHandler(CallToolRequestSchema, safeToolHandler);
server.setRequestHandler(ReadResourceRequestSchema, safeResourceHandler);
Configuration Reference
| Option | Python | TypeScript | Default | Description |
|---|---|---|---|---|
enable_prompt_guard | Yes | Yes | True (Python) / False (TS) | Block malicious prompts via PromptGuard |
enable_pii_redaction | Yes | Yes | True (Python) / False (TS) | Mask PII in outgoing content |
enable_rate_limit | Yes | Yes | True | Enforce iteration and timeout caps |
max_iterations | Via TokenBucketRateLimiter | Yes | 15 | Max tool calls per session |
timeout_seconds / timeoutMs | Via TokenBucketRateLimiter | Yes | 60 | Session timeout |
token_budget | Via TokenBucketRateLimiter | - | 50,000 | FinOps token cap per request |
sidecarUrl | - | Yes | "" | Python sidecar URL for ML features |
threshold | Via PromptGuardEngine | - | 0.85 | Malicious probability cutoff |
setLogLevel | - | Yes | "info" | TypeScript: "debug" | "info" | "warn" | "error" |
Error Handling
When MCP-Bastion blocks a request, it returns standard MCP/JSON-RPC errors:
| Code | Exception | When |
|---|---|---|
| -32001 | PromptInjectionError | Tool args contain jailbreak/injection |
| -32002 | RateLimitExceededError | Session exceeds iteration or timeout limit |
| -32003 | TokenBudgetExceededError | Session exceeds token budget |
| -32004 | CircuitBreakerOpenError | Tool’s circuit breaker is open after failures |
| -32005 | ContentFilterError | Content filter matched a blocked pattern |
| -32006 | RBACError | Caller not allowed to use this tool |
| -32007 | SchemaValidationError | Tool arguments failed schema validation |
| -32008 | ReplayAttackError | Duplicate nonce / replay detected |
| -32009 | CostBudgetExceededError | Session cost budget exceeded |
# Python: exceptions
from mcp_bastion.errors import (
PromptInjectionError,
RateLimitExceededError,
TokenBudgetExceededError,
CircuitBreakerOpenError,
ContentFilterError,
RBACError,
SchemaValidationError,
ReplayAttackError,
CostBudgetExceededError,
)
import logging
logger = logging.getLogger(__name__)
try:
result = await middleware(context, call_next)
except (
PromptInjectionError,
RateLimitExceededError,
TokenBudgetExceededError,
CircuitBreakerOpenError,
ContentFilterError,
RBACError,
SchemaValidationError,
ReplayAttackError,
CostBudgetExceededError,
) as e:
logger.warning("blocked: %s", e.to_mcp_error())
// TypeScript: handlers return isError: true
import { logger, setLogLevel } from "@mcp-bastion/core";
setLogLevel("debug"); // optional: "debug" | "info" | "warn" | "error"
const result = await guardedHandler(request);
if (result.isError) {
logger.error("blocked", result.content);
}
Testing
MCP Inspector:
# Start your guarded server
python server.py # or: npx tsx server.ts
# In another terminal, launch the Inspector
npx -y @modelcontextprotocol/inspector
Connect via HTTP (http://localhost:8000/mcp) or stdio, then:
- List tools and call one with benign arguments (should succeed)
- Call a tool with "Ignore previous instructions" (should be blocked)
- Trigger 16+ tool calls in one session (should hit rate limit)
Testing
# Python (PYTHONPATH=src on Windows: $env:PYTHONPATH="src")
pytest tests/ -v
# TypeScript
npm run test --workspace=@mcp-bastion/core
# Full validation checklist (build, pillars, latency)
PYTHONPATH=src python scripts/validate_checklist.py
# MCP Inspector (manual)
npx -y @modelcontextprotocol/inspector
Third-Party Components
See NOTICE for licenses. MCP-Bastion uses Meta Llama Prompt Guard 2 (Llama 4 Community License) and Microsoft Presidio. For OWASP-relevant mitigations, dependency audit, and reporting vulnerabilities, see docs/SECURITY.md.
License
MCP-Bastion is distributed under the MCP-Bastion Community and Commercial License.
- Non-commercial use is permitted with required attribution/citation.
- Commercial use requires a separate paid agreement.
See:
