Quickstart

This guide will take you from zero to a working AIP deployment in under 5 minutes. You’ll secure an MCP tool server with a policy and see AIP block an unauthorized action.

What you’ll learn:

Install the AIP Go proxy
Write your first policy file
Start the AIP proxy to protect an MCP server
See AIP block a dangerous operation in real-time

Prerequisites

Before starting, ensure you have:

Go 1.21+ installed (download here)
An MCP-compatible tool server (Docker MCP, Postgres MCP, or any custom MCP server)
Basic familiarity with YAML and command-line tools

Don’t have an MCP server? The examples below show how to secure common tools like Docker and file system operations.

Installation

Install the AIP Go Implementation

The reference implementation is available as a Go package:

# Clone the repository
git clone https://github.com/openagentidentityprotocol/aip-go.git
cd aip-go

# Build the binary
go build -o aip ./cmd/aip

# Verify installation
./aip --version

You should see output like:

AIP Proxy v0.1.0 (aip.io/v1alpha1)

Create Your First Policy File

Create a file called agent.yaml with a restrictive read-only policy:

agent.yaml

apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: read-only-agent
  version: "1.0.0"
spec:
  mode: enforce
  allowed_tools:
    - read_file
    - list_directory
    - git_status
  tool_rules:
    - tool: write_file
      action: block
    - tool: exec_command
      action: block
    - tool: delete_file
      action: block

What this policy does:

Allows only safe read operations: read_file, list_directory, git_status
Explicitly blocks dangerous operations: write_file, exec_command, delete_file
Uses enforce mode to actively block violations (not just log them)

Start the AIP Proxy

Now wrap your MCP server with AIP:

# Start AIP proxy pointing to your MCP server
aip --policy ./agent.yaml --target "python mcp_server.py"

You should see:

[AIP] Policy loaded: read-only-agent (v1.0.0)
[AIP] Mode: enforce
[AIP] Allowed tools: 3
[AIP] Proxy started on stdio transport
[AIP] Target: python mcp_server.py

See AIP in Action

Now let’s test the policy by attempting both allowed and blocked operations.

Test an Allowed Operation

Try a safe read operation:

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/tmp/test.txt"
    }
  }
}

Result: ✅ Request passes through to the MCP server.

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": "File contents here..."
  }
}

Test a Blocked Operation

Now try a dangerous write operation:

Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "write_file",
    "arguments": {
      "path": "/tmp/test.txt",
      "content": "malicious data"
    }
  }
}

Result: 🔴 AIP blocks the request.

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32001,
    "message": "Permission Denied: Tool 'write_file' is not allowed by policy"
  }
}

Your MCP server never received this request. The dangerous operation was blocked at the AIP proxy layer before reaching your infrastructure.

Check the Audit Log

Every decision is logged to aip-audit.jsonl:

cat aip-audit.jsonl | jq .

You’ll see structured audit events:

{
  "timestamp": "2026-03-03T10:15:30Z",
  "policy": "read-only-agent",
  "tool": "write_file",
  "decision": "BLOCK",
  "violation": true,
  "error_code": -32001,
  "arguments": {
    "path": "/tmp/test.txt"
  }
}

Filter for violations only:

cat aip-audit.jsonl | jq 'select(.violation == true)'

Example Policies

Here are real-world policy examples for common use cases:

Prompt Injection Defense

Protect against the GeminiJack attack class:

gemini-jack-defense.yaml

apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: gemini-jack-defense
spec:
  mode: enforce
  allowed_tools:
    - read_file
    - search_code
  tool_rules:
    # Block all external communication
    - tool: send_email
      action: block
    - tool: post_slack
      action: block
    - tool: http_request
      action: block
    
    # Block file system writes
    - tool: write_file
      action: block
    - tool: exec_command
      action: block
  
  dlp:
    patterns:
      - name: "Exfil URL"
        regex: "https?://[a-zA-Z0-9.-]+\\.(ngrok|requestbin|pipedream)"

Database Read-Only Access

Restrict SQL operations to SELECT queries only:

postgres-readonly.yaml

apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: postgres-readonly
spec:
  mode: enforce
  tool_rules:
    - tool: postgres_query
      action: allow
      allow_args:
        query: "^SELECT\\s+.*"  # Only SELECT queries
  
  dlp:
    patterns:
      - name: "SSN"
        regex: "\\b\\d{3}-\\d{2}-\\d{4}\\b"
      - name: "Credit Card"
        regex: "\\b(?:\\d{4}[- ]?){3}\\d{4}\\b"

Human-in-the-Loop for Sensitive Operations

Require user approval for destructive actions:

human-approval.yaml

apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: human-approval-required
spec:
  mode: enforce
  allowed_tools:
    - github_get_repo
    - github_list_pulls
  tool_rules:
    - tool: github_create_pr
      action: ask  # Native OS approval dialog
    - tool: github_merge_pr
      action: ask
    - tool: github_delete_repo
      action: block  # Never allowed

DLP Scanning for Secrets

Prevent accidental exposure of sensitive data:

dlp-scanning.yaml

apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: dlp-scanning
spec:
  mode: enforce
  allowed_tools:
    - read_file
    - search_files
  dlp:
    patterns:
      - name: "AWS Key"
        regex: "(AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}"
      - name: "GitHub Token"
        regex: "ghp_[a-zA-Z0-9]{36}"
      - name: "Private Key"
        regex: "-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----"

When a secret is detected, it’s redacted:

Before: "Your key is AKIAIOSFODNN7EXAMPLE"
After:  "Your key is [REDACTED:AWS Key]"

Testing in Monitor Mode

Before enforcing a new policy in production, test it with monitor mode:

test-policy.yaml

apiVersion: aip.io/v1alpha1
kind: AgentPolicy
metadata:
  name: test-policy
spec:
  mode: monitor  # Log violations but don't block
  allowed_tools:
    - safe_tool

Monitor mode behavior:

Policy violations are logged to aip-audit.jsonl
Requests are allowed through even if they violate policy
Use this to test new policies without breaking production workflows

Review the audit log to see what would have been blocked:

cat aip-audit.jsonl | jq 'select(.violation == true)'

Once confident, change mode: monitor to mode: enforce.

Next Steps

Policy Reference

Complete YAML schema, validation rules, and advanced examples

Architecture Deep Dive

Understand Layer 1 (Identity) and Layer 2 (Enforcement)

Core Concepts

Learn about AATs, registries, and the two-layer model

AIP Specification

Formal protocol definition for implementers

Troubleshooting

Policy validation fails at startup

Common causes:

Invalid apiVersion (must be aip.io/v1alpha1)
Empty allowed_tools with no tool_rules
Invalid regex in allow_args

Run validation:

aip --policy ./agent.yaml --validate

All requests are blocked

Check your policy:

Ensure mode: enforce is intentional (use monitor for testing)
Verify tool names exactly match what your MCP server reports
Check audit log for the actual tool names being called

Enable verbose logging:

aip --policy ./agent.yaml --target "..." --verbose

DLP patterns not matching

Regex must use double-escaped backslashes in YAML: \\d not \d
Test regex patterns outside AIP first
Check the audit log for dlp_events to see what was scanned

Human-in-the-loop dialogs not appearing

Ensure action: ask is set in tool_rules
On Linux, requires a display server (X11/Wayland)
On macOS, requires terminal to have accessibility permissions
Check AIP logs for “approval prompt sent”

Get Help

GitHub Discussions

Ask questions and share your AIP setup

Report Issues

Found a bug? Let us know

FAQ

Common questions answered

Contributing

Help build AIP

Get Started

Core Concepts

Guides

Deployment

Prerequisites

Installation

See AIP in Action

Example Policies

Prompt Injection Defense

Database Read-Only Access

Human-in-the-Loop for Sensitive Operations

DLP Scanning for Secrets

Testing in Monitor Mode

Next Steps

Policy Reference

Architecture Deep Dive

Core Concepts

AIP Specification

Troubleshooting

Get Help

GitHub Discussions

Report Issues

FAQ

Contributing

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Deployment

​Prerequisites

​Installation

​See AIP in Action

​Example Policies

​Prompt Injection Defense

​Database Read-Only Access

​Human-in-the-Loop for Sensitive Operations

​DLP Scanning for Secrets

​Testing in Monitor Mode

​Next Steps

Policy Reference

Architecture Deep Dive

Core Concepts

AIP Specification

​Troubleshooting

​Get Help

GitHub Discussions

Report Issues

FAQ

Contributing

Build docs developers (and LLMs) love

Prerequisites

Installation

See AIP in Action

Example Policies

Prompt Injection Defense

Database Read-Only Access

Human-in-the-Loop for Sensitive Operations

DLP Scanning for Secrets

Testing in Monitor Mode

Next Steps

Troubleshooting

Get Help