使用说明

宙斯盾MCP

MCP治理代理将软规则转化为硬约束。

Aegis MCP作为协议级代理位于您的AI代理和MCP工具服务器之间，强制执行代理无法绕过的约束——速率限制、访问控制、人工审批工作流、序列化执行队列和完整审计日志。任何MCP兼容代理都不需要更改代码。

         AI Agents
    ┌────────┬────────┐
  Agent    Agent    Agent
    A        B        C
    │        │        │
    └────┬───┴───┬────┘
         ▼       ▼
┌────────────────────────────────┐
│       Aegis MCP (:18070)       │
│                                │
│  Pipeline:                     │
│  ① ACL → ② Rate Limit         │
│  → ③ Human Approval            │
│  → ④ FIFO Queue → ⑤ Forward   │
│  → ⑥ Audit Log                │
└───────────────┬────────────────┘
                ▼
┌────────────────────────────────┐
│       MCP Tool Server          │
│       (e.g. social media,      │
│        database, APIs...)      │
└────────────────────────────────┘

为什么选择MCP代理？

AI代理是强大但不可靠的规则追随者。基于提示的“软规则”，如“每天发布不超过一次”，经常被违反。当代理在真实账户（社交媒体、电子商务、客户服务）上操作时，一系列不受约束的行为可能会引发平台禁令、合规违规或更糟糕的情况。

Aegis MCP将软规则转化为 程序性硬约束 在MCP协议级别。无论LLM决定做什么，代理都不能超过其速率限制或跳过审批步骤。

与需要在每个代理中更改代码的基于SDK的方法不同，Aegis MCP作为 透明代理 --将您的代理指向Aegis MCP而不是后端，治理将自动执行。适用于任何MCP兼容的代理：Claude Code、OpenClaw、自定义代理等。

特性

访问控制（ACL） --每个代理、每个后端、每个工具的允许/拒绝规则。被拒绝的工具对代理不可见（已从中删除 tools/list 答复）。
两级速率限制 --每个代理的滑动窗口限制和全局跨代理限制。所有代理共享一个帐户？全球限制防止累积过度使用。
人工审批工作流 --破坏性操作（发布、删除）需要通过带有HMAC签名回调URL的webhook通知进行人工批准。支持Feishu/Lark、通用webhook（Slack、Discord、自定义系统）或同时支持这两者。具有自动拒绝功能的可配置超时。
FIFO执行队列 --每个后端序列化执行，操作之间有随机延迟（可配置1-10分钟）。模仿人类互动模式。只读工具的旁路列表。
审计日志 --每个工具调用都记录在SQLite中：代理、工具、参数、ACL/速率限制/批准判断、队列位置、执行持续时间、结果。自动清除，可配置保留。
工具描述增强 --约束被注入到工具描述中，以便代理看到 [Rate:1/1d|ApprovalRequired] Publish post 而不是仅仅 Publish post代理人在决定做什么之前知道自己的局限性。
热重新加载 --通过以下方式更新配置而无需重新启动 POST /api/v1/config/reload.
单一二进制 --用Go编写，只有5个直接依赖项。运行在Raspberry Pi上。

安装

npm（建议MCP用户使用）

npx aegis-mcp-proxy config/aegis.yaml
# Or install globally:
npm install -g aegis-mcp-proxy
aegis-mcp-proxy config/aegis.yaml

预构建二进制文件

下载自 GitHub 发布:

tar xzf aegis_v*.tar.gz
./aegis config/aegis.yaml

码头工人

docker run --rm -v $(pwd)/config:/config ghcr.io/bigmoon-dev/aegis /config/aegis.yaml

去安装

需要Go 1.24+和CGO（gcc）：

CGO_ENABLED=1 go install github.com/bigmoon-dev/aegis/cmd/aegis@latest
aegis config/aegis.yaml

从源代码构建

git clone https://github.com/bigmoon-dev/Aegis.git
cd Aegis
make build
./aegis config/aegis.yaml

快速入门

2分钟内体验宙斯盾：

npx aegis-mcp-proxy demo

按照屏幕上的curl示例查看ACL过滤、速率限制、人工批准和审计日志记录。

准备好连接自己的MCP服务器了吗？选择您的代理：

导游	代理人	时间
Claude 代码指南	克劳德密码（人物）	5分钟
OpenClaw指南	OpenClaw	10分钟
通用代理指南	任何MCP兼容试剂	5分钟

中文版: 克劳德代码 · 龙虾 · 通用 Agent

交互式设置（建议新用户使用）

获得工作配置的最快方法：

./aegis setup
# or: npx aegis-mcp-proxy setup

向导将引导您完成以下操作：

后端URL --输入您的MCP服务器地址，Aegis连接并发现可用工具
按工具政策 --基于工具名称的智能默认值（只读工具获得无限访问权限，写/发布工具获得速率限制+批准，危险工具被拒绝）
代理配置 --自动检测已安装的代理，并将Aegis代理URL注入到其配置中
审批通知 --为审批请求传递配置Feishu/Lark或通用webhook URL（仅当工具需要审批时）。自动检测回调URL的本地IP

支持的代理：

代理	配置文件	检测
OpenClaw	`~/.openclaw/workspace/config/mcporter.json`	自动检测
克劳德代码	`~/.claude/mcp_servers.json`	自动检测
自定义	--	手动设置

向导创建 .bak 在修改任何代理配置之前进行备份，并在写入后验证JSON。如果同一后端已存在条目，则会提示解决冲突。

尝试交互式演示

在5分钟内体验所有Aegis功能，无需后端设置。只需要Node.js：

./aegis demo
# or: npx aegis-mcp-proxy demo

这将启动一个具有预配置策略的模拟MCP服务器+Aegis代理。终端打印curl命令来尝试每个功能：

步骤	发生了什么
`tools/list`	`admin_reset` 被ACL隐藏——只有4个工具可见
`echo`	通行无限制
`get_weather` ×4	前3个成功，第4个是限速(`-32002`)
`publish_post`	阻止，直到您通过管理层API批准
`list_posts`	绕过FIFO队列，立即返回
`audit/logs`	显示所有操作的完整审计跟踪

Raspberry Pi的交叉编译

# Requires a cross-compiler (e.g. aarch64-linux-gnu-gcc) for CGO/SQLite
CC=aarch64-linux-gnu-gcc make cross-rpi
scp aegis user@your-server:~/aegis/

# Or build directly on the server:
ssh user@your-server 'cd ~/aegis && make build'

配置

看 策略配置指南 有关编写策略规则的详细文档，包括字段解释、时间格式、策略交互和常见场景。

基本示例：

server:
  listen: ":18070"
  read_timeout: 300s
  write_timeout: 300s
  # api_token: "your-secret-token"   # Protect /api/v1/ endpoints

backends:
  my-tools:
    url: "http://localhost:8080/mcp"    # Your MCP tool server
    health_url: "http://localhost:8080/health"
    timeout: 120s

queue:
  my-tools:
    enabled: true
    delay_min: 60s                      # Min delay between operations
    delay_max: 600s                     # Max delay between operations
    max_pending: 50
    bypass_tools:                       # Skip queue (still rate-limited)
      - "health_check"
    global_rate_limits:                 # Across ALL agents
      risky_operation: { window: 1h, max_count: 10 }

agents:
  production-agent:
    display_name: "Production Agent"
    auth_token: "your-secret-token-here"  # Optional: require Bearer token auth
    backends:
      my-tools:
        allowed: true
        tool_denylist: ["dangerous_tool"]
        rate_limits:
          publish: { window: 24h, max_count: 1 }
        approval_required:
          - "publish"
          - "delete"

  dev-agent:
    display_name: "Dev Agent"
    backends:
      my-tools:
        allowed: true
        tool_denylist: ["publish", "delete", "dangerous_tool"]

approval:
  feishu:
    webhook_url: ""                     # Your Feishu/Lark webhook URL
  generic:
    webhook_url: ""                     # Any webhook URL (Slack, Discord, custom, etc.)
  timeout: 600s
  callback_base_url: "http://your-server:18070"

audit:
  db_path: "./data/audit.db"
  retention_days: 90

管道

每 tools/call 请求通过：

阶段	目的	拒绝
ACL	允许代理调用此工具吗？	JSON-RPC `-32001`
速率限制器	全局+每个代理滑动窗口检查	JSON-RPC `-32002`
审批门	通过webhook通知进行人工审批	JSON-RPC `-32004` （超时）
FIFO队列	具有随机延迟的序列化执行	JSON-RPC `-32003` （满）
转运商	后端MCP服务器的代理	后端错误
审计记录器	将所有内容记录到SQLite中	--

只有成功的呼叫才计入速率限制（失败的呼叫不消耗配额）。

管理API

当 server.api_token 已设置，全部 /api/v1/ 端点需要 Authorization: Bearer <token>。如果未设置，API将打开（适用于本地主机部署）。

GET  /health                           # Service + backend health
GET  /api/v1/queue/status              # Pending items per backend
GET  /api/v1/agents                    # Agent list with permissions
GET  /api/v1/agents/{id}/rate-limits   # Current usage vs limits (agent + global scope)
GET  /api/v1/approvals/pending         # Awaiting human decision
POST /api/v1/approvals/{id}/approve    # Approve via API
POST /api/v1/approvals/{id}/reject     # Reject via API
GET  /api/v1/audit/logs                # Query audit log (?limit=50&offset=0)
POST /api/v1/config/reload             # Hot reload configuration

运作原理

代理向发送MCP请求 http://aegis:18070/agents/{agent-id}/mcp
Aegis MCP从URL路径中识别代理
tools/list → 从后端获取，过滤被拒绝的工具，注入约束注释
tools/call → 贯穿整个管道（ACL→ 速率限制→ 批准→ 队列→ 转发→ 审计）
initialize, ping等等。 → 透明地通过
代理人只看到它被允许看到的东西，只能做它被允许做的事情

设计决策

决定	理由
MCP代理（非SDK/框架集成）	动态工具转发；零代码更改；可与任何MCP兼容的代理配合使用
SQLite（不是Redis）	最小依赖；持续审计追踪；资源利用率低
每个后端队列	共享一个帐户的所有代理都必须全局序列化
HMAC签名的审批回调	通过URL猜测防止未经授权的审批
UTC无处不在	在速率限制窗口计算中避免DST问题
全局+每个代理的费率限制	共享帐户的多代理累积频率控制

通用Webhook有效载荷

当 approval.generic.webhook_url 配置完毕后，Aegis会发送一个POST请求 Content-Type: application/json:

{
  "event": "approval_request",
  "id": "request-uuid",
  "agent_id": "production-agent",
  "tool_name": "publish",
  "arguments": "{...}",
  "created_at": "2026-03-12T10:00:00Z",
  "approve_url": "http://aegis:18070/callback/approval?id=xxx&action=approve&token=xxx",
  "reject_url": "http://aegis:18070/callback/approval?id=xxx&action=reject&token=xxx"
}

要批准或拒绝，请向相应的URL发出GET请求。Feishu和通用webhook都可以同时配置，都会收到通知。

发展

运行测试

# All tests
CGO_ENABLED=1 go test ./... -count=1

# With race detector (recommended)
CGO_ENABLED=1 go test -race ./... -count=1

# With coverage
CGO_ENABLED=1 go test -cover ./internal/...

测试使用临时SQLite数据库和内存配置，不需要外部依赖。CI运行 go test -race 在每次推送和拉取请求中。

安全

代理端点身份验证：设置 auth_token 配置中每个代理都需要 Authorization: Bearer <token> 上 /agents/{agentID}/mcp令牌必须至少包含16个字符。无代理 auth_token 保持开放（适合本地/演示使用）。 始终在生产中设置此项。
管理API认证：设置 server.api_token 在您的配置中需要 Authorization: Bearer <token> 在所有 /api/v1/ 端点。没有这个，任何可以访问端口的人都可以批准操作、查看审计日志和重新加载配置。 始终在生产中设置此项。
审批回访：由每个请求的HMAC-SHA256令牌保护（在启动时从随机的32字节密钥生成）。令牌通过恒定时间比较进行验证。
请求大小限制：传入请求的上限为1 MB，后端响应的上限为10 MB。
传输层安全：Aegis在纯HTTP上监听。对于生产环境，将其放置在反向代理（nginx、Caddy）后面或仅绑定到localhost。
HMAC密钥生命周期：HMAC签名密钥在启动时在内存中生成。重新启动Aegis将使所有待审批令牌无效。

需求

转到1.24+（SQLite启用了CGO）
作为后端的MCP兼容工具服务器

许可证

Apache 2.0

致谢

专为管理在真实平台上运行的人工智能代理而设计，源于社交媒体自动化风险控制方面来之不易的经验教训。

使用说明

宙斯盾MCP

为什么选择MCP代理？

特性

安装

npm（建议MCP用户使用）

预构建二进制文件

码头工人

去安装

从源代码构建

快速入门

交互式设置（建议新用户使用）

尝试交互式演示

Raspberry Pi的交叉编译

配置

管道

管理API

运作原理

设计决策

通用Webhook有效载荷

发展

运行测试

安全

需求

许可证

致谢

相关 MCP

搜索工具服务器

百度搜索MCP服务器

安全策略中间件

API安全网关

MCP工具验证平台

DnD 5e MCP服务器