aegisgate-mcp

<!-- mcp-name: io.github.aegisgatesecurity/aegisgate-mcp -->
<div align="center">

# 🛡️ AegisGate MCP

**Secure MCP server framework — 22 layers of defense, zero dependencies.**

*A hardened, zero-dependency MCP server written in pure Go. Build your MCP server on a foundation that has security built in from line one — not bolted on after a breach.*

Apache 2.0 · 22 security layers · 30 regex patterns + CharCNN-BiLSTM (v13) ML detection · Zero CVEs · Zero external module dependencies

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Go](https://img.shields.io/badge/Go-1.26.6-00ADD8?logo=go)](https://golang.org/)
[![Version](https://img.shields.io/badge/Version-1.3.0-blue.svg)](#changelog)
[![Coverage](https://img.shields.io/badge/Coverage-91.3%25-brightgreen.svg)](#test-coverage)
[![Dependencies](https://img.shields.io/badge/Dependencies-Zero-success.svg)](#overview)
[![Docker](https://img.shields.io/badge/Docker-DebianSlim-135MB-blue.svg)](#docker)
[![ML](https://img.shields.io/badge/ML-CharCNN--BiLSTM_v13-purple.svg)](#ml-threat-detection-l3)
[![Arch](https://img.shields.io/badge/Arch-amd64%20%7C%20arm64-orange.svg)](#build)
[![CI](https://github.com/aegisgatesecurity/aegisgate-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/aegisgatesecurity/aegisgate-mcp/actions/workflows/ci.yml)
[![Security](https://github.com/aegisgatesecurity/aegisgate-mcp/actions/workflows/security.yml/badge.svg)](https://github.com/aegisgatesecurity/aegisgate-mcp/actions/workflows/security.yml)
[![Patent Pending](https://img.shields.io/badge/IP-Patent_Pending-8B5CF6?logo=uspto)](#ip-notice)

[Quick Start](#quick-start) · [Security Layers](#security-layers) · [RBAC](#rbac-roles) · [Architecture](#architecture) · [Protocol](#mcp-protocol-support) · [Docs](#documentation) · [Releases](https://github.com/aegisgatesecurity/aegisgate-mcp/releases)

[![GitHub stars](https://img.shields.io/github/stars/aegisgatesecurity/aegisgate-mcp?style=social)](https://github.com/aegisgatesecurity/aegisgate-mcp) — **If AegisGate MCP helps you secure your AI agents, please consider ⭐ starring this repo. It helps others discover it.**

</div>

> **AegisGate Security™** is a trademark of AegisGate Security, LLC, filed with the USPTO.
> "AegisGate MCP" is an unregistered product name. See [Trademark](#trademark) below.

---

## Why AegisGate MCP?

**38% of MCP servers have no authentication. 590+ security advisories. 3 critical CVEs in the official MCP SDKs in 6 months — including CVSS 9.8 remote code execution and the "Mother of All AI Supply Chains" flaw affecting 150M+ downloads.**

The official MCP SDKs give you the protocol. They don't give you security.
No authentication. No audit logging. No threat detection. No rate limiting.
No RBAC. Every server built on a bare SDK starts with a blank security posture
and it's on you to build it — or skip it, as 38% of servers do.

**AegisGate MCP is the secure alternative.** Build your MCP server on a
foundation that has security built in from line one — not bolted on after
a breach.

| | Official MCP SDKs | AegisGate MCP |
|---|---|---|
| Authentication | ❌ Bring your own | ✅ Bearer tokens + API keys + lockout |
| Authorization | ❌ Nothing | ✅ 4-tier RBAC with per-tool permissions |
| Audit logging | ❌ Nothing | ✅ Tamper-evident SHA-256 hash chain |
| Threat detection | ❌ Nothing | ✅ 30 regex patterns + neural ML (<1ms) |
| Supply chain risk | ❌ npm/PyPI deps | ✅ Zero dependencies (Go stdlib only) |
| CVEs | 3 critical in 6 months | Zero. Ever. |
| License | MIT | Apache 2.0 |

**22 security layers. Zero dependencies. Zero CVEs. Apache 2.0.**

> Need proxy mode, OAuth, SIEM, or compliance frameworks? See
> [When to Upgrade to AegisGate Platform](#when-to-upgrade-to-aegisgate-platform)
> below — or explore **[AegisGate Rampart](https://github.com/aegisgatesecurity/aegisgate-rampart)**
> for local AI API proxy protection.

---

## Overview

AegisGate MCP is a hardened, zero-dependency MCP server written in pure Go.
It sits between AI agents and the tools they call, applying **22 layers of
defense** to every request — from authentication and RBAC to neural threat
detection and chain analysis.

Standard MCP servers assume a trusted local environment. In production —
whether that's a cloud SaaS platform, an enterprise data pipeline, or an
air-gapped plant network — agents may execute commands, query databases, or
interact with critical systems. A single unauthorized or malicious tool call
can cause data exfiltration, process disruption, or worse. AegisGate MCP
wraps every tool call in defense-in-depth, all with zero external module
dependencies so it can run air-gapped.

| | |
|---|---|
| **Version** | 1.3.0 |
| **License** | Apache-2.0 |
| **Go version** | 1.26+ |
| **Module deps** | Zero (no `require` directives — all third-party code vendored) |
| **Docker image** | `debian:bookworm-slim`, ~135 MB (ML-enabled) or ~8 MB (heuristic-only) |
| **Architectures** | amd64, arm64 |
| **ML model** | CharCNN-BiLSTM v13, 1.6M params, <1ms CPU inference |
| **Tests** | 426 tests, 10 benchmarks, 3 fuzz targets, 91.3% coverage (non-CGO) / 91.3% (CGO) |

---

## Quick Start

### Build

```bash
go build -o mcp-server ./cmd/mcp-server
```

### Run

```bash
# Basic TCP server on :8081
./mcp-server

# With authentication and audit logging
./mcp-server --token my-secret --audit /var/log/mcp-audit.json

# With demo tools (ping, system_info, echo)
./mcp-server --demo

# stdio mode for local MCP clients (Claude Desktop, Cursor)
./mcp-server --transport stdio --demo

# Streamable HTTP mode (MCP 2025-06-18)
./mcp-server --transport http --addr :8081 --demo

# TLS + mutual TLS
./mcp-server --tls --tls-cert server.pem --tls-key server.key --tls-client-ca ca.pem

# Config file + health endpoint
./mcp-server --config /etc/mcp/config.json --health-addr :8082
```

### Docker

```bash
# Build and run (ML-enabled, ~135 MB)
docker build -t aegisgate-mcp .
docker run -p 8081:8081 aegisgate-mcp --demo

# With authentication and audit logging
docker run -p 8081:8081 \
  -e MCP_AUTH_TOKEN=your-secret-token \
  -e MCP_DEMO_TOOLS=true \
  aegisgate-mcp

# Heuristic-only build (no CGO, ~8 MB)
docker build --build-arg CGO_ENABLED=0 -t aegisgate-mcp:lite .
docker run -p 8081:8081 aegisgate-mcp:lite --demo
```

The default Docker image uses `debian:bookworm-slim` with CGO enabled,
including the vendored ONNX Runtime and CharCNN-BiLSTM v13 model for
full neural threat detection. A `--build-arg CGO_ENABLED=0` variant
produces a smaller heuristic-only image. Multi-arch builds support
both `linux/amd64` and `linux/arm64`.

### ML Threat Detection (L3)

AegisGate MCP includes the same CharCNN-BiLSTM v13 neural model used by
AegisGate Platform and Rampart — vendored with zero external module
dependencies. The model provides:

- **Semantic attack detection** — catches prompt injection and jailbreak
  attempts that bypass regex pattern matching
- **Evasion resistance** — detects obfuscation techniques (leetspeak,
  Unicode homoglyphs, character transposition, vowel deletion, word reversal)
- **Two-tier blocking** — scores ≥0.95 block independently; scores 0.50–0.94
  block only if L1 (regex) or L2 (input scanner) corroboration is present
- **Shadow mode** — log predictions without blocking (for calibration)
- **Heuristic fallback** — when CGO is unavailable, heuristic scoring
  provides baseline detection without ONNX

| Flag | Env Var | Default | Description |
|------|---------|---------|-------------|
| `--ml` | `MCP_ML_ENABLED` | `false` (CLI) / `true` (Docker) | Enable neural threat detection |
| `--ml-shadow` | `MCP_ML_SHADOW` | `false` | Log predictions but never block |
| `--ml-threshold` | `MCP_ML_THRESHOLD` | `0.50` | Threat score threshold (0.0–1.0) |
| `--ml-model` | `MCP_ML_MODEL` | `./models/threat_cnn_bilstm.onnx` | Path to ONNX model file |

### Library Usage

AegisGate MCP can be embedded as a Go library:

```go
package main

import (
    "context"
    "log"
    mcp "github.com/aegisgatesecurity/aegisgate-mcp"
)

func main() {
    cfg := mcp.DefaultServerConfig()
    cfg.AuthToken = "my-secret-token"
    cfg.AuditLogPath = "/var/log/mcp-audit.json"
    cfg.RateLimitRPM = 120
    cfg.ScanResponses = true

    server, err := mcp.NewSecuredMCPServer(cfg)
    if err != nil {
        log.Fatal(err)
    }

    // Register a custom tool
    // Note: tools are automatically scanned for prompt-injection poisoning
    // at registration time. If the description or inputSchema contains
    // malicious patterns, RegisterTool returns *ToolPoisoningError.
    server.RegisterTool("my_tool", "Does something useful", 40, map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "param1": map[string]interface{}{"type": "string"},
        },
        "required": []interface{}{"param1"},
    })
    server.RegisterToolHandler("my_tool", func(ctx context.Context, params map[string]interface{}) (interface{}, error) {
        return "result", nil
    })

    // Register a resource (MCP resources/list, resources/read)
    server.RegisterResource("config://app/info", "App Info", "App config as JSON", "application/json",
        func(ctx context.Context, uri string) (*mcp.ResourceContent, error) {
            return &mcp.ResourceContent{URI: uri, Text: `{"version":"1.0"}`, MimeType: "application/json"}, nil
        })

    // Register a prompt (MCP prompts/list, prompts/get)
    server.RegisterPrompt("code_review", "Generate a code review prompt",
        []mcp.PromptArgument{{Name: "filename", Required: true}},
        func(ctx context.Context, args map[string]string) (*mcp.GetPromptResult, error) {
            return &mcp.GetPromptResult{
                Messages: []mcp.PromptMessage{{Role: "user", Content: "Review " + args["filename"]}},
            }, nil
        })

    // Load built-in policy rules
    server.LoadDefaultPolicies()