llms-full.txt

# JadeGate — Complete Reference

> For a quick overview, see /llms.txt

## The Problem

MCP has no security layer. When an AI client calls an MCP tool, it trusts the server completely. There is no policy enforcement, no identity verification, no anomaly detection. Any tool can read files, make network requests, or execute commands without restriction.

JadeGate fixes this by adding a transparent security proxy between AI clients and MCP servers.

## Architecture

```
AI Client (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed)
    ↓
  JadeGate Proxy
    ├── Policy Engine        → allow/deny/ask per tool, rate limiting
    ├── Runtime Monitor      → DAG call-chain tracking, anomaly detection, circuit breaker
    ├── Transport Layer      → transparent stdio/SSE proxy, no server modification
    ├── Trust Store          → TOFU fingerprinting + Ed25519 certificate verification
    ├── Security Scanner     → static analysis, capability detection, risk scoring
    └── Auto Installer       → config injection for all supported clients
    ↓
  MCP Server (filesystem, github, puppeteer, slack, etc.)
```

## Installation & Auto-Protection

```bash
pip install jadegate
```

On install, JadeGate automatically:
1. Scans the system for MCP client configurations
2. Wraps each configured MCP server with the JadeGate proxy
3. Backs up all original configs (fully reversible with `jadegate uninstall`)

No manual configuration required. Next time any supported client opens, all MCP tool calls are proxied through JadeGate.

## The 6 Security Layers — Detail

### Layer 1: Policy Enforcement
- Per-tool rules: allow, deny, or ask (requires human confirmation)
- Rate limiting: max calls per minute, configurable per tool
- Argument validation: pattern matching on tool call arguments
- Default policy blocks known dangerous patterns

### Layer 2: Runtime Monitoring
- Dynamic DAG: tracks call chains across tools in real time
- Anomaly detection: flags unusual call patterns (e.g., filesystem read → network send)
- Circuit breaker: automatically isolates failing or suspicious servers
- Session tracking: per-session call history and statistics

### Layer 3: Transport Proxy
- Transparent MCP proxy for stdio and SSE transports
- Intercepts all tool calls without modifying the MCP server
- Zero server-side changes required
- Supports all standard MCP message types

### Layer 4: Trust Verification
- TOFU (Trust On First Use): fingerprints server on first connection
- Ed25519 certificates: cryptographic identity verification
- Trust store: local database of known server fingerprints
- Mismatch detection: alerts on server identity changes

### Layer 5: Security Scanner
- Static analysis of MCP server tool definitions
- Capability detection: filesystem, network, shell, browser access
- Risk scoring: LOW / MEDIUM / HIGH / CRITICAL per server
- Pattern matching: known dangerous tool signatures

### Layer 6: Auto Installer
- Detects MCP client configs at standard paths
- Supported: Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed
- Config injection: wraps each server entry with JadeGate proxy
- Backup & restore: original configs preserved, clean uninstall

## CLI Reference

```bash
jadegate status      # Show protection status for all detected clients
jadegate scan        # Run security audit on all configured MCP servers
jadegate install     # Re-run auto-injection (after adding new servers)
jadegate uninstall   # Revert all config changes, restore backups
```

### Scan Output Format

```
$ jadegate scan

  💠 JadeGate v2.0.0 — AI Tool Call Security Protocol

  MCP Server Security Scan

  ✓ filesystem  ● MEDIUM    filesystem access
    tools: 3 discovered (read_file, write_file, list_directory)
  ✓ github      ● MEDIUM    network access
    tools: 5 discovered (search_repos, create_issue, ...)
  ✓ puppeteer   ● CRITICAL  shell + network + browser
    tools: 8 discovered (navigate, screenshot, evaluate, ...)

  3 servers scanned: 0 low, 2 medium, 0 high, 1 critical
```

## Python SDK Integration

For Python agents using OpenAI or Anthropic SDKs directly:

```bash
# Environment variable activation
export JADEGATE=1
python my_agent.py
```

```python
# Programmatic activation
import jadegate
jadegate.activate()

# All subsequent SDK tool calls are intercepted
from openai import OpenAI
client = OpenAI()
# tool calls now pass through JadeGate policy engine
```

## Policy Configuration

```json
{
  "default_action": "allow",
  "tool_rules": {
    "filesystem:write_file": {
      "action": "ask",
      "reason": "File write requires confirmation"
    },
    "shell:exec": {
      "action": "deny",
      "reason": "Shell execution blocked"
    },
    "github:create_issue": {
      "action": "allow",
      "rate_limit": 10
    }
  },
  "rate_limit": {
    "max_calls_per_minute": 60
  },
  "anomaly_detection": {
    "enabled": true,
    "max_chain_depth": 10
  }
}
```

## Supported Clients

| Client | Config Path | Auto-detected |
|--------|-----------|:---:|
| Claude Desktop | `~/.config/claude/` | ✅ |
| Cursor | `~/.cursor/` | ✅ |
| Windsurf | `~/.codeium/windsurf/` | ✅ |
| Cline | `~/.vscode/cline/` | ✅ |
| Continue | `~/.continue/` | ✅ |
| Zed | `~/.config/zed/` | ✅ |
| Custom | `jadegate install --config <path>` | Manual |

## Design Principles

- **Zero config**: `pip install` = protected. No setup files, no env vars.
- **Transparent**: MCP servers are unaware of JadeGate. No protocol changes.
- **Reversible**: `jadegate uninstall` restores all original configurations.
- **Offline**: All analysis and enforcement runs locally. Zero telemetry.
- **Fail-open**: If JadeGate crashes, MCP servers continue to function normally.
- **Deterministic**: Same policy + same input = same result. No probabilistic decisions.

## Testing

238 tests covering all 6 layers:
- Policy engine: rule matching, rate limiting, argument validation
- Runtime: DAG tracking, anomaly detection, circuit breaker
- Transport: stdio/SSE proxy, message interception
- Trust: TOFU, Ed25519 signing/verification, trust store
- Scanner: capability detection, risk scoring
- Installer: config detection, injection, backup/restore

```bash
pip install pytest
pytest tests/ -v
```

## Links

- GitHub: https://github.com/JadeGate/jadegate
- PyPI: https://pypi.org/project/jadegate/
- Website: https://jadegate.io
- Quick reference: https://jadegate.io/llms.txt