# Mcp Capagate

> Capability-aware firewall and policy compiler for MCP tool calls.

- **Type:** MCP server
- **Install:** `agentstack add mcp-choose-hy-mcp-capagate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [choose-hy](https://agentstack.voostack.com/s/choose-hy)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [choose-hy](https://github.com/choose-hy)
- **Source:** https://github.com/choose-hy/mcp-capagate

## Install

```sh
agentstack add mcp-choose-hy-mcp-capagate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP CapaGate

[](https://github.com/choose-hy/mcp-capagate/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)

Capability-aware firewall and policy compiler for MCP tool calls.

面向 MCP 工具调用的能力图谱、安全策略编译器与运行时防火墙。

[中文 README](README.zh-CN.md)

Stop unsafe MCP tool calls before they execute.

MCP CapaGate turns MCP tool schemas into a Capability Graph, compiles least-privilege policy, and enforces `ALLOW` / `WARN` / `REQUIRE_APPROVAL` / `BLOCK` decisions through a deterministic runtime proxy.

```text
read_order: ALLOW
issue_refund: REQUIRE_APPROVAL or BLOCK
execute_shell: BLOCK
read_secret + send_email: BLOCK
```

`Tool Schema -> Capability Extraction -> Capability Graph -> Policy Compiler -> Runtime Firewall -> Audit Receipts + Reports`

This is not another MCP scanner. It is not another chatbot framework. It runs locally and does not require training data, fine-tuning, proprietary data, a database, telemetry, or an LLM API key.

Research-style framing:

> We propose a capability-aware policy compiler for MCP tools that maps tool schemas to a risk graph, synthesizes least-privilege policies, and enforces them at runtime through a deterministic MCP proxy.

## The Problem

MCP gives agents tools such as `read_file`, `send_email`, `issue_refund`, `execute_shell`, and `query_database`. Once an LLM can call tools, prompt injection is no longer only a text risk; it can become execution risk.

Safe-looking tools can also combine into dangerous attack chains: read a customer profile, summarize it, then send it to an external inbox; write a file, then execute a shell command; add a forwarding rule, then quietly exfiltrate future messages.

## What CapaGate Does

MCP CapaGate asks a stronger question:

> What can this tool do, what can it be chained with, and what policy should exist before an agent calls it?

It converts tool schemas into a Capability Graph, detects drift and attack chains, compiles least-privilege policy, and enforces decisions through a transparent JSON-RPC stdio proxy.

## Without / With CapaGate

Without CapaGate:

- tool risk is implicit
- schema drift may go unnoticed
- safe tools can chain into exfiltration
- risky calls may execute before review

With CapaGate:

- tools become capability nodes
- risky tools get explicit policy
- dangerous calls are blocked before execution
- every decision has an audit receipt

## 30-Second Demo

```bash
pnpm install
pnpm build
pnpm --filter @mcp-capagate/cli capagate demo
```

The demo generates:

- `reports/scan.json`
- `capagate.policy.yaml`
- `reports/summary.md`
- `reports/index.html`
- `.capagate/audit.jsonl`

## Security Decisions

MCP CapaGate uses four explicit decisions:

- `ALLOW`: forward the call.
- `WARN`: forward and log a warning receipt.
- `REQUIRE_APPROVAL`: require interactive human approval; non-interactive mode blocks.
- `BLOCK`: return a JSON-RPC error without forwarding.

## Capability Graph

Capabilities include:

`read_data`, `write_data`, `delete_data`, `execute_code`, `send_message`, `external_network`, `financial_action`, `identity_access`, `credential_access`, `database_query`, `database_write`, `filesystem_read`, `filesystem_write`, `shell_execution`, `browser_automation`, `admin_action`, `private_data_access`, `cross_system_exfiltration`, `webhook_post`, and `unknown`.

Edges model risky combinations:

- sensitive read followed by external send
- filesystem write followed by shell execution
- private data access
- state mutation
- cross-server tool shadowing

Every graph gets a stable SHA-256 hash for drift detection.

## Policy Compiler

The compiler synthesizes least-privilege policy from the graph:

- allow read-only low-risk tools
- warn on medium-risk or unclear tools
- require approval for private data, financial actions, writes, and external messages
- block shell execution, arbitrary code execution, credential exfiltration, and destructive actions by default

Policy is YAML, deterministic, and human-reviewable.

## Runtime Proxy

`capagate wrap` runs an upstream stdio MCP server behind a transparent firewall:

```bash
capagate wrap --policy capagate.policy.yaml --scan reports/scan.json -- npx @modelcontextprotocol/server-filesystem ./workspace
```

The proxy forwards non-tool JSON-RPC messages unchanged. For `tools/call`, it evaluates policy, optionally checks session attack-chain state, writes a receipt to `.capagate/audit.jsonl`, and fails closed on parse or evaluation errors.

## Tool Drift

Baseline a graph in version control, then compare it in CI:

```bash
capagate diff --baseline .capagate/baseline.json --current reports/scan.json
```

Drift detection flags new tools, removed tools, schema changes, description changes, capability changes, risk changes, and graph hash changes.

## Attack-Chain Detection

MCP CapaGate tracks session-level tool-call memory:

- private or secret read taints a session
- later email, webhook, browser, or external network sink can be blocked
- file write followed by shell execution is treated as persistence risk
- sensitive read after external-network activity is warned or blocked

This is deterministic. It does not require an LLM.

## CLI Usage

```bash
capagate init
capagate discover --input tools-list-response.json --out normalized-tools.json
capagate discover --mcp-config claude_desktop_config.json --out reports/discovered-tools.json
capagate scan --input examples/refund-server/tools.json --out reports/scan.json
capagate policy --input reports/scan.json --out capagate.policy.yaml
capagate baseline save --scan reports/scan.json --out .capagate/baseline.json
capagate baseline verify --baseline .capagate/baseline.json --current reports/scan.json --fail-on high
capagate diff --baseline .capagate/baseline.json --current reports/scan.json
capagate benchmark --suite benchmarks/tool-risk-suite --out reports/benchmark.json --markdown reports/benchmark.md
capagate report --scan reports/scan.json --policy capagate.policy.yaml --html reports/index.html --markdown reports/summary.md
capagate wrap --policy capagate.policy.yaml -- npx your-mcp-server
capagate demo
```

## Benchmark

MCP CapaGate includes an MCP Tool Risk Benchmark:

```bash
capagate benchmark --suite benchmarks/tool-risk-suite --out reports/benchmark.json --markdown reports/benchmark.md
```

It measures capability extraction, policy decisions, scanner findings, drift detection, and attack-chain detection across synthetic MCP tool-risk scenarios.

## GitHub Action

External users should use the published action, for example `choose-hy/mcp-capagate@v0.2.0`:

```yaml
name: MCP CapaGate

on:
  pull_request:
  workflow_dispatch:

jobs:
  mcp-capagate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: choose-hy/mcp-capagate@v0.2.0
        with:
          config: capagate.yaml
          fail-on: high
          report-dir: reports
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: mcp-capagate-report
          path: reports/
```

- `fail-on: high` fails the workflow when high or critical findings are detected.
- `report-dir` controls where scan JSON, Markdown, HTML, and SARIF reports are written.
- The Markdown report is also written to the GitHub step summary.
- For local development inside this repository, use `uses: ./`.

## Examples

- `examples/refund-server`: read order, issue refund, cancel order, send refund email
- `examples/filesystem-server`: read, write, delete, execute shell
- `examples/email-server`: list inbox, send email, forwarding rule
- `examples/poisoned-tools`: synthetic prompt-injection metadata, hidden Unicode, schema comments, and suspicious examples
- `examples/mcp-client-config`: synthetic MCP client config discovery workflow

## Reports

Reports include:

- security posture summary
- capability graph summary
- tool risk matrix
- top critical risks
- policy decisions
- drift findings
- attack-chain findings
- audit timeline
- recommended fixes
- product-facing summary
- developer-facing remediation

## Further Reading

- [Limitations](docs/limitations.md): deployment boundaries, safety assumptions, and known MVP limits.
- [Comparison](docs/comparison.md): how CapaGate differs from scanners, guardrails, observability, and sandboxing.
- [Policy DSL](docs/policy-dsl.md): argument-level constraints for paths, domains, amounts, flags, and patterns.
- [Runtime Modes](docs/runtime-modes.md): enforce, shadow, and audit-only behavior for the proxy.
- [Taint Tracking](docs/taint-tracking.md): session taint labels and external-sink attack-chain detection.
- [MCP Discovery](docs/mcp-discovery.md): parse MCP client configs and optionally probe `tools/list`.
- [Baseline CI](docs/baseline-ci.md): save graph baselines and fail pull requests on risky drift.
- [Benchmark](docs/benchmark.md): MCP Tool Risk Benchmark scenarios, metrics, and limitations.

## Roadmap

- Ed25519-signed audit receipts
- richer HTTP proxy integration
- server identity pinning
- policy override templates
- optional LLM-assisted explanations that never affect deterministic enforcement
- graph visualization exports

## Security

MCP CapaGate is a guardrail, not a sandbox. Run upstream MCP servers with least-privilege OS permissions. Do not pass real secrets into examples or tests. The MVP redacts common secret and PII patterns in responses, but production deployments should still restrict upstream server permissions.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [choose-hy](https://github.com/choose-hy)
- **Source:** [choose-hy/mcp-capagate](https://github.com/choose-hy/mcp-capagate)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-choose-hy-mcp-capagate
- Seller: https://agentstack.voostack.com/s/choose-hy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.