MCP-Bastion

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

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).

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 cloud
mcp-bastion scan examples/fixtures/tools-poisoned.json
mcp-bastion fingerprint tools.json -o baseline.json
mcp-bastion scan tools.json --baseline baseline.json --format json -o report.json
mcp-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 effectiveness
mcp-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.yaml
mcp-bastion validate --config bastion.yaml

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

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

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

_{Feature tour}

_{Dashboard walkthrough}

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

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 Routing
agent_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 executes
server_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

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

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.

_{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.

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 FastMCP
from 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.

_{Feature tour}

_{Dashboard walkthrough}

_{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

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

Feed scan/audit artifacts into the posture panels:

mkdir -p .bastion/scan
mcp-bastion scan tools.json --format json -o .bastion/scan/catalog.json
mcp-bastion scan --skills ./skills --format json -o .bastion/scan/skills.json
mcp-bastion osv-scan --format json -o .bastion/scan/osv.json
mcp-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:latest
docker 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_config
middleware = 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 report
mcp-bastion scan tools.json       # static tool-definition scan
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.

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.

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
# or
pip 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).

Package	Protects	Version	Downloads
mcp-bastion-python	Core middleware		· pypistats
mcp-bastion-langchain	LangChain		· pypistats
mcp-bastion-openai	OpenAI GPT		· pypistats
mcp-bastion-anthropic	Anthropic Claude		· pypistats
mcp-bastion-bedrock	AWS Bedrock		· pypistats
mcp-bastion-gemini	Google Gemini		· pypistats
mcp-bastion-crewai	CrewAI		· pypistats
mcp-bastion-llamaindex	LlamaIndex		· pypistats
mcp-bastion-groq	Groq		· pypistats
mcp-bastion-mistral	Mistral AI		· pypistats
mcp-bastion-cohere	Cohere		· pypistats
mcp-bastion-azure	Azure OpenAI		· pypistats
mcp-bastion-vertexai	Vertex AI		· pypistats
mcp-bastion-huggingface	Hugging Face		· pypistats
mcp-bastion-deepseek	DeepSeek AI		· pypistats
mcp-bastion-together	Together AI		· pypistats
mcp-bastion-fireworks	Fireworks AI		· pypistats
mcp-bastion-litellm	LiteLLM (100+ providers)		· pypistats
mcp-bastion-ollama	Ollama local models		· pypistats
mcp-bastion-openrouter	OpenRouter gateway		· pypistats
mcp-bastion-xai	xAI Grok		· pypistats
mcp-bastion-autogen	Microsoft AutoGen		· pypistats
mcp-bastion-langgraph	LangGraph		· pypistats
mcp-bastion-pydantic-ai	Pydantic AI		· pypistats
mcp-bastion-openai-agents	OpenAI Agents SDK		· pypistats
mcp-bastion-fastmcp	FastMCP servers		· pypistats

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-litellm        # LiteLLM (100+ providers)
pip install mcp-bastion-ollama         # Ollama local models
pip install mcp-bastion-openrouter     # OpenRouter gateway
pip install mcp-bastion-xai            # xAI Grok
pip install mcp-bastion-autogen        # Microsoft AutoGen
pip install mcp-bastion-langgraph      # LangGraph
pip install mcp-bastion-pydantic-ai    # Pydantic AI
pip install mcp-bastion-openai-agents  # OpenAI Agents SDK
pip 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 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:

# 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 FastMCP
from 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_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 import MCPBastionMiddleware
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

bastion = MCPBastionMiddleware()  # or use the configured instance from above
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,
} 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 sidecar
wrapWithMcpBastion(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 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

Error Handling

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

# Python: exceptions
from 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 logging
logger = 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: 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:

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

# 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 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.