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

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

@require_scopes(["finance:refund"])

Refund <= $500
→ ALLOW

Refund > $500
→ APPROVAL_REQUIRED

Customer data export
→ APPROVAL_REQUIRED

Customer deletion
→ DENY

APPROVED
→ EXECUTED

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.

crm:read

finance:refund

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

agent:manage

agent:manage

finance:refund

PENDING
APPROVED
DENIED
EXECUTED

PENDING
   ↓
APPROVED
   ↓
EXECUTED

PENDING
   ↓
DENIED

DENIED
reviewed_by = Human Administrator
approved_by = null

ALLOW
DENY
APPROVAL_REQUIRED
APPROVED

{
  "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

requesting_identity
action
payload
reason
status

reviewed_by
reviewed_at

approved_by
approved_at

executed_at

identity
action
decision
required_scope
reason
approval_id
metadata
created_at

database/schema.sql

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

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

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

pip install poetry
poetry install

.env.example

.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=

crm:read
crm:write

support:read
support:write

finance:read
finance:refund

customer:export

agent:manage

python -m src.server

http://localhost:3001/

http://localhost:3001/mcp

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

npx -y @modelcontextprotocol/inspector

Transport:
Streamable HTTP

URL:
http://localhost:3001/mcp

Authorization: Bearer <ACCESS_TOKEN>

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