🛡️ 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
• 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.

Before:   Client ─▶ server A / server B / server C

After:    Client ─▶ mcp-bastion ─▶ server A
                                  ─▶ server B
                                  ─▶ server C

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:

// your client's mcpServers config
{
  "mcpServers": {
    "bastion": {
      "command": "npx",
      "args": ["-y", "mcp-bastion", "--config", "bastion.config.json"],
    },
  },
}

2. List your real servers in bastion.config.json (moved verbatim from the client):

{
  "servers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
    },
  },
  "reconnect": { "auto": true },
  "healthCheck": { "enabled": true },
}

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 exfiltration) and warns on heuristic ones (description/response poisoning), while redacting leaked secrets from tool results. Set security.enforcementProfile to observe (warn-only) or strict (block-all), or tune any individual control — see Runtime security.

Demo

See the whole thing in action — a server crashing mid-session and healing itself:

npm run demo

It boots Bastion in front of a server that crashes on command, shows the agent getting an actionable "reconnect" message instead of a cryptic error, and then the connection auto-recovering with no human involved. To record it as a GIF: asciinema rec demo.cast -c "npm run demo" && agg demo.cast assets/demo.gif.

Control tools

Bastion injects control tools so the agent can manage connections and review security itself, using only standard MCP calls:

Re-approval is operator-only. Clearing a rug-pull block is a security authority, so it is not an agent-callable tool — a prompt-injected agent must not be able to re-approve the very tool it was blocked from. A changed tool stays blocked until an operator clears it out-of-band; bastion__approve is not advertised and a client call to it is refused.

Configuration