Bastion MCP Server

MCP-Bastion

Current release: 3.1.0 · Docker v3.1.0 · 18 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.

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

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

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 + prevalidation → OWASP heatmaps → attack matrix → compliance → governance → forensics → FinOps actual vs would-have-been → traffic.

What you get on the board

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

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 (docs hub) · published site entry: docs/index.md · quick wrap: docs/QUICK_START.md · discovery: docs/DISCOVERY.md · contribute: CONTRIBUTING.md.

Documentation truncated — see the full README on GitHub.