Skip to main content
Version: Next

Audit Logs

Audit Logs give you visibility into every action your agents perform through MCPX. When an agent uses a tool or a configuration changes, MCPX records a structured audit event so you can trace, debug, and verify activity across your system. They provide clear records of tool usage, traceable configuration changes, and reliable data for debugging and compliance. Logging is enabled by default and can be configured to control write intervals, storage location, and retention.

MCPX records two event types, tool_used and config_applied.

Tool usage event (tool_used)​

Triggered whenever an agent invokes a tool. Payload fields include:

  • toolName: the name of the tool called
  • targetServerName: the server or service that handled the request
  • args: the input arguments passed to the tool
  • consumerTag: optional tag identifying the consumer or agent
Tool Used Example Log
{"timestamp":"2025-10-28T13:52:46.201Z","createdAt":"2025-10-28T13:52:48.806Z","eventType":"tool_used","payload":{"toolName":"slack_list_channels","targetServerName":"slack","args":{"limit":20},"consumerTag":"Claude"}}

Configuration update event (config_applied)​

Triggered whenever MCPX applies or reloads configuration. Payload fields include:

  • version: configuration version number
  • config: the full configuration object that was applied
Configuration Update Example Log
{"timestamp":"2025-10-28T13:51:42.495Z","createdAt":"2025-10-28T13:51:43.733Z","eventType":"config_applied","payload":{"config":{"permissions":{"default":{"_type":"default-allow","block":[]},"consumers":{}},"toolGroups":[{"name":"Database_and_file_operations","services":{"supabase":["search_docs","list_tables","list_migrations","apply_migration","execute_sql","get_project_url","get_anon_key","generate_typescript_types"]}}],"auth":{"enabled":false},"toolExtensions":{"services":{}}},"version":1,"lastModified":"2025-10-28T13:51:42.495Z"}}
note

Each entry includes two timestamps:

  • timestamp: when the event actually occurred
  • createdAt: when MCPX wrote the event to disk

Configuration​

Audit logging is controlled through the following environment variables:

ENABLE_AUDIT_LOG​

Type: boolean or string ("true"/"false")
Default: true
Required: Yes
Enables or disables audit logging

AUDIT_LOG_FLUSH_INTERVAL_IN_SEC​

Type: seconds
Default: 5
Required: No
Number of seconds to wait before flushing logs to disk

AUDIT_LOG_DIR​

Type: path
Default: <cwd>/audit-logs
Required: No
Directory where logs are written. When running MCPX in Docker, the default file path is /lunar/packages/mcpx-server/audit-logs/audit-2025-10-29T10.jsonl. Audited events are automatically grouped by hour and written to separate files, meaning a new log file is generated each hour at the configured path.

AUDIT_LOG_RETENTION_HOURS​

Type: num
Default: 336 (14 days)
Required: No
How long to retain log files before cleanup

Best practices​

  • Keep ENABLE_AUDIT_LOG=true in production to maintain full visibility.
  • If you need tighter real-time tracking, reduce AUDIT_LOG_FLUSH_INTERVAL_IN_SEC; if you want to reduce disk I/O, increase it.
  • When running in Docker, mount AUDIT_LOG_DIR to a persistent volume so logs survive container restarts.
  • Set retention (AUDIT_LOG_RETENTION_HOURS) according to your compliance and audit policy.
  • Consider shipping the JSONL file to your observability stack (for example : Loki, Splunk, or Elasticsearch) for centralized querying and alerting.

Example​

Here is an example of a log file

/lunar/packages/mcpx-server/audit-logs/audit-2025-10-29T10.jsonl
{"timestamp":"2025-10-29T10:05:44.132Z","createdAt":"2025-10-29T10:05:44.417Z","eventType":"config_applied","payload":{"config":{"permissions":{"default":{"_type":"default-allow","block":[]},"consumers":{}},"toolGroups":[{"name":"Version_control_and_issue_management","services":{"github":["get_issue","create_issue","add_issue_comment","list_issues","update_issue","get_pull_request","list_pull_requests","merge_pull_request","get_pull_request_diff","create_pull_request","update_pull_request","delete_file","list_branches","push_files","search_repositories","create_repository","fork_repository","create_branch","run_workflow","get_workflow_run","get_workflow_run_logs","rerun_failed_jobs","rerun_workflow_run","cancel_workflow_run"],"slack":"*"}},{"name":"Browser_automation_and_UI_testing","services":{"duckduckgo":["search"],"playwright":["browser_snapshot","browser_click","browser_drag","browser_hover","browser_type","browser_select_option","browser_wait_for","browser_navigate","browser_tab_list","browser_tab_new","browser_tab_select","browser_press_key"]}},{"name":"Database_and_file_operations","services":{"supabase":["search_docs","list_tables","list_migrations","apply_migration","execute_sql","get_project_url","get_anon_key","generate_typescript_types"]}},{"name":"Code_development_and_refactoring","services":{"memory":["create_entities","create_relations","add_observations"],"serena":["create_text_file","activate_project","delete_memory","execute_shell_command","find_symbol","get_symbols_overview","insert_after_symbol","list_memories","list_dir","prepare_for_new_conversation","read_memory","read_file","search_for_pattern"]}},{"name":"Observability_and_debugging","services":{"grafana":["search_dashboards","query_prometheus","query_loki_logs","list_incidents"]}}],"auth":{"enabled":false},"toolExtensions":{"services":{}}},"version":1,"lastModified":"2025-10-29T10:05:44.132Z"}}
{"timestamp":"2025-10-29T10:30:18.772Z","createdAt":"2025-10-29T10:30:23.529Z","eventType":"config_applied","payload":{"config":{"permissions":{"default":{"_type":"default-allow","block":[]},"consumers":{}},"toolGroups":[{"name":"Version_control_and_issue_management","services":{"github":["get_issue","create_issue","add_issue_comment","list_issues","update_issue","get_pull_request","list_pull_requests","merge_pull_request","get_pull_request_diff","create_pull_request","update_pull_request","delete_file","list_branches","push_files","search_repositories","create_repository","fork_repository","create_branch","run_workflow","get_workflow_run","get_workflow_run_logs","rerun_failed_jobs","rerun_workflow_run","cancel_workflow_run"],"slack":["slack_list_channels","slack_post_message","slack_reply_to_thread","slack_add_reaction","slack_get_channel_history","slack_get_thread_replies","slack_get_users","slack_get_user_profile"]}},{"name":"Browser_automation_and_UI_testing","services":{"duckduckgo":["search"],"playwright":["browser_snapshot","browser_click","browser_drag","browser_hover","browser_type","browser_select_option","browser_wait_for","browser_navigate","browser_tab_list","browser_tab_new","browser_tab_select","browser_press_key"]}},{"name":"Database_and_file_operations","services":{"supabase":["search_docs","list_tables","list_migrations","apply_migration","execute_sql","get_project_url","get_anon_key","generate_typescript_types"]}},{"name":"Code_development_and_refactoring","services":{"memory":["create_entities","create_relations","add_observations"],"serena":["create_text_file","activate_project","delete_memory","execute_shell_command","find_symbol","get_symbols_overview","insert_after_symbol","list_memories","list_dir","prepare_for_new_conversation","read_memory","read_file","search_for_pattern"]}},{"name":"Observability_and_debugging","services":{"grafana":["search_dashboards","query_prometheus","query_loki_logs","list_incidents"]}},{"name":"time","services":{"time":["get_current_time","convert_time"]}}],"auth":{"enabled":false},"toolExtensions":{"services":{}}},"version":2,"lastModified":"2025-10-29T10:30:18.755Z"}}
{"timestamp":"2025-10-29T10:30:32.516Z","createdAt":"2025-10-29T10:30:33.525Z","eventType":"config_applied","payload":{"config":{"permissions":{"default":{"_type":"default-allow","block":[]},"consumers":{"Claude":{"_type":"default-block","consumerGroupKey":"claude-ai (via mcp-remote 0.1.21) Profile","allow":["time"]}}},"toolGroups":[{"name":"Version_control_and_issue_management","services":{"github":["get_issue","create_issue","add_issue_comment","list_issues","update_issue","get_pull_request","list_pull_requests","merge_pull_request","get_pull_request_diff","create_pull_request","update_pull_request","delete_file","list_branches","push_files","search_repositories","create_repository","fork_repository","create_branch","run_workflow","get_workflow_run","get_workflow_run_logs","rerun_failed_jobs","rerun_workflow_run","cancel_workflow_run"],"slack":"*"}},{"name":"Browser_automation_and_UI_testing","services":{"duckduckgo":["search"],"playwright":["browser_snapshot","browser_click","browser_drag","browser_hover","browser_type","browser_select_option","browser_wait_for","browser_navigate","browser_tab_list","browser_tab_new","browser_tab_select","browser_press_key"]}},{"name":"Database_and_file_operations","services":{"supabase":["search_docs","list_tables","list_migrations","apply_migration","execute_sql","get_project_url","get_anon_key","generate_typescript_types"]}},{"name":"Code_development_and_refactoring","services":{"memory":["create_entities","create_relations","add_observations"],"serena":["create_text_file","activate_project","delete_memory","execute_shell_command","find_symbol","get_symbols_overview","insert_after_symbol","list_memories","list_dir","prepare_for_new_conversation","read_memory","read_file","search_for_pattern"]}},{"name":"Observability_and_debugging","services":{"grafana":["search_dashboards","query_prometheus","query_loki_logs","list_incidents"]}},{"name":"time","services":{"time":"*"}}],"auth":{"enabled":false},"toolExtensions":{"services":{}}},"version":3,"lastModified":"2025-10-29T10:30:32.509Z"}}
{"timestamp":"2025-10-29T10:31:33.063Z","createdAt":"2025-10-29T10:31:33.598Z","eventType":"tool_used","payload":{"toolName":"get_current_time","targetServerName":"time","args":{"timezone":"Asia/Tokyo"},"consumerTag":"Claude"}}
{"timestamp":"2025-10-29T10:58:40.710Z","createdAt":"2025-10-29T10:58:45.207Z","eventType":"config_applied","payload":{"config":{"permissions":{"default":{"_type":"default-allow","block":[]},"consumers":{"Claude":{"_type":"default-block","consumerGroupKey":"claude-ai (via mcp-remote 0.1.21) Profile","allow":["time"]}}},"toolGroups":[{"name":"Browser_automation_and_UI_testing","services":{"duckduckgo":["search"],"playwright":["browser_snapshot","browser_click","browser_drag","browser_hover","browser_type","browser_select_option","browser_wait_for","browser_navigate","browser_tab_list","browser_tab_new","browser_tab_select","browser_press_key"]}},{"name":"Database_and_file_operations","services":{"supabase":["search_docs","list_tables","list_migrations","apply_migration","execute_sql","get_project_url","get_anon_key","generate_typescript_types"]}},{"name":"Code_development_and_refactoring","services":{"memory":["create_entities","create_relations","add_observations"],"serena":["create_text_file","activate_project","delete_memory","execute_shell_command","find_symbol","get_symbols_overview","insert_after_symbol","list_memories","list_dir","prepare_for_new_conversation","read_memory","read_file","search_for_pattern"]}},{"name":"Observability_and_debugging","services":{"grafana":["search_dashboards","query_prometheus","query_loki_logs","list_incidents"]}},{"name":"time","services":{"time":["get_current_time","convert_time"]}}],"auth":{"enabled":false},"toolExtensions":{"services":{}}},"version":4,"lastModified":"2025-10-29T10:58:40.698Z"}}
{"timestamp":"2025-10-29T10:59:05.063Z","createdAt":"2025-10-29T10:59:05.289Z","eventType":"config_applied","payload":{"config":{"permissions":{"default":{"_type":"default-allow","block":[]},"consumers":{"Claude":{"_type":"default-block","consumerGroupKey":"claude-ai (via mcp-remote 0.1.21) Profile","allow":["time"]}}},"toolGroups":[{"name":"Database_and_file_operations","services":{"supabase":["search_docs","list_tables","list_migrations","apply_migration","execute_sql","get_project_url","get_anon_key","generate_typescript_types"]}},{"name":"Observability_and_debugging","services":{"grafana":["search_dashboards","query_prometheus","query_loki_logs","list_incidents"]}},{"name":"time","services":{"time":["get_current_time","convert_time"]}}],"auth":{"enabled":false},"toolExtensions":{"services":{}}},"version":5,"lastModified":"2025-10-29T10:59:05.058Z"}}
{"timestamp":"2025-10-29T10:59:29.434Z","createdAt":"2025-10-29T10:59:30.309Z","eventType":"config_applied","payload":{"config":{"permissions":{"default":{"_type":"default-allow","block":[]},"consumers":{"Claude":{"_type":"default-block","consumerGroupKey":"claude-ai (via mcp-remote 0.1.21) Profile","allow":["time"]}}},"toolGroups":[{"name":"Database_and_file_operations","services":{"supabase":["search_docs","list_tables","list_migrations","apply_migration","execute_sql","get_project_url","get_anon_key","generate_typescript_types"]}},{"name":"Observability_and_debugging","services":{"grafana":["search_dashboards","query_prometheus","query_loki_logs","list_incidents"]}},{"name":"time","services":{"time":["get_current_time","convert_time"]}},{"name":"tool_group_name","services":{"duckduckgo":["search"],"github":["add_comment_to_pending_review","add_issue_comment","get_me"],"grafana":["fetch_pyroscope_profile"]}}],"auth":{"enabled":false},"toolExtensions":{"services":{}}},"version":6,"lastModified":"2025-10-29T10:59:29.428Z"}}
{"timestamp":"2025-10-29T10:59:40.881Z","createdAt":"2025-10-29T10:59:45.329Z","eventType":"config_applied","payload":{"config":{"permissions":{"default":{"_type":"default-allow","block":[]},"consumers":{"Claude":{"_type":"default-block","consumerGroupKey":"claude-ai (via mcp-remote 0.1.21) Profile","allow":["time"]}}},"toolGroups":[{"name":"Database_and_file_operations","services":{"supabase":["search_docs","list_tables","list_migrations","apply_migration","execute_sql","get_project_url","get_anon_key","generate_typescript_types"]}},{"name":"Observability_and_debugging","services":{"grafana":["search_dashboards","query_prometheus","query_loki_logs","list_incidents"]}},{"name":"time","services":{"time":["get_current_time","convert_time"]}},{"name":"tool_group_name","services":{"duckduckgo":["search"],"github":["add_comment_to_pending_review","add_issue_comment","get_me"],"grafana":["fetch_pyroscope_profile"]}},{"name":"tool group","services":{"duckduckgo":["search","fetch_content"]}}],"auth":{"enabled":false},"toolExtensions":{"services":{}}},"version":7,"lastModified":"2025-10-29T10:59:40.873Z"}}