Skip to main content

Audit Logs

The audit log records every access decision made by the permission engine. Use it to monitor activity, debug permission issues, and detect unauthorized access attempts.

Audit Log

Understanding Audit Entries​

Each log entry records:

FieldDescription
TimeTimestamp of the access decision (UTC)
TargetThe file path, command, or tool name being accessed
AccessThe access level requested (read, write, execute, active)
ResultWhether the request was allowed or denied
ReasonHuman-readable explanation of the decision
UserThe authenticated user ID (from MCP_USER_ID)
Sub-agentClaude Code sub-agent ID (from CLAUDE_AGENT_ID, audit-only)

Filtering​

The audit log supports four filter dimensions:

Free-text search across target, command, result, and reason fields.

Access Level Filter​

Filter by the access level requested:

  • All access: No filter
  • Read: Only read attempts
  • Write: Only write attempts
  • None: Only denied-by-default attempts

Result Filter​

Filter by decision outcome:

  • All results: No filter
  • Allowed: Only successful access
  • Denied: Only denied access

Date Range Filter​

Filter by when the event occurred:

  • All time: No filter
  • Last hour: Events from the past 60 minutes
  • Today: Events since midnight (server time)
  • This week: Events from the past 7 days

Active filters are highlighted. Click "Clear filters" to reset all filters.

Pagination​

The audit log is paginated. Use the "Prev" and "Next" buttons at the bottom to navigate pages. The footer shows total entries and current page.

The page size is configurable in Settings (50, 100, or 150 entries per page).

Detail Panel​

Click any row to expand a detail panel showing all fields for that entry in a structured grid layout:

  • Timestamp, server, target type, target path
  • Command (if applicable), access requested, result, reason
  • User ID and sub-agent ID (if present)

Audit Log Format​

Logs are stored as JSON Lines (one JSON object per line) at /var/log/mcp/<server>/audit.log:

{"ts": "2026-01-15T12:00:00Z", "server": "ubuntu-mcp", "target_type": "file", "target": "/var/log/nginx/access.log", "access": "read", "result": "allowed", "reason": "", "user_id": "alice", "tool": "ubuntu_read_file"}
{"ts": "2026-01-15T12:01:00Z", "server": "ubuntu-mcp", "target_type": "command", "target": "systemctl restart postgresql", "access": "execute", "result": "denied", "reason": "command not in allowlist", "user_id": "alice", "tool": "ubuntu_exec"}

This format is append-only and easily consumable by log processors like jq, grep, or centralized logging systems.

Log Rotation​

By default, audit logs grow indefinitely. Set up log rotation on the host:

# /etc/logrotate.d/mcp-audit
/var/log/mcp/*/audit.log {
daily
rotate 30
compress
delaycompress
missingok
notifempty
create 0640 root root
}

Monitoring​

For production deployments, consider forwarding audit logs to a centralized system:

# Forward to syslog
tail -f /var/log/mcp/*/audit.log | logger -t mcp-audit

# Or use filebeat/fluentd for ELK stack integration

Denied entries are especially important to monitor: they may indicate misconfiguration, a user trying to access something they should not, or an attempted attack.