AgentGuard MCP

AI 에이전트를 위한 신원 인식(identity-aware) 권한 부여.

AgentGuard MCP는 보호된 Model Context Protocol 서버로, AI 에이전트에 고유한 머신 신원(machine identity)을 부여하고, 최소 권한 OAuth 권한을 적용하며, 상황 기반 권한 부여 정책을 적용하고, 실행 전에 민감한 작업을 인증된 인간의 승인을 위해 일시 중지합니다.

이는 AgentGuard의 권한 부여 백엔드입니다.

라이브 제품: https://agentguard-eight.vercel.app

왜 AgentGuard인가?

AI 에이전트에게 도구 접근 권한을 주는 것은 쉽습니다.

어떤 에이전트가 어떤 도구를, 어떤 조건에서 사용할 수 있고, 언제 인간이 개입해야 하는지를 제어하는 것은 더 어렵습니다.

AgentGuard는 이러한 관심사를 분리합니다:

• Auth0은 머신 및 인간 신원을 인증합니다.

• OAuth 스코프는 각 머신 신원이 요청할 수 있는 권한을 정의합니다.

• AgentGuard 정책은 작업의 맥락을 평가합니다.

• 인간 승인은 고위험 작업을 통제합니다.

• Supabase는 승인 상태와 보안 감사 이벤트를 저장합니다.

• MCP는 보호된 도구를 AI 런타임에 노출합니다.

따라서 에이전트는 인증되었다고 해서 모든 작업을 수행할 수 있다고 자동으로 신뢰되지는 않습니다.

Related MCP server: gov-mcp

아키텍처

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 신원을 받습니다.

데모 신원 예시:

Sales Agent는 다른 에이전트가 환불을 할 수 있다는 이유만으로 환불을 발행할 수 없습니다.

권한 부여 계층은 보호된 도구가 실행되기 전에 호출자의 OAuth 액세스 토큰이 담고 있는 스코프를 확인합니다.

인간 신원

인간 운영자는 AgentGuard 대시보드의 Auth0 Regular Web Application을 통해 별도로 인증합니다.

머신 신원과 인간 신원은 의도적으로 분리됩니다.

따라서 민감한 요청은 다음과 같은 형태일 수 있습니다:

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 Machine-to-Machine 애플리케이션

• 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

Machine-to-Machine 애플리케이션은 해당 역할에 필요한 권한만 받아야 합니다.

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

Authorization 헤더에 Auth0 Machine-to-Machine 액세스 토큰 사용:

Authorization: Bearer <ACCESS_TOKEN>

액세스 토큰을 커밋하거나 노출하지 마십시오.

프론트엔드

함께 제공되는 AgentGuard 제품 인터페이스는 여기에서 확인할 수 있습니다:

저장소

https://github.com/haisamar/agentguard

라이브 데모

https://agentguard-eight.vercel.app

다음을 제공합니다:

• 공개 제품 페이지

• 민감 정보가 제거된 공개 보안 데모

• Auth0으로 보호되는 관리자 대시보드

• 인간 승인/거부 컨트롤

• 머신 vs 인간 신원 시각화

• 권한 부여 추적 탐색기

• 대화형 보안 이벤트 검사

• 승인 기록

기술

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 역할 기반 인간 관리

• policy-as-code

• 정책 버전 관리

• 에이전트 신원 레지스트리

• 워크로드 신원 페더레이션

• 위임된 권한 부여

• 시간 제한 승인

• 리소스 수준 권한 부여

• 승인 만료

• 조직 수준 격리

• 서명된 감사 이벤트

• SIEM 내보내기

• 정책 시뮬레이션

• 프로덕션 MCP 배포

• 추가 MCP 도구 및 리소스 서버

관련 프로젝트

AgentGuard 프론트엔드:

https://github.com/haisamar/agentguard