Audit Logging

Audit Logging

MCP Gateway Registry provides comprehensive audit logging for compliance, security monitoring, and operational visibility. All API requests and MCP server access events are logged to MongoDB/DocumentDB with automatic retention management.

Overview

Audit logging captures two types of events:

1. Registry API Access - All REST API requests to the Registry (/api/*, /v0.1/*)
2. MCP Server Access - All MCP protocol requests proxied through the Gateway

Sensitive data such as authentication tokens, session cookies, and passwords are never logged. Credentials are masked to show only the last 6 characters as a hint for debugging.

Security and Privacy

Data That Is NOT Logged

The following sensitive data is explicitly excluded from audit logs:

• Authentication tokens (Bearer tokens, JWT tokens)
• Session cookies (Cookie header values)
• Passwords (form fields, query parameters)
• API keys (full values)
• Refresh tokens
• Authorization header values

Data Masking

When credential hints are logged for debugging purposes, they are automatically masked:

• Full token: eyJhbGciOiJSUzI1NiIsInR5... becomes ***zI1Ni
• Tokens shorter than 6 characters become ***

Query parameters with sensitive names (token, password, key, secret, api_key, etc.) are automatically masked.

Event Schemas

Registry API Access Event

Logged for every REST API request to the Registry.

{
  "timestamp": "2026-02-06T10:30:00.000Z",
  "log_type": "registry_api_access",
  "version": "1.0",
  "request_id": "abc123-def456-...",
  "correlation_id": null,
  "identity": {
    "username": "john.doe@example.com",
    "auth_method": "oauth2",
    "provider": "keycloak",
    "groups": ["mcp-registry-admin", "developers"],
    "scopes": ["registry-admins"],
    "is_admin": true,
    "credential_type": "session_cookie",
    "credential_hint": "***abc123"
  },
  "request": {
    "method": "POST",
    "path": "/api/servers",
    "query_params": {},
    "client_ip": "192.168.1.100",
    "forwarded_for": "10.0.0.1",
    "user_agent": "Mozilla/5.0...",
    "content_length": 1024
  },
  "response": {
    "status_code": 201,
    "duration_ms": 45.32,
    "content_length": 512
  },
  "action": {
    "operation": "create",
    "resource_type": "server",
    "resource_id": "my-mcp-server",
    "description": "Create new MCP server"
  },
  "authorization": {
    "decision": "ALLOW",
    "required_permission": "servers:write",
    "evaluated_scopes": ["registry-admins"]
  }
}

MCP Server Access Event

Logged for every MCP protocol request proxied through the Gateway.

{
  "timestamp": "2026-02-06T10:30:00.000Z",
  "log_type": "mcp_server_access",
  "version": "1.0",
  "request_id": "xyz789-...",
  "correlation_id": null,
  "identity": {
    "username": "ai-agent@example.com",
    "auth_method": "jwt_bearer",
    "provider": "keycloak",
    "groups": [],
    "scopes": ["mcp-server-cloudflare-docs"],
    "is_admin": false,
    "credential_type": "bearer_token",
    "credential_hint": "***def456"
  },
  "mcp_server": {
    "name": "cloudflare-docs",
    "path": "/cloudflare-docs",
    "version": "1.0.0",
    "proxy_target": "http://internal-mcp-server:8080/mcp"
  },
  "mcp_request": {
    "method": "tools/call",
    "tool_name": "search_docs",
    "resource_uri": null,
    "mcp_session_id": "session-123",
    "transport": "streamable-http",
    "jsonrpc_id": "1"
  },
  "mcp_response": {
    "status": "success",
    "duration_ms": 123.45,
    "error_code": null,
    "error_message": null
  }
}

Data Fields Reference

Identity Fields

Action Fields (Registry API only)

MCP Request Fields (MCP Access only)

Data Retention

Audit logs are automatically expired using MongoDB/DocumentDB TTL (Time-To-Live) indexes.

Default Retention

• Default retention period: 7 days
• TTL index field: timestamp

Configuring Retention

Set the AUDIT_LOG_MONGODB_TTL_DAYS environment variable to customize retention:

# Keep logs for 30 days
export AUDIT_LOG_MONGODB_TTL_DAYS=30

# Keep logs for 90 days (compliance requirement)
export AUDIT_LOG_MONGODB_TTL_DAYS=90

The TTL index is created when running the DocumentDB initialization script:

./scripts/init-documentdb.sh

Important Notes

• TTL indexes run approximately once per minute in MongoDB/DocumentDB
• Documents may persist slightly longer than the TTL value
• Changing the TTL requires dropping and recreating the index with --recreate flag
• For compliance requirements, consider also streaming logs to a long-term archive

Storage

MongoDB Collection

Audit events are stored in the audit_events_{namespace} collection with the following indexes:

Storage Sizing

Typical event sizes:

• Registry API event: ~1-2 KB
• MCP Server Access event: ~1-2 KB

Estimated storage (without compression):

• 1,000 requests/day for 7 days: ~14 MB
• 10,000 requests/day for 30 days: ~600 MB
• 100,000 requests/day for 90 days: ~18 GB

Viewing Audit Logs

Admin UI

Administrators can view audit logs in the Registry UI:

1. Navigate to Settings > Audit > Audit Logs
2. Select log stream: Registry API or MCP Access
3. Apply filters (time range, username, operation, status)
4. Click any row to view full event details
5. Export filtered results as JSONL or CSV

API Access

Query audit events programmatically:

# Get recent Registry API events
curl -H "Authorization: Bearer $TOKEN" \
  "https://registry.example.com/api/audit/events?stream=registry_api&limit=50"

# Get MCP access events for a specific user
curl -H "Authorization: Bearer $TOKEN" \
  "https://registry.example.com/api/audit/events?stream=mcp_access&username=john.doe"

# Export events as JSONL
curl -H "Authorization: Bearer $TOKEN" \
  "https://registry.example.com/api/audit/export?stream=registry_api&format=jsonl"

MongoDB/DocumentDB Direct Query

// Find all events for a user in the last 24 hours
db.audit_events_default.find({
  "identity.username": "john.doe@example.com",
  "timestamp": { $gte: new Date(Date.now() - 24*60*60*1000) }
}).sort({ timestamp: -1 })

// Count events by operation type
db.audit_events_default.aggregate([
  { $match: { log_type: "registry_api_access" } },
  { $group: { _id: "$action.operation", count: { $sum: 1 } } },
  { $sort: { count: -1 } }
])

// Find failed MCP requests
db.audit_events_default.find({
  "log_type": "mcp_server_access",
  "mcp_response.status": "error"
})

Configuration

Environment Variables

Non-Blocking Design

Audit logging is designed to never impact request processing:

• Logging happens asynchronously after the response is sent
• Failures in audit logging are logged as warnings but don't fail requests
• High-volume scenarios use batched writes (if enabled)

Compliance Considerations

SOC 2 / ISO 27001

Audit logs support compliance requirements by capturing:

• Who: User identity with auth method and provider
• What: Operation performed with resource details
• When: Precise UTC timestamp
• Where: Client IP and forwarded-for headers
• Outcome: Success/failure status with error details

GDPR

• User identifiers (usernames) are logged for accountability
• No PII beyond usernames is captured
• Logs can be exported and deleted per data subject requests
• TTL-based retention supports data minimization

Additional Recommendations

For production compliance deployments:

1. Stream audit logs to a SIEM (Splunk, Datadog, etc.) for long-term retention
2. Set up alerts for suspicious patterns (failed auths, privilege escalation)
3. Regularly review admin actions in the audit log
4. Document your retention policy and ensure TTL matches it

Troubleshooting

Logs Not Appearing

1. Verify audit logging is enabled: AUDIT_LOG_ENABLED=true
2. Check MongoDB connection: ensure the Registry can write to the database
3. Look for warnings in Registry logs: grep "audit" registry.log

TTL Not Working

1. Verify the TTL index exists: db.audit_events_default.getIndexes()
2. Note that MongoDB TTL runs approximately every 60 seconds
3. Documents may persist up to 60 seconds beyond their expiration time

Missing Events

1. Check if the request completed (cancelled requests may not be logged)
2. Verify the log stream filter matches the event type
3. For MCP access, ensure the path is not an API path (starts with /api/)