flowchart LR
    A[AI Agent] --> B[Auth0 Machine Identity]
    B --> C[OAuth Access Token]
    C --> D[AgentGuard MCP Server]

    D --> E{Required Scope?}

    E -->|Missing| F[DENY]
    E -->|Granted| G[Contextual Policy]

    G -->|Low Risk| H[ALLOW]
    G -->|Sensitive| I[APPROVAL_REQUIRED]
    G -->|Forbidden| F

    I --> J[(Supabase Approval)]
    J --> K[Auth0 Human Login]
    K --> L{Human Decision}

    L -->|Approve| M[APPROVED]
    L -->|Deny| N[DENIED]

    M --> O[Agent Retries Approved Action]
    O --> P[Identity + Approval Verification]
    P --> Q[Execute Once]

    F --> R[(Audit Events)]
    H --> R
    I --> R
    N --> R
    Q --> R

安全模型

AgentGuard 使用两种不同的身份类别。

机器身份

每个自主运行时都会获得一个独立的 Auth0 机器对机器（Machine-to-Machine）身份。

示例演示身份：

运行时	用途	授予的作用域
销售代理	营收运营	`crm:read`、`crm:write`、`support:read`
财务代理	财务运营	`crm:read`、`finance:read`、`finance:refund`
管理运行时	管理自动化	`agent:manage`

销售代理不能仅仅因为另一个代理可以退款就执行退款操作。

授权层会在受保护工具执行之前检查调用方 OAuth 访问令牌所携带的作用域。

人类身份

人类操作员通过 AgentGuard 仪表板中的 Auth0 常规 Web 应用单独进行身份验证。

机器身份和人类身份被有意地分离开来。

因此，一个敏感请求可能看起来像这样：

Finance Agent
    ↓
Authenticated machine identity
    ↓
finance:refund scope
    ↓
Contextual policy
    ↓
APPROVAL_REQUIRED
    ↓
Authenticated human administrator
    ↓
APPROVED
    ↓
Finance Agent executes approved action

授权层级

AgentGuard 分层应用授权。

1. 身份验证

MCP 服务器验证 Auth0 访问令牌并确定调用方的身份。

2. OAuth 作用域授权

受保护的工具声明调用它们所需的作用域。

示例：

@require_scopes(["finance:refund"])

如果调用方不具备所需的作用域，执行将立即停止。

3. 上下文策略

通过 OAuth 检查并不自动意味着可以执行。

AgentGuard 会评估所请求操作的上下文。

当前的演示规则包括：

Refund <= $500
→ ALLOW

Refund > $500
→ APPROVAL_REQUIRED

Customer data export
→ APPROVAL_REQUIRED

Customer deletion
→ DENY

4. 人工审批

敏感操作会被写入审批存储并暂停执行。

经过单独身份验证的人类可以通过 AgentGuard 仪表板批准或拒绝该请求。

5. 绑定审批的执行

已批准的操作只能由最初请求该操作的机器身份来执行。

AgentGuard 会检查：

审批是否存在
审批状态是否为 APPROVED
审批是否属于发起请求的身份
审批操作是否与所请求的工具匹配
审批是否尚未被执行过

6. 重放保护

成功执行之后：

APPROVED
→ EXECUTED

第二次执行尝试将被拒绝，并记录为安全事件。

演示的安全场景

该项目包含三个持久化的场景，这些场景也可见于公开的 AgentGuard 演示中。

人工已批准

Finance Agent
→ finance:refund scope verified
→ requests $750 refund
→ policy requires approval
→ human administrator approves
→ Finance Agent executes
→ ALLOW
→ approval becomes EXECUTED

人工已拒绝

Finance Agent
→ finance:refund scope verified
→ requests $750 refund
→ policy requires approval
→ human administrator denies
→ Finance Agent attempts execution
→ DENY

作用域被阻止

Sales Agent
→ attempts issue_refund
→ missing finance:refund
→ DENY

Contextual policy is never evaluated.
Human review is never reached.

这展示了以下概念之间的区别：

身份验证
授权
上下文策略
人工控制

MCP 工具

当前演示暴露了五个受保护的 MCP 工具。

`search_accounts`

搜索 CRM 账户。

所需作用域：

crm:read

`issue_refund`

根据策略请求或执行退款。

所需作用域：

finance:refund

策略：

amount <= $500 → ALLOW
amount > $500  → APPROVAL_REQUIRED

`list_pending_approvals`

列出等待审核的审批请求。

所需作用域：

agent:manage

`approve_action`

用于机器运行时测试的管理性 MCP 审批路径。

所需作用域：

agent:manage

该组合应用还支持通过受 Auth0 保护的 Next.js 仪表板进行首选的人工审批路径。

`execute_approved_refund`

执行已获批准的退款。

所需作用域：

finance:refund

服务器会在执行前验证该审批是否属于发起调用的机器身份。

审批生命周期

审批记录使用四种状态：

PENDING
APPROVED
DENIED
EXECUTED

典型的成功生命周期：

PENDING
   ↓
APPROVED
   ↓
EXECUTED

被拒绝的生命周期：

PENDING
   ↓
DENIED

审核和审批是分开存储的。

这使得 AgentGuard 能够表示：

DENIED
reviewed_by = Human Administrator
approved_by = null

而不会错误地将人工拒绝视为批准。

审计事件

AgentGuard 将授权和策略决策记录在 Supabase 中。

示例事件包括：

ALLOW
DENY
APPROVAL_REQUIRED
APPROVED

安全元数据可以包括：

授予的作用域
缺失的作用域
授权失败
审批 ID
发起请求的身份
操作上下文
重放尝试
人工审核者
账户/资源标识符

作用域失败示例：

{
  "action": "issue_refund",
  "decision": "DENY",
  "required_scope": "finance:refund",
  "reason": "Missing required scopes: ['finance:refund']",
  "metadata": {
    "granted_scopes": [
      "crm:read",
      "crm:write",
      "support:read"
    ],
    "missing_scopes": [
      "finance:refund"
    ],
    "security_event": "authorization_failure"
  }
}

密钥和访问令牌绝不应写入审计日志。

仓库结构

agentguard-mcp/
│
├── database/
│   └── schema.sql
│
├── src/
│   ├── auth0/
│   │   ├── __init__.py
│   │   ├── authz.py
│   │   ├── errors.py
│   │   └── middleware.py
│   │
│   ├── approvals.py
│   ├── audit.py
│   ├── config.py
│   ├── database.py
│   ├── policy.py
│   ├── server.py
│   ├── tools.py
│   └── __init__.py
│
├── .env.example
├── .gitignore
├── pyproject.toml
└── README.md

数据库

AgentGuard 目前使用 Supabase/Postgres 来存储：

`approvals`

存储敏感请求及其审核生命周期。

重要字段包括：

requesting_identity
action
payload
reason
status

reviewed_by
reviewed_at

approved_by
approved_at

executed_at

`audit_events`

存储安全决策和执行上下文。

重要字段包括：

identity
action
decision
required_scope
reason
approval_id
metadata
created_at

两个表都启用了行级安全（Row Level Security）。

未创建任何公开的浏览器策略。

受信任的 AgentGuard 服务器组件使用仅限服务器端的凭据访问数据库。

参见：

database/schema.sql

本地设置

要求

Python 3.10+
Auth0 租户
Supabase 项目
Auth0 机器对机器应用
为 MCP 资源配置的 Auth0 API

克隆

git clone https://github.com/haisamar/agentguard-mcp.git
cd agentguard-mcp

创建虚拟环境

Windows：

python -m venv .venv
.\.venv\Scripts\Activate.ps1

macOS/Linux：

python -m venv .venv
source .venv/bin/activate

安装依赖

使用 Poetry：

pip install poetry
poetry install

或者，如果愿意，也可以手动安装所需的依赖。

配置环境

复制：

.env.example

到：

.env

并配置你自己的凭据。

切勿提交 .env 文件。

必需的环境变量

AUTH0_DOMAIN=
AUTH0_AUDIENCE=http://localhost:3001/
MCP_SERVER_URL=http://localhost:3001/
PORT=3001

SALES_AGENT_CLIENT_ID=
SALES_AGENT_CLIENT_SECRET=

FINANCE_AGENT_CLIENT_ID=
FINANCE_AGENT_CLIENT_SECRET=

ADMIN_AGENT_CLIENT_ID=
ADMIN_AGENT_CLIENT_SECRET=

SUPABASE_URL=
SUPABASE_SECRET_KEY=

Auth0 API 权限

AgentGuard API 当前定义的权限包括：

crm:read
crm:write

support:read
support:write

finance:read
finance:refund

customer:export

agent:manage

机器对机器应用应仅获得其角色所需的权限。

运行 MCP 服务器

从仓库根目录：

python -m src.server

默认服务器：

http://localhost:3001/

MCP 端点：

http://localhost:3001/mcp

受保护资源元数据：

http://localhost:3001/.well-known/oauth-protected-resource

使用 MCP Inspector 进行测试

启动 MCP Inspector：

npx -y @modelcontextprotocol/inspector

使用以下方式连接：

Transport:
Streamable HTTP

URL:
http://localhost:3001/mcp

在授权头中使用 Auth0 机器对机器访问令牌：

Authorization: Bearer <ACCESS_TOKEN>

切勿提交或暴露访问令牌。

前端

配套的 AgentGuard 产品界面可在此处获取：

仓库

https://github.com/haisamar/agentguard

在线演示

https://agentguard-eight.vercel.app

它提供：

公开产品页面
经过脱敏处理的公开安全演示
受 Auth0 保护的管理员仪表板
人工批准/拒绝控件
机器身份与人类身份可视化
授权追踪浏览器
交互式安全事件检查
审批历史记录

技术栈

AgentGuard 结合了：

Auth0
OAuth 2.0
Model Context Protocol
Python
FastMCP
Starlette
Supabase / PostgreSQL
Next.js
Human-in-the-loop authorization

设计原则

AgentGuard 基于一个简单的理念：

AI 代理通过身份验证并不意味着它拥有无限的权限。

身份验证证明代理是谁。

OAuth 作用域决定它可以请求哪些类别的操作。

上下文策略决定该特定操作是否可以在无人干预的情况下自主执行。

人工审批为高风险决策提供了独立的身份边界。

当前范围

AgentGuard 是一个作品集安全原型，而非生产级 IAM 平台。

当前有意包含的限制包括：

演示策略规则在代码中定义
机器身份映射到演示角色
MCP 后端设计用于受控/本地部署
人工管理员授权目前使用应用级管理员白名单
策略管理尚未通过控制平面暴露
审计事件的不可变性未在数据库层强制执行
并发执行的分布式锁不在当前演示范围内

这些边界被有意地记录在案，而非隐藏起来。

可能的扩展

未来版本可以增加：

基于 Auth0 角色的人工管理
策略即代码
策略版本控制
代理身份注册表
工作负载身份联合
委托授权
限时审批
资源级授权
审批过期
组织级隔离
签名审计事件
SIEM 导出
策略模拟
生产级 MCP 部署
更多 MCP 工具和资源服务器

AgentGuard MCP

为什么选择 AgentGuard？

架构

安全模型

机器身份

人类身份

授权层级

1. 身份验证

2. OAuth 作用域授权

3. 上下文策略

4. 人工审批

5. 绑定审批的执行

6. 重放保护

演示的安全场景

人工已批准

人工已拒绝

作用域被阻止

MCP 工具

search_accounts

issue_refund

list_pending_approvals

approve_action

execute_approved_refund

审批生命周期

审计事件

仓库结构

数据库

approvals

audit_events

本地设置

要求

克隆

创建虚拟环境

安装依赖

配置环境

必需的环境变量

Auth0 API 权限

运行 MCP 服务器

使用 MCP Inspector 进行测试

前端

技术栈

设计原则

当前范围

可能的扩展

相关项目

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Secure MCP-gRPC

gov-mcp

Clinical MCP Server

agent-security-gateway

`search_accounts`

`issue_refund`

`list_pending_approvals`

`approve_action`

`execute_approved_refund`

`approvals`

`audit_events`