Gowthaman90/mcp-bastion

**A reliability & security proxy for the Model Context Protocol (MCP).**
_Self-healing connections, runtime tool-security, and a compliance-mapped audit trail for your MCP servers._
---
mcp-bastion sits between your MCP client (Claude Code, Cursor, Cline, Windsurf, Zed, Claude
Desktop, or any MCP-compliant agent) and your MCP servers. It is **client-agnostic** — it works with
any compliant client through configuration alone, with zero client-specific code — and **non-invasive**:
your servers run unchanged, and removing Bastion is a one-line config revert.
📦 **Package:** mcp-bastion on npm · 🗂️ **Official MCP Registry:** io.github.Gowthaman90/mcp-bastion
🔒 **Security, measured:** on the open, vendor-neutral mcp-defense-bench, Bastion covers **63% of the MCP attack surface (15.0/24 vectors; 11 enforced)** at zero false positives — the broadest of the proxies measured.
📖 **Launch story:** Medium · dev.to
👤 **Created & maintained by Gowthaman Arumugam** — Independent Researcher. Companion benchmark: mcp-defense-bench.
Contents
- Why
- How it works
- Features
- Quick start
- Demo
- Control tools
- Configuration
- Transports
- Per-user identity (gateway mode)
- Delegation checks
- Runtime security
- Audit & compliance
- Client setup
- Architecture
- Development
- Roadmap
- Contributing
- Security
- License
Why
When an MCP server disconnects mid-session, the agent only sees a generic _"No such tool available"_
error — **indistinguishable from a tool that never existed** — and it cannot reconnect; only a human
can. Long agent sessions silently lose capabilities and fail in confusing ways.
Bastion closes that gap. It health-checks every server, auto-reconnects with backoff, and — crucially —
exposes control tools so the **agent itself** can inspect connection health and recover a dropped
server without human intervention.
> Bastion now spans three layers: **reliability** (v0.1), **runtime security** (v0.2 — tool pinning /
> rug-pull & poisoning detection), and **audit & compliance** (v0.3 — pluggable sinks mapped to NIST
> AI RMF / OWASP LLM Top 10). See the roadmap.
How it works
Today your client connects **directly** to each server. With Bastion, your client connects to
**Bastion**, which connects to those same servers on your behalf — so it sits in the tool-call path
and can add reliability (and, later, security) transparently.
Bastion is a standard MCP **server** to your client and a standard MCP **client** to each upstream.
Because it speaks the protocol faithfully, it works with every compliant client automatically — the
only per-client difference is where you put a few lines of config.
Features
- 🔌 **Client-agnostic** — one binary, config-only integration; no per-client plugins.
- ♻️ **Self-healing** — health checks + capped exponential-backoff auto-reconnect for stdio servers.
- 🧭 **Agent-recoverable** — bastion__status and bastion__reconnect let the agent detect and fix
drops itself, instead of hitting an opaque "no such tool" wall.
- 🧩 **Transparent aggregation** — merges many servers into one, with per-server tool namespacing to
prevent collisions and tool-shadowing.
- 💬 **Legible failures** — a dropped server yields an actionable message, not a crash.
- 🛡️ **Runtime security** _(new in v0.2)_ — pins each tool's definition and blocks "rug pulls" (a
server changing a tool after approval); heuristically inspects descriptions for poisoning; detects
cross-server shadowing. See Runtime security.
- 📝 **Audit & compliance** _(new in v0.3, opt-in)_ — structured, integrity-hash-chained audit events to
pluggable sinks (console / file / webhook), mapped to NIST AI RMF & OWASP LLM Top 10. See
Audit & compliance.
- 🪶 **Non-invasive & reversible** — your servers run unchanged; uninstall is a config revert.
- 🧱 **Enterprise-grade codebase** — strict TypeScript, layered architecture, ESLint + Prettier, and
unit + end-to-end tests.
Quick start
Bastion is published on npm as mcp-bastion — the
npx command below fetches it automatically, so there's nothing to install first.
**1. Add Bastion to your client**, pointing it at a config file:
**2. List your real servers in bastion.config.json** (moved verbatim from the client):
**3. Restart your client.** Your tools now appear namespaced (e.g. github__create_issue) alongside
Bastion's control tools. See bastion.config.example.json for the
full set of options.
> 🔒 **Security is on by default.** Out of the box, Bastion runs the balanced enforcement profile:
> it **blocks** high-confidence attacks (rug-pulls, argument/command injection, cross-server