AgentGuard MCP

Identity-Aware Authorization for AI Agents

AgentGuard MCP is the protected Model Context Protocol authorization backend for AgentGuard.

It gives AI runtimes distinct machine identities, enforces least-privilege OAuth permissions, evaluates contextual security policy, pauses high-risk actions for authenticated human approval, binds approvals back to the requesting identity, prevents approval replay, and records security decisions in Supabase.

Frontend Repository:
https://github.com/haisamar/agentguard

Live Product:
https://agentguard-eight.vercel.app

Public Demo:
https://agentguard-eight.vercel.app/demo

Why AgentGuard MCP?

Giving an AI agent access to a tool is easy.

Controlling:

which agent can use which tool, under what conditions, and when a human must intervene

is harder.

AgentGuard separates that problem into distinct security layers.

• Auth0 establishes machine and human identities.

• OAuth scopes define which classes of operations each machine identity may request.

• AgentGuard policy evaluates the context of the specific action.

• Human approval creates a separate authority boundary for sensitive operations.

• Approval-bound execution ensures approval can only be used by the original requesting identity.

• Replay protection prevents an executed approval from being reused.

• Supabase persists approval state and audit events.

• MCP exposes protected tools to agent runtimes.

The design principle is:

An AI agent being authenticated should not mean it has unlimited authority.

Architecture

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

    E{"Required Scope?"}
    G{"Contextual Policy"}

    F["DENY"]
    H["ALLOW"]
    I["APPROVAL_REQUIRED"]

    J[("Supabase Approval")]
    K["Auth0<br/>Human Login"]
    L{"Human Decision"}

    M["APPROVED"]
    N["DENIED"]

    O["Original Agent<br/>Requests Execution"]
    P["Identity + Approval<br/>Verification"]
    Q["Execute Once"]

    R[("Audit Events")]

    A --> B
    B --> C
    C --> D

    D --> E

    E -->|"Missing"| F
    E -->|"Granted"| G

    G -->|"Low Risk"| H
    G -->|"Sensitive"| I
    G -->|"Forbidden"| F

    I --> J
    J --> K
    K --> L

    L -->|"Approve"| M
    L -->|"Deny"| N

    M --> O
    O --> P
    P --> Q

    F --> R
    H --> R
    I --> R
    N --> R
    Q --> R

Security Model

AgentGuard uses distinct machine and human security principals.

Machine Identities

Each autonomous runtime receives a separate Auth0 Machine-to-Machine identity.

Example roles:

This means a Sales Agent cannot issue refunds simply because another agent can.

The caller's OAuth access token determines which permissions belong to that identity.

Related MCP server: gov-mcp

Human Identities

Human administrators authenticate separately through an Auth0 Regular Web Application.

Machine identity and human identity are intentionally separate.

Example:

Finance Agent
   ↓
Authenticated Machine Identity
   ↓
finance:refund
   ↓
Contextual Policy
   ↓
APPROVAL_REQUIRED
   ↓
Human Administrator
   ↓
Authenticated Human Identity
   ↓
APPROVED
   ↓
Original Finance Agent Executes

This creates a separation of duties between:

request authority

and:

approval authority

Authorization Layers

AgentGuard applies multiple authorization layers before sensitive execution occurs.

1. Authentication

The MCP server validates the Auth0 access token and establishes the caller identity.

Authentication answers:

Who is this runtime?

It does not automatically answer:

What is this runtime allowed to do?

2. OAuth Scope Authorization

Protected MCP tools declare which OAuth permissions are required.

Example:

@require_scopes(["finance:refund"])

If the caller does not possess:

finance:refund

the action is denied immediately.

Example:

Sales Agent
   ↓
Authenticated
   ↓
issue_refund
   ↓
Missing finance:refund
   ↓
DENY

Contextual policy is not evaluated.

Human review is not reached.

3. Contextual Policy

Passing the OAuth scope boundary does not guarantee autonomous execution.

AgentGuard evaluates the specific context of the requested action.

Current demonstration rules include:

Refund <= $500
→ ALLOW

Refund > $500
→ APPROVAL_REQUIRED

Customer data export
→ APPROVAL_REQUIRED

Customer deletion
→ DENY

This allows AgentGuard to distinguish:

Can this identity request refunds?

from:

Should this particular refund execute autonomously?

4. Human Approval

Sensitive operations are persisted in the approval store.

The operation pauses with:

APPROVAL_REQUIRED

A separately authenticated human can then approve or deny the request through the AgentGuard dashboard.

5. Approval-Bound Execution

An approved action may only be executed by the machine identity that originally requested it.

Before execution, AgentGuard verifies:

approval exists

status == APPROVED

requesting identity matches current identity

approval action matches requested action

approval has not already executed

Only after those checks can the protected action continue.

6. Replay Protection

After successful execution:

APPROVED
   ↓
EXECUTED

A second execution attempt is denied.

This prevents the same approval from authorizing the same protected action multiple times.

MCP Tools

The AgentGuard prototype exposes five protected MCP tools.

search_accounts

Search CRM account data.

Required permission:

crm:read

Example:

Sales Agent
crm:read
   ↓
search_accounts
   ↓
ALLOW

issue_refund

Request a refund.

Required permission:

finance:refund

Policy:

amount <= $500
→ ALLOW

amount > $500
→ APPROVAL_REQUIRED

Example low-risk request:

Finance Agent
finance:refund
   ↓
issue_refund($100)
   ↓
ALLOW

Example sensitive request:

Finance Agent
finance:refund
   ↓
issue_refund($750)
   ↓
APPROVAL_REQUIRED

Example scope failure:

Sales Agent
no finance:refund
   ↓
issue_refund($750)
   ↓
DENY

list_pending_approvals

Lists approval requests waiting for review.

Required permission:

agent:manage

approve_action

Administrative MCP approval path used during machine-runtime testing.

Required permission:

agent:manage

The portfolio application also contains a preferred human approval workflow through the separately authenticated Next.js administrator dashboard.

execute_approved_refund

Executes an already approved refund.

Required permission:

finance:refund

AgentGuard verifies that the approval belongs to the current machine identity before allowing execution.

Approval Lifecycle

Approval records use four states:

PENDING
APPROVED
DENIED
EXECUTED

Successful flow:

PENDING
   ↓
APPROVED
   ↓
EXECUTED

Denied flow:

PENDING
   ↓
DENIED

Review information and approval information are represented separately.

This allows a denied request to correctly represent:

status       = DENIED
reviewed_by  = Human Administrator
approved_by  = null

without incorrectly treating the reviewer as an approver.

Demo Simulator

The repository includes:

src/demo_simulator.py

The simulator creates deterministic security records for the protected AgentGuard administrator dashboard.

It is separate from the public browser simulation.

Scenario 1 — OAuth Scope Denial

Sales Agent
   ↓
Attempts $750 refund
   ↓
Missing finance:refund
   ↓
DENY

The generated event includes authorization-failure metadata.

Scenario 2 — Autonomous Allow

Finance Agent
   ↓
Requests $100 refund
   ↓
finance:refund granted
   ↓
Policy satisfied
   ↓
ALLOW

Scenario 3 — Approval Required

Finance Agent
   ↓
Requests $750 refund
   ↓
finance:refund granted
   ↓
Refund > $500
   ↓
APPROVAL_REQUIRED

Scenario 4 — Human Approved Execution

Human Administrator
   ↓
Approves Request
   ↓
APPROVED

The original Finance Agent then executes:

Finance Agent
   ↓
execute_approved_refund
   ↓
Approval verified
   ↓
ALLOW
   ↓
EXECUTED

Scenario 5 — Pending Review

The simulator also creates a $900 refund request and intentionally leaves it pending.

Finance Agent
   ↓
$900 refund
   ↓
APPROVAL_REQUIRED
   ↓
PENDING

This gives the administrator dashboard an active request that can be reviewed interactively.

Run the Simulator

Activate the virtual environment:

.\.venv\Scripts\Activate.ps1

Then:

python -m src.demo_simulator

Audit Events

AgentGuard records security decisions in Supabase.

Important event decisions include:

ALLOW
DENY
APPROVAL_REQUIRED
APPROVED

Audit metadata may include:

• granted scopes

• missing scopes

• authorization failures

• approval IDs

• requesting identity

• action context

• human reviewer

• resource identifiers

• replay attempts

Example authorization failure:

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

OAuth access tokens, client secrets, and credentials should never be written into the audit log.

Database

AgentGuard uses Supabase/PostgreSQL.

The two primary tables are:

approvals
audit_events

approvals

Stores sensitive operations and their review lifecycle.

Important fields include:

id
requesting_identity
action
payload
reason
status

reviewed_by
reviewed_at

approved_by
approved_at

created_at
executed_at

audit_events

Stores security decisions and execution context.

Important fields include:

id
identity
action
decision
required_scope
reason
approval_id
metadata
created_at

Row Level Security is enabled.

No public browser policies are intentionally created for sensitive AgentGuard records.

Trusted server-side components use protected server credentials.

Repository Structure

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

Environment Configuration

AgentGuard MCP reads environment variables from .env.

Example:

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=

Never commit .env.

Auth0 API Permissions

The AgentGuard Auth0 API defines permissions including:

crm:read
crm:write

support:read
support:write

finance:read
finance:refund

customer:export

agent:manage

Each Machine-to-Machine application should receive only the permissions needed for its role.

Local Setup

Requirements

• Python 3.10+

• Auth0 tenant

• Auth0 Machine-to-Machine applications

• Auth0 API configured for AgentGuard

• Supabase project

Clone:

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

Create Virtual Environment

Windows PowerShell

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

macOS / Linux

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

Install Dependencies

Using Poetry:

pip install poetry
poetry install

Configure:

.env

using:

.env.example

as the template.

Run the MCP Server

From the repository root:

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

Default server:

http://localhost:3001

MCP endpoint:

http://localhost:3001/mcp

OAuth protected-resource metadata:

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

Keep this terminal running while testing the MCP backend.

Auth0 OAuth Metadata

AgentGuard publishes protected-resource metadata for the MCP resource.

The server integrates with the configured Auth0 issuer and audience.

Machine clients obtain OAuth access tokens from Auth0 and send them to AgentGuard MCP as bearer tokens.

The authorization middleware validates the identity and exposes the granted scopes to protected MCP tools.

MCP Inspector Note

Some MCP Inspector OAuth workflows attempt Dynamic Client Registration.

The Auth0 tenant used for this prototype does not enable Dynamic Client Registration.

Because of that, the Inspector's automatic registration workflow is not the primary validation path for this project.

The MCP server itself still exposes OAuth protected-resource metadata and validates Auth0 access tokens.

AgentGuard's recruiter-facing demonstration is provided through:

Public deterministic simulation
+
Protected administrator console
+
Real MCP authorization implementation

Frontend

The companion AgentGuard frontend is:

https://github.com/haisamar/agentguard

Live product:

https://agentguard-eight.vercel.app

Public demo:

https://agentguard-eight.vercel.app/demo

The frontend provides:

• public product experience

• deterministic security simulation

• technical trace explorer

• Auth0-protected administrator console

• machine identity inventory

• human operator identity

• approval controls

• persisted authorization trace explorer

• security activity feed

• audit-event inspection

• approval history

Public Demo vs Backend Records

These are intentionally different systems.

Public Demo

Deterministic
Client-side
Read-only
No sensitive identifiers
No Supabase security records exposed

Protected Administrator Dashboard

Persisted Supabase approvals
Persisted audit events
Real administrator authentication
Human approve / deny controls
Sensitive identity context

This separation makes the project publicly reviewable without exposing privileged security data.

Security Principles Demonstrated

Authentication ≠ Authorization

An authenticated machine can still be denied.

Least Privilege

Every runtime receives only the OAuth scopes needed for its role.

Contextual Authorization

A valid permission does not always mean immediate execution.

Separation of Duties

Machines request sensitive actions while humans independently approve them.

Human-in-the-Loop Authorization

Autonomous authority stops at defined policy thresholds.

Approval-Bound Execution

Approval belongs to a specific requesting identity and action.

Replay Protection

An executed approval cannot be reused.

Auditability

Security decisions are persisted with identity and authorization context.

Design Principle

AgentGuard is based on one core idea:

An AI agent being authenticated should not mean it has unlimited authority.

Authentication proves:

who the agent is

OAuth scopes determine:

what category of operations it may request

Contextual policy determines:

whether that exact operation should execute autonomously

Human approval creates:

a separate authority boundary for sensitive decisions

Current Scope

AgentGuard MCP is a security portfolio prototype rather than a production IAM platform.

Intentional boundaries currently include:

• demonstration policies are defined in application code

• machine identities are mapped to demonstration roles

• human administrator authorization uses an application-level allowlist

• policy management is not exposed through a dedicated control plane

• audit events are not cryptographically immutable

• distributed locking for production concurrency is outside the prototype scope

• approval expiration is not implemented

• backend deployment is designed primarily for controlled testing

These limitations are documented rather than hidden.

Possible Extensions

Future versions could add:

• Auth0 role-based administrator access

• policy-as-code

• policy versioning

• centralized agent identity registry

• workload identity federation

• delegated authorization

• resource-level authorization

• approval expiration

• time-limited privileges

• organization isolation

• step-up authentication

• signed audit records

• SIEM export

• policy simulation

• dynamic risk scoring

• additional MCP tools

• production MCP deployment

• distributed execution locking

Project Motivation

AgentGuard explores a question:

What does identity security look like when the user is not always a human?

Autonomous AI runtimes can increasingly:

call APIs
use tools
change records
trigger workflows
take financial actions

That makes identity and authorization critical at the agent layer.

AgentGuard applies familiar IAM concepts such as:

machine identity
OAuth scopes
least privilege
separation of duties
human approval
auditability

to autonomous agent execution.

Related Project

AgentGuard Frontend

https://github.com/haisamar/agentguard

Live Product

https://agentguard-eight.vercel.app

Interactive Demo

https://agentguard-eight.vercel.app/demo