io.github.Gowthaman90/mcp-bastion
Reliability + security proxy for MCP: runtime tool-security and a compliance-mapped audit trail.
Open source Open in the app JSON README (API)
About
Reliability + security proxy for MCP: runtime tool-security and a compliance-mapped audit trail.
Details
- Kind
- MCP servers
- Topic
- Security & identity
- Publisher
- gowthaman90
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.6.1
- Stars
- 6
- Forks
- 3
- Last push
- 2026-09-08T02:20:18Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 03:01:56
- Updated
- 2026-08-29 03:01:56
- Origin id
io.github.Gowthaman90/mcp-bastion
README
<div align="center">
# 🛡️ 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._
[](https://www.npmjs.com/package/mcp-bastion)
[](https://www.npmjs.com/package/mcp-bastion)
[](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Gowthaman90/mcp-bastion)
[](https://github.com/Gowthaman90/mcp-defense-bench)
[](https://github.com/Gowthaman90/mcp-bastion/actions/workflows/ci.yml)
[](./LICENSE)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
[](#contributing)
<br/>
<img src="./assets/demo.svg" alt="mcp-bastion: an MCP server crashes mid-session and the agent recovers it automatically" width="760">
</div>
---
`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](https://www.npmjs.com/package/mcp-bastion) · 🗂️ **Official MCP Registry:** `io.github.Gowthaman90/mcp-bastion`
🔒 **Security, measured:** on the open, vendor-neutral [mcp-defense-bench](https://github.com/Gowthaman90/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](https://medium.com/p/e74f638e9e15) · [dev.to](https://dev.to/gowthaman90/the-mcp-reliability-security-gap-and-an-open-source-proxy-that-fills-it-3ppo)
👤 **Created & maintained by [Gowthaman Arumugam](https://github.com/Gowthaman90)** — Independent Researcher. Companion benchmark: [mcp-defense-bench](https://github.com/Gowthaman90/mcp-defense-bench).
## Contents
- [Why](#why)
- [How it works](#how-it-works)
- [Features](#features)
- [Quick start](#quick-start)
- [Demo](#demo)
- [Control tools](#control-tools)
- [Configuration](#configuration)
- [Transports](#transports)
- [Runtime security](#runtime-security)
- [Audit & compliance](#audit--compliance)
- [Client setup](#client-setup)
- [Architecture](#architecture)
- [Development](#development)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [Security](#security)
- [License](#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](#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](#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](#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`](https://www.npmjs.com/package/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:
```jsonc
// 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):
```jsonc
{
"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`](./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](#runtime-security).
## Demo
See the whole thing in action — a server crashing mid-session and healing itself:
```bash
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:
| Tool | Purpose |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `bastion__status` | Health of every proxied server: connected / disconnected / reconnecting / failed, tool counts, last error. |
| `bastion__reconnect` | Reconnect a named server (argument: `{ "server": "<name>" }`) without human intervention. |
| `bastion__security` | Per-tool security report: pin status (approved vs changed), poisoning findings, and shadowing. |
| `bastion__compliance` | Audit summary of recent activity mapped to NIST AI RMF / OWASP LLM Top 10 (requires `audit.enabled`). |
> **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
| Key | Type | Default | Description |
| ------------------------------ | -------------------------- | -------------------- | ---------------------------------------------------- |
| `servers` | map | — | Upstream servers to proxy (required, at least one). |
| `servers.<name>.command` | string | — | Executable to launch (e.g. `npx`, `node`). |
| `servers.<name>.args` | string[] | `[]` | Arguments to `command`. |
| `servers.<name>.env` | map | — | Env overrides merged over the process env. |
| `servers.<name>.cwd` | string | — | Working directory for the spawned process. |
| `reconnect.auto` | boolean | `true` | Auto-reconnect after an unexpected disconnect. |
| `reconnect.maxRetries` | number | `10` | Max attempts before giving up (`-1` = unlimited). |
| `reconnect.initialBackoffMs` | number | `500` | Initial backoff, doubled each attempt. |
| `reconnect.maxBackoffMs` | number | `30000` | Backoff ceiling. |
| `healthCheck.enabled` | boolean | `true` | Enable periodic liveness probing. |
| `healthCheck.intervalMs` | number | `30000` | Interval between probes. |
| `healthCheck.timeoutMs` | number | `5000` | Per-probe timeout. |
| `namespace.strategy` | `prefix` \| `passthrough` | `prefix` | How upstream tool names are exposed. |
| `namespace.separator` | string | `__` | Separator used by the `prefix` strategy. |
| `security.pinTools` | boolean | `true` | Pin tool definitions and detect later changes. |
| `security.onRugPull` | `block` \| `warn` | `block` | Action when a pinned tool's definition changed. |
| `security.inspectDescriptions` | boolean | `true` | Run poisoning heuristics on tool descriptions. |
| `security.onPoisoning` | `block` \| `warn` | `warn` | Action on a high-severity poisoning finding. |
| `audit.enabled` | boolean | `false` | Record an audit event for every tool call. |
| `audit.includeArgs` | `none`\|`redacted`\|`full` | `none` | How tool arguments are recorded. |
| `audit.tamperEvident` | boolean | `false` | Hash-chain events so tampering is detectable. |
| `audit.sinks` | array | console | Destinations: `console`, `file`, `webhook`, `otlp`. |
| `servers.<name>.transport` | `stdio` \| `http` | `stdio` | Local subprocess or remote endpoint. |
| `servers.<name>.url` | string | — | Remote MCP URL (required for `http`). |
| `servers.<name>.headers` | map | — | Headers for `http` upstreams (e.g. `Authorization`). |
| `listen.mode` | `stdio` \| `http` | `stdio` | Serve Bastion over stdio or Streamable HTTP. |
| `listen.host` / `listen.port` | string / number | `127.0.0.1` / `3000` | Bind address for `http` mode. |
| `listen.validateRoutingHeaders`| boolean | `true` | Reject `Mcp-*` routing headers that disagree with the body (`-32020`, MCP 2026-07-28). |
| `security.maxCacheTtlMs` | number (ms) | `3600000` | Ceiling on upstream `ttlMs` cache hints forwarded downstream (MCP 2026-07-28). |
## Transports
Bastion speaks two transports on **both** faces:
- **stdio** (default) — the client spawns Bastion, and Bastion spawns local servers.
- **Streamable HTTP** — connect to **remote** MCP servers (`servers.<name>` with `transport: "http"`,
a `url`, and optional auth `headers`), and/or **serve** Bastion over HTTP to multiple/remote clients
(`listen.mode: "http"`, or `--http <port>`).
HTTP upstreams configured without an authentication header are flagged (`authenticated: false`) in
`bastion__status` and warned at connect time.
## Runtime security
_New in v0.2._ Bastion adds a security layer in the tool-call path (an interceptor pipeline), enabled
by default:
- **Rug-pull detection (tool pinning).** Each tool's definition is pinned on first use. If a server
later changes that definition, the tool is blocked (`onRugPull: "block"`) until an operator reviews it
and re-approves it out-of-band (operator-only — not an agent-callable tool). This catches a server that
looks benign at install time and turns malicious afterward.
- **Poisoning inspection.** Tool names and descriptions are scanned for manipulation heuristics
(instruction override, secret access, data exfiltration, covert instructions, embedded directives,
hidden/zero-width characters). Because heuristics can false-positive, the default is `warn` (logged
and reported, not blocked); set `onPoisoning: "block"` to enforce.
- **Shadowing.** When two servers expose a tool with the same name, it's surfaced in the report.
Review everything with the `bastion__security` tool. These checks apply to local stdio servers today;
authentication checks for remote servers arrive with HTTP transport support.
## Audit & compliance
_New in v0.3, opt-in._ Enable `audit` to record a structured, versioned event for every tool call —
including calls blocked by the security layer:
```jsonc
"audit": {
"enabled": true,
"includeArgs": "redacted", // none | redacted | full
"tamperEvident": true, // integrity hash-chain (detects naive edits; unkeyed, not signed)
"sinks": [
{ "type": "file", "path": "./bastion-audit.jsonl" },
{ "type": "webhook", "url": "https://collector.example/v1/audit" }
]
}
```
- **Pluggable sinks.** `console` (stderr JSONL), `file` (JSONL append), `webhook` (batched POST), and
`otlp` (native OpenTelemetry logs export — point it at an OTel Collector to fan out to any SIEM/cloud
backend). The sink interface makes new destinations additive.
- **Compliance mapping.** Each event is mapped to **NIST AI RMF** functions and **OWASP LLM Top 10**
categories; `bastion__compliance` returns an aggregate report of recent activity.
- **Integrity hash chain.** With `tamperEvident`, events are linked by a SHA-256 hash chain, and the
exported `verifyChain` helper detects naive or partial edits within an intact log. The chain is
**unkeyed**: a party who can rewrite the log file can recompute a consistent chain, and truncating the
most-recent events links cleanly — so treat this as corruption-detection, **not** cryptographic
tamper-proofing. For stronger guarantees, ship events to an append-only external sink (webhook / OTLP →
a WORM store or SIEM). Keyed/signed attestation is on the roadmap.
- **Redaction (best-effort).** Arguments are omitted by default; `includeArgs: "redacted"` keeps structure
while masking values under known credential key-names and common secret patterns. It is a heuristic, not
a guarantee — a secret under an unrecognized key can still be recorded, so prefer `none` for
high-sensitivity deployments.
## Standards alignment
Every security check maps to recognized frameworks — the **NIST AI Risk Management Framework** (a U.S.
federal standard), the **OWASP Top 10 for LLM (2025)** and **Agentic (2026)** Applications, and
**STRIDE**. The full per-check mapping (with reference links to the MCP-security literature the checks
are drawn from) is in **[docs/CHECKS-MAPPING.md](docs/CHECKS-MAPPING.md)**.
Coverage is measured independently — bastion is scored against a 22-vector attack surface by the
vendor-neutral [mcp-defense-bench](https://github.com/Gowthaman90/mcp-defense-bench) benchmark, with a
public [leaderboard and framework mapping](https://gowthaman90.github.io/mcp-defense-bench/).
## Client setup
The steps are identical for every client — only the **config file location** differs:
| Client | Where to add the `bastion` entry |
| -------------- | -------------------------------------------------- |
| Claude Code | project `.mcp.json` (or `claude mcp add`) |
| Cursor | `~/.cursor/mcp.json` or project `.cursor/mcp.json` |
| Claude Desktop | `claude_desktop_config.json` |
| Cline | `cline_mcp_settings.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
> **Gradual adoption:** you don't have to route every server through Bastion — put only your flaky or
> untrusted servers behind it and leave the rest connected directly.
## Architecture
Bastion is organized into clear layers with a one-directional dependency flow, so each concern is
independently testable and easy to evolve:
```
src/
├── cli.ts # thin CLI entrypoint (parse → wire → serve)
├── index.ts # public library API
├── errors.ts # error hierarchy (BastionError, …)
├── config/ # schema (Zod) + loader
├── core/ # domain: upstream connection lifecycle, aggregation & routing
├── proxy/ # client-facing MCP server + control tools
├── observability/ # logging (audit sinks in v0.3)
└── internal/ # small cross-cutting utilities
```
Design details — including the client-agnostic rationale, the interceptor pipeline, and the audit-sink
strategy — live in the project's design docs.
## Development
```bash
npm install
npm run check # format:check + lint + typecheck + test (the full gate)
npm test # unit + end-to-end (in-memory transport) tests
npm run build # bundle to dist/ (CLI + library)
npm run dev -- --config bastion.config.json
```
| Script | Does |
| ------------------------- | ----------------------------------- |
| `build` | Bundle CLI + library with `tsup`. |
| `dev` | Run the CLI from source with `tsx`. |
| `typecheck` | `tsc --noEmit` (strict). |
| `lint` / `lint:fix` | ESLint (flat config). |
| `format` / `format:check` | Prettier. |
| `test` / `test:watch` | Vitest. |
| `check` | Everything above, as one gate. |
## Roadmap
| Version | Theme | Highlights |
| ----------- | ---------------------- | ----------------------------------------------------------------------------------------- |
| **v0.1** ✅ | **Reliability** | Aggregating proxy, auto-reconnect, `bastion__status` / `__reconnect`. |
| **v0.2** ✅ | **Runtime security** | Tool-definition pinning (rug-pull detection), poisoning inspection, shadowing detection. |
| **v0.3** ✅ | **Audit & compliance** | Pluggable audit sinks (console / file / webhook), NIST AI RMF / OWASP LLM Top 10 mapping. |
Both **stdio** and **Streamable HTTP** transports are supported (see [Transports](#transports)).
## Contributing
Contributions are very welcome — this project is built to be community-owned. Please read
**[CONTRIBUTING.md](./CONTRIBUTING.md)** for the dev setup, project layout, and PR workflow, and our
**[Code of Conduct](./CODE_OF_CONDUCT.md)**.
In short: open an issue for non-trivial changes, keep PRs focused with tests, and make sure
`npm run check` passes (CI runs it on Node 18/20/22). Good first areas: additional client setup
recipes, more upstream test fixtures, and Streamable HTTP transport support.
## Security
`mcp-bastion` is security-adjacent software, so we hold it to a high bar. Please report
vulnerabilities privately — **do not open a public issue**. See **[SECURITY.md](./SECURITY.md)** for
the disclosure process.
## License
[Apache-2.0](./LICENSE) © Gowthaman Arumugam and mcp-bastion contributors