Skip to content

MCP_MONITORING.md

Latest commit

 

History

History
338 lines (264 loc) · 8.3 KB

MCP_MONITORING.md

File metadata and controls

338 lines (264 loc) · 8.3 KB

MCP (Model Context Protocol) Monitoring with Guardian Agent

Overview

Guardian Agent provides governance and compliance monitoring for MCP (Model Context Protocol) communications between AI agents. When deployed as a sidecar, Guardian Agent can:

  • Monitor all MCP protocol messages (tool calls, resource access, prompts)
  • Validate tool calls and resource access against policies
  • Block unauthorized operations (optional)
  • Audit all MCP interactions with immutable logs
  • Detect PII in tool arguments and resource contents
  • Enforce compliance policies on MCP traffic

Architecture

┌─────────────────────────────────────┐
│ MCP Client Agent                    │
│  ┌──────────────────────────────┐   │
│  │ MCP Client                   │   │
│  │                              │   │
│  │ MCP Protocol                 │   │
│  │ ──────────────→              │   │
│  └──────────┬───────────────────┘   │
│             │                        │
│  ┌──────────▼───────────────────┐   │
│  │ Guardian Agent Sidecar       │   │
│  │  • Parse MCP messages        │   │
│  │  • Validate tool calls       │   │
│  │  • Validate resources        │   │
│  │  • Apply policies            │   │
│  │  • Audit all traffic         │   │
│  └──────────┬───────────────────┘   │
│             │                        │
│  ┌──────────▼───────────────────┐   │
│  │ MCP Server                   │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘

MCP Protocol Support

Guardian Agent monitors the following MCP methods:

Tool Calls (tools/call)

  • Validates tool name against allowed/blocked patterns
  • Extracts and validates tool arguments
  • Can block unauthorized tool executions
  • Logs all tool calls for audit

Resource Access (resources/read)

  • Validates resource URI against allowed/blocked patterns
  • Checks resource types (file://, https://, etc.)
  • Can block access to sensitive resources
  • Logs all resource access for compliance

Prompts (prompts/get)

  • Monitors prompt access (for audit)
  • Can validate prompt names against policies

Configuration

Basic MCP Monitoring

mcp:
  enabled: true
  monitor_tool_calls: true
  monitor_resources: true
  monitor_prompts: true

Policy-Based Validation

mcp:
  enabled: true
  validate_tool_calls: true
  validate_resources: true
  
  # Block dangerous tools
  blocked_tool_patterns:
    - "^.*delete.*$"
    - "^.*exec.*$"
    - "^.*eval.*$"
    - "^.*system.*$"
  
  # Block sensitive resources
  blocked_resource_patterns:
    - "^file:///etc/.*$"
    - "^file:///root/.*$"
    - "^file://.*/\.(env|key|pem|secret)$"

Whitelist Mode

mcp:
  enabled: true
  block_unauthorized_tools: true
  block_unauthorized_resources: true
  
  # Only allow specific tools
  allowed_tool_patterns:
    - "^read_file$"
    - "^search_web$"
    - "^calculate$"
  
  # Only allow specific resources
  allowed_resource_patterns:
    - "^file:///tmp/.*$"
    - "^file:///var/data/.*$"
    - "^https://public-api\\.example\\.com/.*$"

API Endpoints

Monitor MCP Message

POST /mcp/monitor
Content-Type: application/json

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

Response:

{
  "allowed": true,
  "reason": "Tool 'read_file' is allowed",
  "should_block": false,
  "metadata": {
    "tool_name": "read_file",
    "tool_arguments": {"path": "/tmp/test.txt"}
  }
}

Get MCP Configuration

GET /mcp/config

Update MCP Configuration

POST /mcp/config
Content-Type: application/json

{
  "blocked_tool_patterns": ["^.*delete.*$"],
  "block_unauthorized_tools": true
}

Get MCP Statistics

GET /mcp/stats

Response:

{
  "messages_monitored": 1523,
  "tool_calls_validated": 892,
  "resources_validated": 631,
  "blocked_messages": 12
}

Deployment Patterns

1. Sidecar Pattern (Recommended)

Guardian Agent runs as a sidecar container alongside your MCP agent:

containers:
- name: mcp-agent
  image: your-mcp-agent:latest
  env:
  - name: MCP_SERVER_URL
    value: "http://localhost:8081"  # Guardian proxy

- name: guardian
  image: guardian:latest
  ports:
  - containerPort: 8081  # MCP proxy port
  env:
  - name: MCP_MODE
    value: "proxy"

2. Proxy Pattern

Guardian Agent acts as an MCP proxy between client and server:

# Client connects to Guardian instead of server
MCP_SERVER_URL=http://guardian:8081

# Guardian forwards to actual MCP server
GUARDIAN_MCP_TARGET=http://mcp-server:8000

3. Middleware Pattern

Guardian Agent intercepts MCP messages at the network level (with service mesh integration).

Compliance Integration

Audit Logging

All MCP messages are logged with:

  • Timestamp
  • Direction (client→server or server→client)
  • Method name
  • Tool/resource information
  • Validation result
  • Policy decisions

PII Detection

Guardian Agent can detect PII in:

  • Tool call arguments
  • Resource contents (when accessed)
  • Prompt responses

Retention Policies

MCP audit logs are subject to retention policies:

  • GDPR: 90 days (default)
  • HIPAA: 6 years (configurable)
  • SOC 2: 1 year (configurable)

Example Use Cases

1. Prevent File System Attacks

mcp:
  blocked_tool_patterns:
    - "^.*delete.*$"
    - "^.*write_file$"  # Block writes to sensitive locations
  blocked_resource_patterns:
    - "^file:///etc/.*$"
    - "^file:///home/.*$"

2. Allow Only Specific Tools

mcp:
  block_unauthorized_tools: true
  allowed_tool_patterns:
    - "^read_file$"
    - "^search_web$"
    - "^calculate.*$"

3. Monitor External API Calls

mcp:
  monitor_resources: true
  blocked_resource_patterns:
    - "^https://.*internal.*$"  # Block internal APIs
    - "^https://.*admin.*$"     # Block admin endpoints

Integration Example

use guardian::{MCPMonitor, MCPMonitorConfig, MCPDirection};

// Create MCP monitor
let config = MCPMonitorConfig {
    enabled: true,
    monitor_tool_calls: true,
    validate_tool_calls: true,
    blocked_tool_patterns: vec![r"^.*delete.*$".to_string()],
    ..Default::default()
};

let monitor = MCPMonitor::new(config);

// Parse and monitor MCP message
let mcp_json = r#"{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "delete_file",
        "arguments": {"path": "/tmp/test.txt"}
    }
}"#;

let parsed = monitor.parse_message(mcp_json, MCPDirection::ClientToServer)?;
let result = monitor.monitor_message(&parsed).await?;

if result.should_block {
    // Block the MCP message
    return Err("Tool call blocked by policy");
}

// Allow the message to proceed
// Forward to MCP server...

Benefits

  1. Governance: Enforce policies on all MCP interactions
  2. Compliance: Complete audit trail for MCP communications
  3. Security: Block unauthorized tool calls and resource access
  4. Observability: Monitor all MCP traffic in one place
  5. PII Protection: Detect and redact sensitive data in MCP messages
  6. Compliance Reporting: Include MCP audit logs in compliance reports

Next Steps

  • Implement MCP proxy mode (forward messages to server)
  • Add MCP server emulation for testing
  • Integrate with OPA for advanced policy validation
  • Add MCP-specific compliance framework mappings
  • Support MCP streaming responses
  • Add MCP session tracking

MCP monitoring enables governance and compliance for AI agent communications. Monitor, validate, and audit all MCP interactions with Guardian Agent.