What can you do with this server?

PolicyGuard is an MCP server that provides security governance for AI agents through policy-based access control, incident tracking, and compliance monitoring. Core Capabilities: * Policy Enforcement: Create and manage security policies with pattern matching (e.g., delete_\*, \*_production) to control agent actions. Policies support conditions (tool patterns, trust levels) and actions (allow, deny, require_approval) * Action Validation: Validate agent actions before execution using multi-layered evaluation of suspension status, denied/allowed lists, and policy rules via the validate_action tool * Agent Management: Register agents with configurable trust levels (low, medium, high, admin), tool permissions, and metadata * Audit Logging: Query comprehensive audit logs of all validations filtered by agent, action type, status, and time range (1h to 30d) with unique action IDs for correlation * Incident Management: Report and track security incidents (policy violations, suspicious activity, unauthorized access, data exfiltration) with severity levels (low, medium, high, critical), evidence collection, and auto-suspension for critical events * Compliance Monitoring: Generate compliance reports with security health metrics, active incidents, policy summaries, violations, and recommendations * Pattern-Based Security: Use wildcard patterns for flexible policy application to tool names * Human Approval Workflows: Require manual review for high-risk actions * Kubernetes Integration: Deploy via Helm chart and integrate with kagent for Kubernetes-native AI agent management * Multi-Protocol Support: Run in HTTP mode or via MCP protocol for integration with various AI platforms

Which integrations are available for this server?

Includes a Helm chart for Kubernetes-native deployment, enabling declarative management of the PolicyGuard service and its security policies. Provides security and governance for AI agents within Kubernetes environments, supporting declarative agent management through kagent integration and custom resource definitions (CRDs). Supports integration with Ollama as a local LLM provider for running AI agents governed by PolicyGuard security rules.

How do I use PolicyGuard?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PolicyGuard Check if agent-alpha is authorized to execute 'delete_records' on production" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

PolicyGuard

Security & Governance MCP Server for AI Agents

Python 3.10+ MCP License: MIT

PolicyGuard is an MCP (Model Context Protocol) server that provides policy-based access control, incident tracking, and compliance monitoring for AI agents.

Note: This project demonstrates working integration with kagent (AI agent platform) and can be extended with kgateway (API gateway) for additional network-level security.

Overview

As AI agents become more autonomous, organizations need controls to govern their behavior. PolicyGuard is my first MCP server project - built to explore how security and governance can be implemented at the MCP layer.

The Problem

AI agents can call any tool they have access to. Without governance:

Agents might perform destructive operations
No audit trail of agent actions
No way to enforce security policies
No visibility into compliance

The Solution

PolicyGuard adds a security layer that agents call before taking action:

User Request → AI Agent → PolicyGuard (validate_action) → Allowed/Denied

Features

Feature	Description
Policy Enforcement	Validate actions against security rules
Trust Levels	low, medium, high, admin hierarchy
Pattern Matching	Wildcard patterns like `delete_`, `_production`
Auto-Registration	Unknown agents get minimal trust
Incident Tracking	Automatic violation logging
Audit Trail	Complete action history
Compliance Dashboard	Security metrics at a glance

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         AI Agent / LLM                          │
│                                                                 │
│  "Before any action, call validate_action to check permission" │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ MCP Protocol
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     PolicyGuard MCP Server                      │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  validate   │  │   create    │  │   report    │             │
│  │   action    │  │   policy    │  │  incident   │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  register   │  │  get_audit  │  │    get      │             │
│  │   agent     │  │    log      │  │ compliance  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌───────────────────┐
                    │   JSON Storage    │
                    │   (policies,      │
                    │    agents,        │
                    │    audit_log,     │
                    │    incidents)     │
                    └───────────────────┘

MCP Tools

PolicyGuard exposes 6 tools via MCP:

1. `validate_action` ⭐ Primary Tool

Check if an action is allowed before executing it.

{
  "action_type": "tool_call",
  "target": "delete_records",
  "agent_id": "my-agent"
}

Response:

{
  "action_id": "act_a1b2c3d4e5f6",
  "allowed": false,
  "reason": "Delete operations require admin trust level"
}

2. `register_agent`

{
  "agent_id": "data-processor",
  "name": "Data Agent",
  "trust_level": "medium"
}

3. `create_policy`

Create security rules.

{
  "policy_id": "block-deletes",
  "name": "Block Deletes",
  "rules": "[{\"condition\": {\"tool_pattern\": \"delete_*\"}, \"action\": \"deny\"}]"
}

4. `get_audit_log`

Query action history.

5. `get_compliance_status`

Get security dashboard metrics.

6. `report_incident`

Manually report security incidents.

Quick Start

Prerequisites

Python 3.10+
pip

Local Installation

# Clone
git clone https://github.com/PrateekKumar1709/policyguard.git
cd policyguard

# Setup
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Run
python src/main.py

Test the Tools

import json
from src.tools.validate_action import validate_action
from src.tools.register_agent import register_agent

# Register an agent
result = json.loads(register_agent.fn(
    agent_id="test-agent",
    name="Test Agent",
    trust_level="medium"
))
print(f"Registered: {result['agent_id']}")

# Validate an action
result = json.loads(validate_action.fn(
    action_type="tool_call",
    target="read_data",
    agent_id="test-agent"
))
print(f"Allowed: {result['allowed']}")

HTTP Mode

python src/main.py --transport http --port 8000

Kubernetes Deployment

PolicyGuard includes a Helm chart for Kubernetes deployment.

Using Kind

# Create cluster
kind create cluster --name policyguard

# Build and load image
docker build -t policyguard:latest .
kind load docker-image policyguard:latest --name policyguard

# Deploy
kubectl create namespace policyguard
helm install policyguard ./helm/policyguard -n policyguard

# Verify
kubectl get pods -n policyguard

Port Forward

kubectl port-forward -n policyguard svc/policyguard 8000:8000

Testing

Unit Tests

pytest tests/ -v

Test Results

tests/test_tools.py::TestValidateAction::test_allow_read_for_low_trust PASSED
tests/test_tools.py::TestValidateAction::test_deny_delete_for_low_trust PASSED
tests/test_tools.py::TestValidateAction::test_allow_delete_for_admin PASSED
tests/test_tools.py::TestValidateAction::test_deny_suspended_agent PASSED
tests/test_tools.py::TestRegisterAgent::test_register_new_agent PASSED
tests/test_tools.py::TestCreatePolicy::test_create_valid_policy PASSED
... (16 tests total)
============================== 16 passed ==============================

E2E Test Output

[1/6] register_agent      ✅ SUCCESS
[2/6] create_policy       ✅ SUCCESS  
[3/6] validate_action     ✅ ALLOWED (read_data)
[4/6] validate_action     ✅ DENIED (delete_records)
[5/6] report_incident     ✅ SUCCESS
[6/6] get_compliance_status ✅ SUCCESS

ALL 6 MCP TOOLS WORKING!

kagent Integration

PolicyGuard integrates with kagent for Kubernetes-native AI agent management.

Screenshots

Agent List - PolicyGuard agent registered and ready:

Agent List

Agent Tools - 6 PolicyGuard MCP tools available:

Agent Tools

Compliance Dashboard - Asking for compliance status:

Compliance Chat

Policy Validation - Action denied based on policy:

Validation Chat

Quick Setup

# 1. Install kagent CRDs
helm install kagent-crds ./kagent-reference/helm/kagent-crds -n kagent --create-namespace

# 2. Install kagent with Ollama (free local LLM)
helm upgrade --install kagent ./kagent-reference/helm/kagent -n kagent \
  --set providers.default=ollama \
  --set providers.ollama.model=qwen2.5:1.5b \
  --set tag=0.7.13

# 3. Deploy PolicyGuard
helm install policyguard ./helm/policyguard -n policyguard --create-namespace

# 4. Create RemoteMCPServer
kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: RemoteMCPServer
metadata:
  name: policyguard
  namespace: kagent
spec:
  protocol: STREAMABLE_HTTP
  url: http://policyguard.policyguard:8000/mcp
  timeout: 30s
EOF

# 5. Create PolicyGuard Agent
kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: policyguard-agent
  namespace: kagent
spec:
  description: "Security agent using PolicyGuard"
  type: Declarative
  declarative:
    modelConfig: "default-model-config"
    systemMessage: |
      You are a PolicyGuard Security Agent. Use the PolicyGuard tools to:
      - validate_action: Check if actions are allowed
      - register_agent: Register new agents
      - create_policy: Define security rules
      - get_compliance_status: View compliance dashboard
    tools:
    - type: McpServer
      mcpServer:
        name: policyguard
        kind: RemoteMCPServer
        apiGroup: kagent.dev
        toolNames:
        - validate_action
        - register_agent
        - create_policy
        - get_audit_log
        - get_compliance_status
        - report_incident
EOF

Verified Working

# Check status
$ kubectl get agents,remotemcpservers -n kagent
NAME                TYPE          READY   ACCEPTED
policyguard-agent   Declarative   True    True

NAME          PROTOCOL          URL                                       ACCEPTED
policyguard   STREAMABLE_HTTP   http://policyguard.policyguard:8000/mcp   True

# Invoke agent via CLI
$ kagent invoke -t "Get compliance status" --agent policyguard-agent

Response:
- Security Posture: Healthy
- Total Policies: 1, Enabled: 1  
- Total Incidents: 0
- Agents Registered: 0

# Test validation
$ kagent invoke -t "Can test-agent delete the database?" --agent policyguard-agent

Response:
The action delete_database was not allowed for test-agent.
Reason: Delete operations require admin trust level.

Access kagent UI

kubectl port-forward -n kagent svc/kagent-ui 8080:8080
# Open http://localhost:8080

Security Model

Trust Levels

Level	Score	Use Case
`low`	1	Unknown agents, read-only
`medium`	2	Verified agents
`high`	3	Trusted agents
`admin`	4	Full access

Policy Rules

{
  "condition": {
    "tool_pattern": "delete_*",
    "trust_level_below": "admin"
  },
  "action": "deny",
  "message": "Delete requires admin"
}

Evaluation Order

Agent suspended? → DENY
Tool in denied list? → DENY
Tool not in allowed list? → DENY
Policy match? → Apply rule
Default → ALLOW

Project Structure

policyguard/
├── helm/
│   └── policyguard/          # Helm chart
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
├── src/
│   ├── main.py               # Entry point
│   ├── core/
│   │   ├── server.py         # MCP server
│   │   └── utils.py          # Utilities
│   └── tools/
│       ├── validate_action.py
│       ├── register_agent.py
│       ├── create_policy.py
│       ├── get_audit_log.py
│       ├── get_compliance_status.py
│       └── report_incident.py
├── tests/
│   └── test_tools.py         # 16 unit tests
├── Dockerfile
├── pyproject.toml
└── README.md

Technologies Used

FastMCP - Python MCP server SDK
Pydantic - Data validation
Helm - Kubernetes packaging
pytest - Testing

Future Improvements

Database backend (PostgreSQL)
Web dashboard UI
Prometheus metrics
RBAC integration
Policy versioning

License

MIT License

Hackathon

MCP_HACK//26 - "MCP & AI Agents Starter Track"

This is my first MCP server project! I built PolicyGuard to learn:

How MCP servers work
How to expose tools to AI agents
How to deploy MCP servers on Kubernetes
How security/governance can be implemented at the MCP layer

What I Built

✅ 6 MCP tools for security governance
✅ Policy engine with pattern matching
✅ Trust level system
✅ Audit logging and incident tracking
✅ Helm chart for Kubernetes
✅ 16 unit tests
✅ kagent integration examples