Audit Logging

MCPlexer logs every tool call that flows through the gateway. Audit records capture the full lifecycle of each request — from routing to execution to response — with sensitive parameters automatically redacted.

What Gets Logged

Every tool call produces an audit record with the following fields:

Name	Type	Default	Description
`id`	string	—	Unique audit record ID
`timestamp`	datetime	—	When the tool call was made
`session_id`	string	—	Client session that made the call
`client_type`	string	—	Client type (e.g., claude-desktop, cursor, api)
`model`	string	—	AI model that initiated the call
`workspace_id`	string	—	Workspace the call was routed through
`workspace_name`	string	—	Human-readable workspace name
`subpath`	string	—	Client's working directory relative to workspace root
`tool_name`	string	—	Namespaced tool name (e.g., github__list_repos)
`params_redacted`	JSON	—	Tool arguments with sensitive values replaced by [REDACTED]
`route_rule_id`	string	—	Route rule that matched the call
`downstream_server_id`	string	—	Target downstream server
`downstream_instance_id`	string	—	Specific process instance that handled the call
`auth_scope_id`	string	—	Auth scope used for credential injection
`status`	string	—	Outcome: success, error, or blocked
`error_code`	string	—	Error code if the call failed
`error_message`	string	—	Error message if the call failed
`latency_ms`	integer	—	Round-trip time in milliseconds
`response_size`	integer	—	Response payload size in bytes
`cache_hit`	boolean	—	Whether the response was served from cache

Parameter Redaction

MCPlexer automatically redacts sensitive parameters before writing them to the audit log. Redaction is controlled by auth scope hints — each auth scope can declare which parameter names contain secrets.

yaml

auth_scopes:
  - id: github-token
    redact_params:
      - token
      - authorization
      - password
      - secret

When a tool call uses this auth scope, any matching parameter names in the arguments will be replaced with [REDACTED] in the params_redacted field. The original values are never persisted.

Default redaction

Even without explicit hints, MCPlexer redacts common secret patterns like token, key, secret, password, and authorization by default.

Query API

Retrieve audit records with powerful filtering and pagination:

GET/api/v1/audit

Query audit records with filters. Returns paginated results ordered by timestamp descending.

Query parameters: session_id, workspace_id, tool_name, status, after, before, limit, offset

Filter Parameters

Name	Type	Default	Description
`session_id`	string	—	Filter by client session ID
`workspace_id`	string	—	Filter by workspace
`tool_name`	string	—	Filter by tool name (exact match)
`status`	string	—	Filter by outcome: success, error, or blocked
`after`	datetime	—	Only records after this timestamp (RFC 3339)
`before`	datetime	—	Only records before this timestamp (RFC 3339)
`limit`	integer	50	Maximum number of records to return
`offset`	integer	0	Number of records to skip for pagination

Example

terminal

curl "http://localhost:8080/api/v1/audit?workspace_id=ws-prod&status=error&limit=10" # Returns recent errors in the production workspace

Real-Time Stream

Subscribe to audit events as they happen via Server-Sent Events:

GET/api/v1/audit/stream

SSE stream of audit events. Emits a new event for every tool call that completes.

terminal

curl -N "http://localhost:8080/api/v1/audit/stream" # data: {"id":"aud-abc123","tool_name":"github__list_repos","status":"success","latency_ms":142} # data: {"id":"aud-def456","tool_name":"slack__post_message","status":"error","error_code":"auth_failed"}

The SSE stream powers the dashboard's real-time activity feed and can be consumed by monitoring tools, alerting systems, or custom integrations.

Dashboard Metrics

The MCPlexer dashboard provides rich analytics built on top of audit data:

Time Series

A timeline chart showing tool call volume, error rates, and latency trends over configurable time windows (1h, 6h, 24h, 7d).

Tool Leaderboard

Ranked list of the most-called tools across all workspaces, with call counts, error rates, and average latency for each.

Server Health

Per-downstream-server breakdown showing uptime, error rates, average latency, and active instance counts.

Error Breakdown

Categorized view of errors by error code and downstream server, making it easy to spot patterns and recurring failures.

Cache Stats

Hit/miss rates for the tool call cache, showing how much traffic is being served from cache vs. forwarded to downstream servers.

Export audit data

Use the query API with wide time ranges and high limits to export audit data for external analysis. Combine with after and before filters for precise time windows.

Tool Approvals Caching