MCP-Bastion

MCP-Bastion

README · Documentation · Demos · Dashboard / Observability · Multi-language · Benchmark · License · Security

[MCP-Bastion - Fortifying the Model Context Protocol]

[PyPI version] [PyPI downloads (mcp-bastion-python)] [Ecosystem PyPI downloads] [Python] [CI] [Docker proxy (GHCR)] [Docker dashboard (GHCR)] [Docs] [Demos] [Benchmark deck] [Multi-language] [License: Source Available] [Website]

Current release: 5.1.0 · Docker v5.1.0 · 26 PyPI packages · CHANGELOG

The Zero-Trust control plane for MCP agents. Your agent can call databases, APIs, and shell tools. One bad prompt can leak PII; one runaway loop can burn your API budget in minutes; three agents on one server with no identity boundary is a confused-deputy incident waiting to happen. MCP-Bastion wraps your MCP server with local guardrails: agent IAM, supply-chain checksums, injection blocking, PII redaction, and denial-of-wallet caps, under 5ms overhead, with no third-party safety API.

Guiding rule: Stay a zero-infra, drop-in library - the guardrail brain that composes with any gateway, not a gateway itself. Strategy: docs/ZERO_INFRA_STRATEGY.md.

Measured proof (offline, reproducible)

Slide deck (share with evaluators): MCP-Security-Deck-v3.pdf — security + FinOps proof pack (direct download).

[MCP-Bastion: SCAN → TEST → ENFORCE - No other tool has all three]

Scan → Test → Enforce (no other tool has all three)

scan vs audit - different inputs, different questions

They complement each other: audit the host surface, then scan the tools you attach. Neither replaces runtime enforce.

mcp-bastion scan also accepts --skills DIR for offline agent skill-file checks. Dependency CVEs: mcp-bastion osv-refresh then mcp-bastion osv-scan (local DB default; --online opt-in, fail-open).

# 1. Scan a tools/list export (or hand-authored catalog) - client-side, no cloudmcp-bastion scan examples/fixtures/tools-poisoned.jsonmcp-bastion fingerprint tools.json -o baseline.jsonmcp-bastion scan tools.json --baseline baseline.json --format json -o report.jsonmcp-bastion scan --skills ./skills/
# 1b. Audit local MCP client configs (what agents can already reach)mcp-bastion audit --root .mcp-bastion audit --format json -o risk-audit.json --fail-on none
# 2. Test policy effectivenessmcp-bastion redteam --config bastion.yaml
# 3. Enforce at runtime (filesystem path guards when agents can read local files)#    merge examples/bastion-filesystem-guards.yaml into bastion.yamlmcp-bastion validate --config bastion.yaml

[mcp-bastion scan CLI - flags injection, secrets, homoglyphs, and fingerprint drift with letter grade A–F]

_{mcp-bastion scan - client-side static scanner; no cloud, no ML download}

[mcp-bastion audit CLI - local MCP risk audit of client configs, over-broad tools, and standing credentials]

_{mcp-bastion audit - map the local MCP surface before you enforce; no network, no vault}

[MCP-Bastion client-side scan suite - schema preconditions, skill files, OSV dependency CVE lookup]

_{Schema · Skills · OSV - offline by default; no login server; no phone-home}

[MCP-Bastion dashboard tour: posture, prevalidation, OWASP, attack matrix, forensics, FinOps actual vs would-have-been]

_{Feature tour}

[MCP-Bastion dashboard walkthrough GIF]

_{Dashboard walkthrough}

[MCP-Bastion dashboard collage - security posture, OWASP coverage, attack matrix, and runtime KPIs]

Live security posture + runtime dashboard - local-only, zero infra. mcp-bastion dashboard --demo · Dashboard docs · Older Vimeo walkthrough

[MCP-Bastion: full MCP method coverage and Redis shared state for multi-replica deployments]

[MCP-Bastion hybrid stateful and stateless MCP transport with discovery, Redis-backed FinOps keys, and agent stability]

[MCP-Bastion 3.2 dual-path: legacy stateful sessions and SEP-2575-ready stateless state handles on one proxy]

Hybrid stateful / stateless MCP (3.2.0) - opt-in mcp_transport for SEP-2575 readiness without breaking legacy sessions. Architecture · Tutorial

Why MCP-Bastion? (Solving the 2026 MCP Security Crisis)

As noted in the NSA's recent Cybersecurity Information Sheet on MCP security and the OWASP MCP Top 10, traditional AppSec tools cannot secure agentic workflows. The gap is runtime governance and the confused deputy problem: multiple AI agents sharing one MCP server with no native identity boundary. Public registry typosquatting and unverified servers have made supply-chain verification a board-level concern.

MCP-Bastion acts as the Zero-Trust Control Plane for your agents, addressing the hardest production problems:

1. The Confused Deputy (Agent IAM): Identity-aware routing binds API tokens to Agent Identities and enforces strict per-tool RBAC. Your customer-support bot can call search_docs, not delete_user.
2. Supply chain & typosquatting defense: Cryptographic SHA-256 manifest verification blocks traffic when MCP server artifacts drift from your signed-off checksums.
3. Data exfiltration & injection prevention: PromptGuard heuristics + ML block jailbreaks locally; Presidio scrubs outbound PII before it hits a model context window.

Define your agent policies (bastion.yaml)

# Stop the Confused Deputy Problem  -  Identity-Aware Routingagent_iam:  enabled: true  token_metadata_key: bastion_agent_token  agents:    - id: customer_support_bot      token_env: BASTION_TOKEN_SUPPORT      allowed_tools: ["search_docs", "get_ticket_status"]      blocked_tools: ["execute_sql", "delete_user"]      rate_limit:        max_iterations: 5
# Supply-chain checksums before any tool executesserver_verification:  enabled: true  on_mismatch: block  base_path: .  manifest_path: mcp-server.manifest.json

Generate a manifest after a trusted build: mcp-bastion manifest server.py pyproject.toml -o mcp-server.manifest.json

Deep dive: docs/RUNTIME_GOVERNANCE.md · docs/ENTERPRISE_RUNTIME_CONTROLS.md (3.0 pillars)

Runtime governance pillars (3.0.0+, current 5.1.0)

Opt-in enterprise controls for production MCP runtimes. All default off so 2.x behavior is unchanged until you enable them.

mode: enforce
canary_goallock:  enabled: true
atr_rules:  enabled: true  rules_dir: ./atr-rules
secrets:  redact_patterns:    - rule: "sk-[A-Za-z0-9]{20,}"      strategy: mask

CLI compliance evidence: mcp-bastion report --framework soc2 --audit ./audit.jsonl

[MCP-Bastion 3.0 runtime governance pillars]

[Exfiltration canary blocks context leakage in tool arguments]

Full MCP surface + horizontal scale (2.0.0)

Previously, most pillars ran only on tools/call. 2.0.0 extends the pipeline to resources/read, prompts/get, sampling/createMessage, and elicitation/create - closing exfil/injection gaps on the rest of the MCP surface.

For multi-replica deployments, enable state_backend.type: redis so rate limits, replay nonces, cost budgets, and session tool scope are shared across pods (default memory is single-process).

state_backend:  type: redis  redis_url: redis://127.0.0.1:6379/0

pip install mcp-bastion-python[redis] · Deep dive: docs/MCP_SURFACE_AND_SCALE.md

Production hardening adopted in 2.0.0

Battle-tested patterns from the broader MCP gateway ecosystem, wired into the middleware stack:

cost_policy:  enabled: true  rules:    - when: { session_spend_pct_gte: 80 }      action: degrade_model      target_model: gpt-4o-mini    - when: { session_spend_pct_gte: 95 }      action: require_approval  expensive_chain:    enabled: true    max_projected_cost_usd: 1.0
governance:  attestation_enabled: true
boundary_mode:  enabled: true   # requires edge_auth or agent_iam
argument_guards:  enabled: true  rules:    - name: block_shell      match: "run_*"      arg: "$.command"      pattern: "(rm\\s+-rf|curl\\s+.*\\|.*sh)"      action: block
audit:  jsonl_path: .bastion/audit.jsonl
cost_tracker:  checkpoint_path: .bastion/cost-checkpoint.json

[MCP-Bastion Zero-Trust runtime governance: full MCP surface, Redis scale, Agent IAM, and beyond-OWASP coverage]

Why developers adopt it

FinOps & abuse protection (denial-of-wallet)

Agents can loop on expensive tools (search, LLM calls, paid APIs) until your bill spikes. Bastion enforces session-level FinOps at the MCP boundary before each tools/call:

Blocked calls return standard errors (RateLimitExceededError -32002, TokenBudgetExceededError -32003, CostBudgetExceededError -32009) and show up in the dashboard and audit log. See docs/ATTACK_PREVENTION.md.

Token reduction & cost saving

Bastion does not only block runaway spend - it reduces how much tool output and tool-catalog tokens reach the model on each turn (not the user’s LLM prompt text itself):

There is no honest single “X% prompt reduction” figure - savings are input-dependent. See docs/BENCHMARKS.md for reproducible pytest benchmarks and live numbers.

[MCP-Bastion benchmarks: RBAC tool-level matrix, output budget up to 99% on large tool responses, discovery filter catalog savings, lexical cache hit/miss]

_{Reproduce: PYTHONPATH=src python -m pytest tests/test_benchmarks_finops_rbac.py -v · Regenerate report: python scripts/generate_benchmark_report.py}

Less tool output and catalog noise per turn means lower LLM input cost - without sending prompts to a third-party optimizer API.

Bottom line: MCP turned every server into an agent gateway overnight. Bastion is the firewall that makes that gateway safe to run in production - in three lines of code or one config file.

OWASP MCP Top 10 + production attacks

All 10 OWASP MCP Top 10 risks are mitigated at the MCP boundary (see controls below). Bastion also blocks FinOps and abuse patterns that OWASP does not list separately.

[MCP-Bastion: OWASP MCP Top 10, FinOps abuse attacks, token reduction and cost saving, 16 security pillars]

OWASP MCP Top 10 (all addressed)

FinOps & abuse attacks (beyond OWASP)

Token reduction & cost saving

Deep-dive mapping and integration hooks: docs/SECURITY_OBSERVABILITY.md · docs/ATTACK_PREVENTION.md

Secure your MCP server in 3 lines (FastMCP)

pip install mcp mcp-bastion-fastmcp

from mcp.server.fastmcp import FastMCPfrom mcp_bastion_fastmcp import secure_fastmcp
mcp = FastMCP("My Server")secure_fastmcp(mcp)  # wires prompt guard, PII redaction, rate limits into tools/call

Policy-as-code instead? Copy bastion.yaml.example → bastion.yaml, then pip install mcp-bastion-python[policy]:

from mcp_bastion import build_middleware_from_config
middleware = build_middleware_from_config()  # loads bastion.yaml

More paths (TypeScript, CI validate, Docker): docs/QUICK_START.md · docs/README.md · website

• Prompt injection defense: Heuristic jailbreak blocking out of the box; Meta PromptGuard ML when Hugging Face access is configured.
• PII redaction: Presidio masks SSN, email, phone in outbound content.
• Denial-of-wallet protection: Token buckets, iteration caps, token budget, cost tracking.
• Response scan: Blocks jailbreak patterns in outbound tool/resource text.
• Output budget & grounding guard: Optional response truncation and path verification (opt-in).

How it works

MCP-Bastion sits in-process on your MCP server and inspects every tools/call before it reaches databases, APIs, or shell tools - then redacts sensitive data on the way back.

flowchart LR  Agent["AI agent / LLM client"]  Server["Your MCP server"]  Bastion["MCP-Bastion<br/>middleware"]  Tools["Tools & upstream APIs"]
  Agent -->|"JSON-RPC"| Server  Server --> Bastion  Bastion -->|"✓ allow / ✗ block"| Tools  Tools -->|"raw result"| Bastion  Bastion -->|"PII masked · audited"| Server  Server --> Agent

Three ways to adopt

flowchart TB  Start(["Protect my MCP server"])  Start --> FastMCP["FastMCP · Python<br/><code>secure_fastmcp(mcp)</code>"]  Start --> Policy["Policy-as-code<br/><code>build_middleware_from_config()</code>"]  Start --> TS["TypeScript<br/><code>wrapWithMcpBastion(server)</code>"]  FastMCP --> Docs["docs/QUICK_START.md · path A"]  Policy --> Yaml["bastion.yaml + CI validate"]  TS --> Sidecar["Rate limit in-process · ML via sidecar"]

Releases: npm, PyPI, and prebuilt Docker on GHCR - see DOCKER.md. Community: SUPPORT.md · CONTRIBUTING.md · FUNDING.md · Security: SECURITY.md.

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

Pillar definitions: Security controls, bastion.yaml sections, and how they relate to dashboard health rows are documented in docs/PILLARS.md (canonical reference; avoids ambiguous “total pillar” counts). The same page lists extended features restored in 1.0.16+ (semantic firewall, sensitive classifier, external policy, edge auth, tool allowlist, session scope, tool metadata guard, multi-tenant, audit hash chain, pricing hooks, telemetry sinks, red team and doctor CLIs, etc.), FinOps/context pillars in 1.0.17+ (output budget, discovery filter, response scan, grounding guard), and runtime governance (agent IAM, server verification - introduced in 1.0.18+, shipped in 2.0.0).

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

Access control, integrity & abuse

FinOps & performance

Audit, metrics & alerting

Policy, packaging & developer experience

Real-Time Dashboard and Alerts

The dashboard is optional and local - a read-only view over runtime metrics + local scan/audit artifacts. No login server, no cloud DB (see docs/ZERO_INFRA_STRATEGY.md).

Feature tour (GIF): posture + how-to-fix → OWASP → attack matrix → compliance → RBAC/governance → forensics → agents → posture drift → token & cost savings → traffic.

[MCP-Bastion dashboard feature tour GIF]

_{Feature tour}

[MCP-Bastion dashboard walkthrough GIF]

_{Dashboard walkthrough}

[MCP-Bastion dashboard collage - posture, OWASP, attack matrix, KPIs]

_{Regenerate captures: mcp-bastion dashboard --demo then python scripts/capture_dashboard_demo.py · Seed: --demo}

What you get on the board

mcp-bastion dashboard --port 7000 --demo# or: PYTHONPATH=src python dashboard/app.py

[Example /api/metrics JSON - requests_total, blocked_total, pii_redacted_total, cost_total, top_tools]

_{/api/metrics JSON for Grafana, Datadog, or custom pollers}

Feed scan/audit artifacts into the posture panels:

mkdir -p .bastion/scanmcp-bastion scan tools.json --format json -o .bastion/scan/catalog.jsonmcp-bastion scan --skills ./skills --format json -o .bastion/scan/skills.jsonmcp-bastion osv-scan --format json -o .bastion/scan/osv.jsonmcp-bastion audit --format json -o .bastion/scan/risk-audit.json

• Alerts: Slack webhook and cost-threshold alerts. Full UI reference: dashboard/README.md.

Documentation: Use Cases, Attacks, Metrics, Tutorials

Adoption paths (start-to-finish):

Full index: docs/README.md · handbook site: Docs guide · quick wrap: docs/QUICK_START.md · discovery: docs/DISCOVERY.md · contribute: CONTRIBUTING.md.

One-Line Docker

Prebuilt images (after the first publish-docker run, usually on a v* release tag):

docker pull ghcr.io/vaquarkhan/mcp-bastion-proxy:latestdocker run -p 8080:8080 ghcr.io/vaquarkhan/mcp-bastion-proxy:latest# Dashboard (optional, port 7000):# docker pull ghcr.io/vaquarkhan/mcp-bastion-dashboard:latest# docker run -p 7000:7000 ghcr.io/vaquarkhan/mcp-bastion-dashboard:latest# Pin a release: ghcr.io/vaquarkhan/mcp-bastion-proxy:vX.Y.Z (published on each v* tag)

Build locally (any revision):

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 (includes GHCR pull commands and package links for forks: replace vaquarkhan with your org or user in image paths).

Policy-as-Code (bastion.yaml)

Single config file controls policy (see docs/PILLARS.md for pillar definitions). Copy bastion.yaml.example to bastion.yaml, then:

from mcp_bastion import build_middleware_from_configmiddleware = build_middleware_from_config()

See docs/POLICY_AS_CODE.md.

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 audit                 # local MCP client-config risk reportmcp-bastion scan tools.json       # static tool-definition scanmcp-bastion validate              # validate bastion.yamlmcp-bastion serve --http 8080     # run MCP server with configmcp-bastion dashboard --port 7000 # run metrics dashboard

See docs/CLI.md.

Continuous integration (this repository)

On every pull request and push to main, .github/workflows/ci.yml runs:

1. pip install -e ".[dev,policy,dashboard]" - install the Python package with tests, YAML policy loading, and FastAPI for dashboard tests.
2. mcp-bastion validate --config bastion.yaml.example - ensure the example policy file loads.
3. python -m pytest --cov=mcp_bastion --cov-fail-under=92 - full Python test suite with ≥92% line coverage on src/mcp_bastion (see [tool.coverage.*] in pyproject.toml for measured paths and gates).
4. npm ci and npm test - TypeScript workspace tests.

To validate your repo’s bastion.yaml in CI without cloning MCP-Bastion, see examples/ci/README.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.

[MCP-Bastion features at a glance]

Why MCP-Bastion

• Active enforcement - Intercepts MCP tool traffic so policies (prompt injection checks, PII handling, content rules, RBAC, and more) run before tools execute and before sensitive results propagate.
• Local-first classification - PromptGuard and Presidio run in your environment; you are not required to send prompts to a third-party API for guardrail scoring.
• Stateful guardrails - Per-session rate limits, iteration caps, token budgets, and cost tracking to reduce runaway loops and unexpected spend.
• Composable integration - Use bastion.yaml with build_middleware_from_config() or wire MCPBastionMiddleware / wrapWithMcpBastion in Python or TypeScript. For a separate process in front of an upstream MCP server, use a wrapper or proxy you control; see docs/INTEGRATION_MODELS.md.

Structure

Example Files

Installation

Python

uv add mcp-bastion-python# orpip install mcp-bastion-python# pin a specific release (optional)pip install mcp-bastion-python==5.1.0

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]
  (adds pyyaml; otherwise you may get ImportError when loading policy files).
• Prompt injection (PromptGuard): two layers:
  1. Regex heuristics (always on) block obvious jailbreak strings such as “ignore previous instructions” - no model download required.
  2. ML classifier (default ungated): ProtectAI/deberta-v3-base-prompt-injection-v2 via use_ungated_default: true (no Hugging Face login). Optional gated upgrade: set use_ungated_default: false and use meta-llama/Llama-Prompt-Guard-2-86M after huggingface-cli login. Unverified payloads are blocked when fail_open: false (default). Run mcp-bastion doctor to verify ML availability.

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

npm

Framework Integrations

Drop-in security for your favorite LLM framework. Each package auto-installs mcp-bastion-python. Version and download columns use live badges from ecosystem-downloads.json (all-time total via PePy). Trends: pypistats.org.

One-place totals: Integrations download dashboard · ecosystem-downloads.json (sum of all 26 packages, refreshed daily).

pip install mcp-bastion-langchain      # LangChain agents and toolspip install mcp-bastion-openai         # OpenAI GPT API callspip install mcp-bastion-anthropic      # Anthropic Claude API callspip install mcp-bastion-bedrock        # AWS Bedrock runtimepip install mcp-bastion-gemini         # Google Geminipip install mcp-bastion-crewai         # CrewAI agent crewspip install mcp-bastion-llamaindex     # LlamaIndex RAG pipelinespip install mcp-bastion-groq           # Groq inferencepip install mcp-bastion-mistral        # Mistral AIpip install mcp-bastion-cohere         # Coherepip install mcp-bastion-azure          # Azure OpenAI Servicepip install mcp-bastion-vertexai       # Google Cloud Vertex AIpip install mcp-bastion-huggingface    # Hugging Face Inferencepip install mcp-bastion-deepseek       # DeepSeek AIpip install mcp-bastion-together       # Together AIpip install mcp-bastion-fireworks      # Fireworks AIpip install mcp-bastion-litellm        # LiteLLM (100+ providers)pip install mcp-bastion-ollama         # Ollama local modelspip install mcp-bastion-openrouter     # OpenRouter gatewaypip install mcp-bastion-xai            # xAI Grokpip install mcp-bastion-autogen        # Microsoft AutoGenpip install mcp-bastion-langgraph      # LangGraphpip install mcp-bastion-pydantic-ai    # Pydantic AIpip install mcp-bastion-openai-agents  # OpenAI Agents SDKpip install mcp-bastion-fastmcp        # FastMCP servers

Publish one-by-one: see integrations/PUBLISH.md.

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), and server.json (MCP registry). Bump before releasing.

Developer Guide

Integration examples for Python and TypeScript. Full contributor and feature docs:

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 middlewarebastion = 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:

# 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 via secure_fastmcp (patches tool dispatch - see integrations/mcp-bastion-fastmcp/README.md).

Step 1: Install dependencies

pip install mcp mcp-bastion-fastmcp

Step 2: Create your server file (server.py)

from mcp.server.fastmcp import FastMCPfrom mcp_bastion_fastmcp import secure_fastmcp
mcp = FastMCP("My Secure Server")secure_fastmcp(mcp)  # call right after FastMCP(), before mcp.run()
@mcp.tool()def get_weather(city: str) -> str:    """Get weather for a city."""    return f"Weather in {city}: 22C, sunny"
if __name__ == "__main__":    mcp.run(transport="streamable-http")

Step 3: Run the server

python server.py

MCP-Bastion (via secure_fastmcp):

• Scans tool arguments for prompt injection before execution
• Redacts PII in tool results on the way out
• Enforces default rate limits (15 calls per session, 60s timeout - see TokenBucketRateLimiter)

For full bastion.yaml policy or resource (resources/read) PII redaction, use the low-level MCP Server with build_middleware_from_config() - see docs/QUICK_START.md path B.

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_configmiddleware = 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 MCPBastionMiddlewarefrom mcp_bastion.pillars.rate_limit import TokenBucketRateLimiterfrom mcp_bastion.pillars.prompt_guard import PromptGuardEngine
# Stricter limitsrate_limiter = TokenBucketRateLimiter(    max_iterations=10,    timeout_seconds=30,    token_budget=25_000,)
# Higher threshold = fewer blocks, more riskprompt_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 PIIbastion_no_pii = MCPBastionMiddleware(enable_pii_redaction=False)

Python: Custom Middleware

Extend Middleware to add logging, metrics, or custom logic:

from mcp_bastion import MCPBastionMiddlewarefrom 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
bastion = MCPBastionMiddleware()  # or use the configured instance from abovemiddleware = 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,} 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, PII, semantic egress, and result guard, run the Python sidecarwrapWithMcpBastion(server, {  enableRateLimit: true,  maxIterations: 15,  timeoutMs: 60_000,  // Optional: enable ML / semantic features via Python sidecar  sidecarUrl: process.env.MCP_BASTION_SIDECAR || "",  enablePromptGuard: !!process.env.MCP_BASTION_SIDECAR,  enablePiiRedaction: !!process.env.MCP_BASTION_SIDECAR,  // Opt-in cyber extensions — see docs/CYBER_EXTENSIONS_CORE.md  enableSemanticEgress: true,  semanticEgressMode: "detect",  semanticEgressTools: ["create_pull_request", "send_email"],  tagResultProvenance: true,  enableAudit: true,});
// 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, PII redaction, semantic egress, and result guard, run a Python HTTP service that exposes /prompt-guard, /pii-redact, /semantic-egress, and /result-guard (see docs/CYBER_EXTENSIONS_CORE.md). Then:

# Start the Python sidecar, then the TypeScript server (sidecarUrl or MCP_BASTION_URL)MCP_BASTION_SIDECAR=http://localhost:8000 npx tsx server.ts

Mediation precondition: wrappers only see MCP-mediated tool calls. Out-of-band shell/git is out of scope.

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 handlerconst 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

Error Handling

When MCP-Bastion blocks a request, it returns standard MCP/JSON-RPC errors:

# Python: exceptionsfrom mcp_bastion.errors import (    PromptInjectionError,    RateLimitExceededError,    TokenBudgetExceededError,    CircuitBreakerOpenError,    ContentFilterError,    RBACError,    SchemaValidationError,    ReplayAttackError,    CostBudgetExceededError,    SemanticFirewallError,    ExternalPolicyDeniedError,    SensitiveContentError,    AuthenticationError,    ToolNotAllowedError,    SessionScopeExceededError,    ToolMetadataPoisoningError,    GroundingViolationError,    PromptGuardUnavailableError,    AgentAccessDeniedError,    ServerVerificationError,)import logginglogger = logging.getLogger(__name__)
try:    result = await middleware(context, call_next)except (    PromptInjectionError,    RateLimitExceededError,    TokenBudgetExceededError,    CircuitBreakerOpenError,    ContentFilterError,    RBACError,    SchemaValidationError,    ReplayAttackError,    CostBudgetExceededError,    SemanticFirewallError,    ExternalPolicyDeniedError,    SensitiveContentError,    AuthenticationError,    ToolNotAllowedError,    SessionScopeExceededError,    ToolMetadataPoisoningError,    GroundingViolationError,    PromptGuardUnavailableError,    AgentAccessDeniedError,    ServerVerificationError,) as e:    logger.warning("blocked: %s", e.to_mcp_error())

// TypeScript: handlers return isError: trueimport { 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 serverpython server.py   # or: npx tsx server.ts
# In another terminal, launch the Inspectornpx -y @modelcontextprotocol/inspector

Connect via HTTP (http://localhost:8000/mcp) or stdio, then:

1. List tools and call one with benign arguments (should succeed)
2. Call a tool with "Ignore previous instructions" (should be blocked)
3. Trigger 16+ tool calls in one session (should hit rate limit)

Testing

# Python (PYTHONPATH=src on Windows: $env:PYTHONPATH="src")python -m pytest tests/ -v
# TypeScriptnpm 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 and dependency audit, see docs/SECURITY.md. To report vulnerabilities privately, see SECURITY.md.

License

MCP-Bastion is distributed under the MCP-Bastion Community and Commercial License (LICENSE).

• Free for non‑commercial use when you cite MCP-Bastion and the copyright notice (see CITATION.cff; you can list your name, team, or org as authors or as who used the software, while still including the project and repository in the credit).
• Copyright is retained. Do not remove license or copyright text, and do not republish a duplicate of the work as if it were unrelated software without meeting the License terms.
• Commercial use (as defined in the License) may still require a separate written agreement - see COMMERCIAL_LICENSE.md.

See also:

• LICENSE
• COMMERCIAL_LICENSE.md
• FUNDING.md - sponsorship and sustainability
• SUPPORT.md - docs, issues, response expectations
• CITATION.cff

Product overview & security decks

Reproducible numbers behind the decks: docs/BENCHMARKS.md · threat model: docs/THREAT_MODEL.md.