{
  "markdown": "<div align=\"center\">\n\n# 🛡️ mcp-bastion\n\n**A reliability &amp; security proxy for the Model Context Protocol (MCP).**\n\n_Self-healing connections, runtime tool-security, and a compliance-mapped audit trail for your MCP servers._\n\n[![npm version](https://img.shields.io/npm/v/mcp-bastion.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/mcp-bastion)\n[![npm downloads](https://img.shields.io/npm/dm/mcp-bastion.svg?color=cb3837)](https://www.npmjs.com/package/mcp-bastion)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6f42c1)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Gowthaman90/mcp-bastion)\n[![Measured coverage](https://img.shields.io/badge/mcp--defense--bench-63%25_coverage-2ea44f)](https://github.com/Gowthaman90/mcp-defense-bench)\n[![CI](https://github.com/Gowthaman90/mcp-bastion/actions/workflows/ci.yml/badge.svg)](https://github.com/Gowthaman90/mcp-bastion/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)](https://www.typescriptlang.org/)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)\n\n<br/>\n\n<img src=\"./assets/demo.svg\" alt=\"mcp-bastion: an MCP server crashes mid-session and the agent recovers it automatically\" width=\"760\">\n\n</div>\n\n---\n\n`mcp-bastion` sits between your MCP client (Claude Code, Cursor, Cline, Windsurf, Zed, Claude\nDesktop, or any MCP-compliant agent) and your MCP servers. It is **client-agnostic** — it works with\nany compliant client through configuration alone, with zero client-specific code — and **non-invasive**:\nyour servers run unchanged, and removing Bastion is a one-line config revert.\n\n📦 **Package:** [`mcp-bastion` on npm](https://www.npmjs.com/package/mcp-bastion) · 🗂️ **Official MCP Registry:** `io.github.Gowthaman90/mcp-bastion`\n\n🔒 **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.\n\n📖 **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)\n\n👤 **Created & maintained by [Gowthaman Arumugam](https://github.com/Gowthaman90)** — Independent Researcher. Companion benchmark: [mcp-defense-bench](https://github.com/Gowthaman90/mcp-defense-bench).\n\n## Contents\n\n- [Why](#why)\n- [How it works](#how-it-works)\n- [Features](#features)\n- [Quick start](#quick-start)\n- [Demo](#demo)\n- [Control tools](#control-tools)\n- [Configuration](#configuration)\n- [Transports](#transports)\n- [Runtime security](#runtime-security)\n- [Audit & compliance](#audit--compliance)\n- [Client setup](#client-setup)\n- [Architecture](#architecture)\n- [Development](#development)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n\n## Why\n\nWhen an MCP server disconnects mid-session, the agent only sees a generic _\"No such tool available\"_\nerror — **indistinguishable from a tool that never existed** — and it cannot reconnect; only a human\ncan. Long agent sessions silently lose capabilities and fail in confusing ways.\n\nBastion closes that gap. It health-checks every server, auto-reconnects with backoff, and — crucially —\nexposes control tools so the **agent itself** can inspect connection health and recover a dropped\nserver without human intervention.\n\n> Bastion now spans three layers: **reliability** (v0.1), **runtime security** (v0.2 — tool pinning /\n> rug-pull & poisoning detection), and **audit & compliance** (v0.3 — pluggable sinks mapped to NIST\n> AI RMF / OWASP LLM Top 10). See the [roadmap](#roadmap).\n\n## How it works\n\nToday your client connects **directly** to each server. With Bastion, your client connects to\n**Bastion**, which connects to those same servers on your behalf — so it sits in the tool-call path\nand can add reliability (and, later, security) transparently.\n\n```\nBefore:   Client ─▶ server A / server B / server C\n\nAfter:    Client ─▶ mcp-bastion ─▶ server A\n                                  ─▶ server B\n                                  ─▶ server C\n```\n\nBastion is a standard MCP **server** to your client and a standard MCP **client** to each upstream.\nBecause it speaks the protocol faithfully, it works with every compliant client automatically — the\nonly per-client difference is where you put a few lines of config.\n\n## Features\n\n- 🔌 **Client-agnostic** — one binary, config-only integration; no per-client plugins.\n- ♻️ **Self-healing** — health checks + capped exponential-backoff auto-reconnect for stdio servers.\n- 🧭 **Agent-recoverable** — `bastion__status` and `bastion__reconnect` let the agent detect and fix\n  drops itself, instead of hitting an opaque \"no such tool\" wall.\n- 🧩 **Transparent aggregation** — merges many servers into one, with per-server tool namespacing to\n  prevent collisions and tool-shadowing.\n- 💬 **Legible failures** — a dropped server yields an actionable message, not a crash.\n- 🛡️ **Runtime security** _(new in v0.2)_ — pins each tool's definition and blocks \"rug pulls\" (a\n  server changing a tool after approval); heuristically inspects descriptions for poisoning; detects\n  cross-server shadowing. See [Runtime security](#runtime-security).\n- 📝 **Audit & compliance** _(new in v0.3, opt-in)_ — structured, integrity-hash-chained audit events to\n  pluggable sinks (console / file / webhook), mapped to NIST AI RMF & OWASP LLM Top 10. See\n  [Audit & compliance](#audit--compliance).\n- 🪶 **Non-invasive & reversible** — your servers run unchanged; uninstall is a config revert.\n- 🧱 **Enterprise-grade codebase** — strict TypeScript, layered architecture, ESLint + Prettier, and\n  unit + end-to-end tests.\n\n## Quick start\n\nBastion is published on npm as [`mcp-bastion`](https://www.npmjs.com/package/mcp-bastion) — the\n`npx` command below fetches it automatically, so there's nothing to install first.\n\n**1. Add Bastion to your client**, pointing it at a config file:\n\n```jsonc\n// your client's mcpServers config\n{\n  \"mcpServers\": {\n    \"bastion\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-bastion\", \"--config\", \"bastion.config.json\"],\n    },\n  },\n}\n```\n\n**2. List your real servers in `bastion.config.json`** (moved verbatim from the client):\n\n```jsonc\n{\n  \"servers\": {\n    \"github\": { \"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"] },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/dir\"],\n    },\n  },\n  \"reconnect\": { \"auto\": true },\n  \"healthCheck\": { \"enabled\": true },\n}\n```\n\n**3. Restart your client.** Your tools now appear namespaced (e.g. `github__create_issue`) alongside\nBastion's control tools. See [`bastion.config.example.json`](./bastion.config.example.json) for the\nfull set of options.\n\n> 🔒 **Security is on by default.** Out of the box, Bastion runs the `balanced` enforcement profile:\n> it **blocks** high-confidence attacks (rug-pulls, argument/command injection, cross-server\n> exfiltration) and **warns** on heuristic ones (description/response\n> poisoning), while redacting leaked secrets from tool results. Set `security.enforcementProfile` to\n> `observe` (warn-only) or `strict` (block-all), or tune any individual control — see\n> [Runtime security](#runtime-security).\n\n## Demo\n\nSee the whole thing in action — a server crashing mid-session and healing itself:\n\n```bash\nnpm run demo\n```\n\nIt boots Bastion in front of a server that crashes on command, shows the agent getting an actionable\n\"reconnect\" message instead of a cryptic error, and then the connection auto-recovering with no human\ninvolved. To record it as a GIF: `asciinema rec demo.cast -c \"npm run demo\" && agg demo.cast assets/demo.gif`.\n\n## Control tools\n\nBastion injects control tools so the agent can manage connections and review security itself, using\nonly standard MCP calls:\n\n| Tool                  | Purpose                                                                                                    |\n| --------------------- | ---------------------------------------------------------------------------------------------------------- |\n| `bastion__status`     | Health of every proxied server: connected / disconnected / reconnecting / failed, tool counts, last error. |\n| `bastion__reconnect`  | Reconnect a named server (argument: `{ \"server\": \"<name>\" }`) without human intervention.                  |\n| `bastion__security`   | Per-tool security report: pin status (approved vs changed), poisoning findings, and shadowing.             |\n| `bastion__compliance` | Audit summary of recent activity mapped to NIST AI RMF / OWASP LLM Top 10 (requires `audit.enabled`).      |\n\n> **Re-approval is operator-only.** Clearing a rug-pull block is a security authority, so it is **not** an\n> agent-callable tool — a prompt-injected agent must not be able to re-approve the very tool it was blocked\n> from. A changed tool stays blocked until an operator clears it out-of-band; `bastion__approve` is not\n> advertised and a client call to it is refused.\n\n## Configuration\n\n| Key                            | Type                       | Default              | Description                                          |\n| ------------------------------ | -------------------------- | -------------------- | ---------------------------------------------------- |\n| `servers`                      | map                        | —                    | Upstream servers to proxy (required, at least one).  |\n| `servers.<name>.command`       | string                     | —                    | Executable to launch (e.g. `npx`, `node`).           |\n| `servers.<name>.args`          | string[]                   | `[]`                 | Arguments to `command`.                              |\n| `servers.<name>.env`           | map                        | —                    | Env overrides merged over the process env.           |\n| `servers.<name>.cwd`           | string                     | —                    | Working directory for the spawned process.           |\n| `reconnect.auto`               | boolean                    | `true`               | Auto-reconnect after an unexpected disconnect.       |\n| `reconnect.maxRetries`         | number                     | `10`                 | Max attempts before giving up (`-1` = unlimited).    |\n| `reconnect.initialBackoffMs`   | number                     | `500`                | Initial backoff, doubled each attempt.               |\n| `reconnect.maxBackoffMs`       | number                     | `30000`              | Backoff ceiling.                                     |\n| `healthCheck.enabled`          | boolean                    | `true`               | Enable periodic liveness probing.                    |\n| `healthCheck.intervalMs`       | number                     | `30000`              | Interval between probes.                             |\n| `healthCheck.timeoutMs`        | number                     | `5000`               | Per-probe timeout.                                   |\n| `namespace.strategy`           | `prefix` \\| `passthrough`  | `prefix`             | How upstream tool names are exposed.                 |\n| `namespace.separator`          | string                     | `__`                 | Separator used by the `prefix` strategy.             |\n| `security.pinTools`            | boolean                    | `true`               | Pin tool definitions and detect later changes.       |\n| `security.onRugPull`           | `block` \\| `warn`          | `block`              | Action when a pinned tool's definition changed.      |\n| `security.inspectDescriptions` | boolean                    | `true`               | Run poisoning heuristics on tool descriptions.       |\n| `security.onPoisoning`         | `block` \\| `warn`          | `warn`               | Action on a high-severity poisoning finding.         |\n| `audit.enabled`                | boolean                    | `false`              | Record an audit event for every tool call.           |\n| `audit.includeArgs`            | `none`\\|`redacted`\\|`full` | `none`               | How tool arguments are recorded.                     |\n| `audit.tamperEvident`          | boolean                    | `false`              | Hash-chain events so tampering is detectable.        |\n| `audit.sinks`                  | array                      | console              | Destinations: `console`, `file`, `webhook`, `otlp`.  |\n| `servers.<name>.transport`     | `stdio` \\| `http`          | `stdio`              | Local subprocess or remote endpoint.                 |\n| `servers.<name>.url`           | string                     | —                    | Remote MCP URL (required for `http`).                |\n| `servers.<name>.headers`       | map                        | —                    | Headers for `http` upstreams (e.g. `Authorization`). |\n| `listen.mode`                  | `stdio` \\| `http`          | `stdio`              | Serve Bastion over stdio or Streamable HTTP.         |\n| `listen.host` / `listen.port`  | string / number            | `127.0.0.1` / `3000` | Bind address for `http` mode.                        |\n| `listen.validateRoutingHeaders`| boolean                    | `true`               | Reject `Mcp-*` routing headers that disagree with the body (`-32020`, MCP 2026-07-28). |\n| `security.maxCacheTtlMs`       | number (ms)                | `3600000`            | Ceiling on upstream `ttlMs` cache hints forwarded downstream (MCP 2026-07-28). |\n\n## Transports\n\nBastion speaks two transports on **both** faces:\n\n- **stdio** (default) — the client spawns Bastion, and Bastion spawns local servers.\n- **Streamable HTTP** — connect to **remote** MCP servers (`servers.<name>` with `transport: \"http\"`,\n  a `url`, and optional auth `headers`), and/or **serve** Bastion over HTTP to multiple/remote clients\n  (`listen.mode: \"http\"`, or `--http <port>`).\n\nHTTP upstreams configured without an authentication header are flagged (`authenticated: false`) in\n`bastion__status` and warned at connect time.\n\n## Runtime security\n\n_New in v0.2._ Bastion adds a security layer in the tool-call path (an interceptor pipeline), enabled\nby default:\n\n- **Rug-pull detection (tool pinning).** Each tool's definition is pinned on first use. If a server\n  later changes that definition, the tool is blocked (`onRugPull: \"block\"`) until an operator reviews it\n  and re-approves it out-of-band (operator-only — not an agent-callable tool). This catches a server that\n  looks benign at install time and turns malicious afterward.\n- **Poisoning inspection.** Tool names and descriptions are scanned for manipulation heuristics\n  (instruction override, secret access, data exfiltration, covert instructions, embedded directives,\n  hidden/zero-width characters). Because heuristics can false-positive, the default is `warn` (logged\n  and reported, not blocked); set `onPoisoning: \"block\"` to enforce.\n- **Shadowing.** When two servers expose a tool with the same name, it's surfaced in the report.\n\nReview everything with the `bastion__security` tool. These checks apply to local stdio servers today;\nauthentication checks for remote servers arrive with HTTP transport support.\n\n## Audit & compliance\n\n_New in v0.3, opt-in._ Enable `audit` to record a structured, versioned event for every tool call —\nincluding calls blocked by the security layer:\n\n```jsonc\n\"audit\": {\n  \"enabled\": true,\n  \"includeArgs\": \"redacted\",     // none | redacted | full\n  \"tamperEvident\": true,          // integrity hash-chain (detects naive edits; unkeyed, not signed)\n  \"sinks\": [\n    { \"type\": \"file\", \"path\": \"./bastion-audit.jsonl\" },\n    { \"type\": \"webhook\", \"url\": \"https://collector.example/v1/audit\" }\n  ]\n}\n```\n\n- **Pluggable sinks.** `console` (stderr JSONL), `file` (JSONL append), `webhook` (batched POST), and\n  `otlp` (native OpenTelemetry logs export — point it at an OTel Collector to fan out to any SIEM/cloud\n  backend). The sink interface makes new destinations additive.\n- **Compliance mapping.** Each event is mapped to **NIST AI RMF** functions and **OWASP LLM Top 10**\n  categories; `bastion__compliance` returns an aggregate report of recent activity.\n- **Integrity hash chain.** With `tamperEvident`, events are linked by a SHA-256 hash chain, and the\n  exported `verifyChain` helper detects naive or partial edits within an intact log. The chain is\n  **unkeyed**: a party who can rewrite the log file can recompute a consistent chain, and truncating the\n  most-recent events links cleanly — so treat this as corruption-detection, **not** cryptographic\n  tamper-proofing. For stronger guarantees, ship events to an append-only external sink (webhook / OTLP →\n  a WORM store or SIEM). Keyed/signed attestation is on the roadmap.\n- **Redaction (best-effort).** Arguments are omitted by default; `includeArgs: \"redacted\"` keeps structure\n  while masking values under known credential key-names and common secret patterns. It is a heuristic, not\n  a guarantee — a secret under an unrecognized key can still be recorded, so prefer `none` for\n  high-sensitivity deployments.\n\n## Standards alignment\n\nEvery security check maps to recognized frameworks — the **NIST AI Risk Management Framework** (a U.S.\nfederal standard), the **OWASP Top 10 for LLM (2025)** and **Agentic (2026)** Applications, and\n**STRIDE**. The full per-check mapping (with reference links to the MCP-security literature the checks\nare drawn from) is in **[docs/CHECKS-MAPPING.md](docs/CHECKS-MAPPING.md)**.\n\nCoverage is measured independently — bastion is scored against a 22-vector attack surface by the\nvendor-neutral [mcp-defense-bench](https://github.com/Gowthaman90/mcp-defense-bench) benchmark, with a\npublic [leaderboard and framework mapping](https://gowthaman90.github.io/mcp-defense-bench/).\n\n## Client setup\n\nThe steps are identical for every client — only the **config file location** differs:\n\n| Client         | Where to add the `bastion` entry                   |\n| -------------- | -------------------------------------------------- |\n| Claude Code    | project `.mcp.json` (or `claude mcp add`)          |\n| Cursor         | `~/.cursor/mcp.json` or project `.cursor/mcp.json` |\n| Claude Desktop | `claude_desktop_config.json`                       |\n| Cline          | `cline_mcp_settings.json`                          |\n| Windsurf       | `~/.codeium/windsurf/mcp_config.json`              |\n\n> **Gradual adoption:** you don't have to route every server through Bastion — put only your flaky or\n> untrusted servers behind it and leave the rest connected directly.\n\n## Architecture\n\nBastion is organized into clear layers with a one-directional dependency flow, so each concern is\nindependently testable and easy to evolve:\n\n```\nsrc/\n├── cli.ts              # thin CLI entrypoint (parse → wire → serve)\n├── index.ts            # public library API\n├── errors.ts           # error hierarchy (BastionError, …)\n├── config/             # schema (Zod) + loader\n├── core/               # domain: upstream connection lifecycle, aggregation & routing\n├── proxy/              # client-facing MCP server + control tools\n├── observability/      # logging (audit sinks in v0.3)\n└── internal/           # small cross-cutting utilities\n```\n\nDesign details — including the client-agnostic rationale, the interceptor pipeline, and the audit-sink\nstrategy — live in the project's design docs.\n\n## Development\n\n```bash\nnpm install\nnpm run check      # format:check + lint + typecheck + test (the full gate)\nnpm test           # unit + end-to-end (in-memory transport) tests\nnpm run build      # bundle to dist/ (CLI + library)\nnpm run dev -- --config bastion.config.json\n```\n\n| Script                    | Does                                |\n| ------------------------- | ----------------------------------- |\n| `build`                   | Bundle CLI + library with `tsup`.   |\n| `dev`                     | Run the CLI from source with `tsx`. |\n| `typecheck`               | `tsc --noEmit` (strict).            |\n| `lint` / `lint:fix`       | ESLint (flat config).               |\n| `format` / `format:check` | Prettier.                           |\n| `test` / `test:watch`     | Vitest.                             |\n| `check`                   | Everything above, as one gate.      |\n\n## Roadmap\n\n| Version     | Theme                  | Highlights                                                                                |\n| ----------- | ---------------------- | ----------------------------------------------------------------------------------------- |\n| **v0.1** ✅ | **Reliability**        | Aggregating proxy, auto-reconnect, `bastion__status` / `__reconnect`.                     |\n| **v0.2** ✅ | **Runtime security**   | Tool-definition pinning (rug-pull detection), poisoning inspection, shadowing detection.  |\n| **v0.3** ✅ | **Audit & compliance** | Pluggable audit sinks (console / file / webhook), NIST AI RMF / OWASP LLM Top 10 mapping. |\n\nBoth **stdio** and **Streamable HTTP** transports are supported (see [Transports](#transports)).\n\n## Contributing\n\nContributions are very welcome — this project is built to be community-owned. Please read\n**[CONTRIBUTING.md](./CONTRIBUTING.md)** for the dev setup, project layout, and PR workflow, and our\n**[Code of Conduct](./CODE_OF_CONDUCT.md)**.\n\nIn short: open an issue for non-trivial changes, keep PRs focused with tests, and make sure\n`npm run check` passes (CI runs it on Node 18/20/22). Good first areas: additional client setup\nrecipes, more upstream test fixtures, and Streamable HTTP transport support.\n\n## Security\n\n`mcp-bastion` is security-adjacent software, so we hold it to a high bar. Please report\nvulnerabilities privately — **do not open a public issue**. See **[SECURITY.md](./SECURITY.md)** for\nthe disclosure process.\n\n## License\n\n[Apache-2.0](./LICENSE) © Gowthaman Arumugam and mcp-bastion contributors\n",
  "bytes": 22256,
  "sha": "f9b4c17f9d7f0775a0f9429a8e4c94a7a8b82177f506801135be4965880c389b",
  "repo_slug": "gowthaman90/mcp-bastion",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gowthaman90_mcp_bastion_91e908cb/readme"
}