LukeOsland1/mcp-audit-logger

MCP Audit Logger

A transparent wrapper for Model Context Protocol (MCP) servers that logs all Claude Code tool interactions to a webhook endpoint for enterprise audit and monitoring.

Enterprise-Ready: Single self-contained deployment script for Jamf with zero dependencies. No package managers, no build steps - just upload and deploy.

Quick Links

• 🚀 - Complete deployment walkthrough
• 📋 Installation - Manual and automated setup
• 📊 Audit Log Format - See what gets logged
• 🔧 Troubleshooting - Common issues and fixes

Overview

This tool wraps your existing MCP servers to provide comprehensive audit logging without modifying their functionality. Perfect for enterprise environments requiring security monitoring, compliance, and user activity tracking.

Features

Deployment & Management:

• 🏢 Enterprise Ready - Self-contained Jamf deployment script, zero dependencies
• 🔄 Automatic Wrapping - LaunchAgent detects and wraps new MCPs when added
• ⚙️ Configurable - Log levels (debug/normal/quiet), custom install paths
• 🤫 Silent Operation - Zero user interaction required

Audit & Compliance:

• 🔍 Tool-Only Logging - Logs only actual MCP tool calls (not handshakes/initialization)
• 👤 User Attribution - Tracks username, hostname, device serial, and timestamp
• 🛠️ Detailed Logs - Captures MCP server, tool name, arguments, and responses
• 📊 Webhook Integration - Sends structured JSON to your monitoring endpoint

Security & Reliability:

• 🔒 Secure - User-level configuration, HTTPS webhook support
• ⚡ No External Dependencies - Uses only Node.js built-ins
• 💻 Multi-Platform - macOS, Linux, and Windows device serial capture
• 🛡️ Non-Blocking - Failed webhooks won't interrupt MCP operations

Installation

Quick Start

The recommended way to deploy this tool is via the Jamf Deployment method below, which is fully automated and requires zero user interaction.

For manual testing or development, you can run the deployment script locally:

# Clone the repository
git clone https://github.com/LukeOsland1/mcp-audit-logger.git
cd mcp-audit-logger

# Run deployment script (requires sudo)
sudo ./deploy-jamf.sh "https://your-webhook-url.com/audit"

This installs the wrapper to /usr/local/mcp-audit-logger/ and automatically wraps all existing MCP servers.

Jamf Deployment (Recommended for Enterprise)

For enterprise macOS deployments, use the included self-contained deployment script for automated installation across your fleet.

What it does:

• ✅ Installs wrapper to /usr/local/mcp-audit-logger (customizable)
• ✅ Wraps all existing MCP servers automatically
• ✅ Installs LaunchAgent for automatic wrapping of new MCPs
• ✅ Creates user webhook configuration
• ✅ Zero user intervention required
• ✅ Runs completely silently

Automatic Wrapping: Once deployed, the LaunchAgent monitors Claude Code's config file. When users add new MCP servers, they are automatically wrapped transparently.

Quick Setup

Installation:

1. Upload deploy-jamf.sh to Jamf Pro Scripts section
2. Create a policy and add the script
3. Set Parameter 4 to your webhook URL (required)
4. Optional: Configure parameters 5-7 for custom settings
5. Scope to target computers

Uninstallation:

1. Upload uninstall-jamf.sh to Jamf Pro Scripts section
2. Create an uninstall policy
3. Script automatically removes all files and unwraps MCPs
4. Runs completely silently

Script Parameters

Detailed Documentation

• 🚀 - Complete beginner-friendly setup guide (start here!)
• 📋 - Step-by-step deployment checklist
• 🔧 - Technical deployment reference

Audit Log Format

The wrapper only logs actual tool usage - initialization, handshakes, and other MCP protocol messages are not logged to keep noise minimal and focus on actual user actions.

Each audit log sent to the webhook contains:

{
  "timestamp": "2025-10-01T12:34:56.789Z",
  "hostname": "macbook-pro.local",
  "username": "johndoe",
  "platform": "darwin",
  "device_serial": "C02XY1234567",
  "event": "mcp_tool_call",
  "mcp_server": "filesystem",
  "method": "tools/call",
  "tool_name": "read_file",
  "tool_arguments": {
    "path": "/home/user/document.txt"
  },
  "request_id": 3
}

Common Fields (in all events):

• timestamp - ISO 8601 timestamp
• hostname - Device hostname
• username - Current user
• platform - OS platform (darwin, linux, win32)
• device_serial - Device serial number (for asset tracking)

Event Types

• wrapper_start - MCP wrapper initialized

  • mcp_server: Name of the MCP server being wrapped
  • wrapped_command: Command being executed
  • wrapped_args: Command arguments

• mcp_tool_call - Tool invocation from Claude Code to MCP server

  • mcp_server: Name of the MCP server
  • method: Always tools/call
  • tool_name: Name of the tool being invoked
  • tool_arguments: Arguments passed to the tool
  • request_id: JSON-RPC request ID

• mcp_tool_response - Tool response from MCP server to Claude Code

  • mcp_server: Name of the MCP server
  • response_id: JSON-RPC response ID (matches request_id)
  • result: Tool execution result data
  • error: Error information (if tool execution failed)

• wrapper_exit - MCP wrapper shutting down

  • mcp_server: Name of the MCP server
  • exit_code: Process exit code

How It Works

┌─────────────┐
│ Claude Code │
└──────┬──────┘
       │ JSON-RPC (all messages)
       ▼
┌─────────────────┐     ┌──────────────┐
│  Audit Wrapper  │────▶│   Webhook    │ (only tool calls)
└────────┬────────┘     └──────────────┘
         │ JSON-RPC (all messages)
         ▼
┌─────────────────┐
│   MCP Server    │
└─────────────────┘

1. Transparent Proxy: The wrapper sits between Claude Code and your MCP servers
2. Selective Logging: Only tools/call requests and responses are logged to your webhook
3. Pass-through: All messages are forwarded unchanged to the MCP server
4. Response Logging: Tool call responses are logged before returning to Claude Code
5. No Impact: MCPs function normally with zero performance impact
6. Low Noise: Handshakes, initialization, and protocol messages are not logged

Configuration

Configuration is stored in ~/.mcp-audit-config.json:

{
  "webhookUrl": "https://your-webhook-endpoint.com/audit"
}

Security Considerations

• Webhook Security: URL is stored locally per user in ~/.mcp-audit-config.json
• System Identification: All logs include hostname, username, and device serial number
• Transport Security: Logs are sent over HTTPS (ensure your webhook supports TLS)
• Privacy: Tool arguments and file paths are included in audit logs - users should be informed
• Error Handling: Failed webhook requests are logged to stderr, won't block MCP operations
• No External Dependencies: Wrapper uses only Node.js built-ins for security and reliability

Requirements

Runtime:

• Node.js 18 or higher (no external dependencies required)
• Claude Code/Desktop

For Jamf Deployment:

• macOS 10.15 or higher
• jq (JSON processor) - required for auto-wrapping MCPs

Files and Locations

Installed Files

• /usr/local/mcp-audit-logger/wrapper.js - Main wrapper executable
• /usr/local/mcp-audit-logger/auto-wrap-mcps.sh - Auto-wrap script
• /usr/local/mcp-audit-logger/package.json - Package metadata
• ~/Library/LaunchAgents/com.mcp.audit.autowrap.plist - LaunchAgent configuration

User Files

• ~/.mcp-audit-config.json - User webhook configuration
• ~/.claude.json - Modified to wrap MCP servers

Log Files

• /var/log/mcp-auto-wrap.log - Auto-wrap script output
• /var/log/mcp-auto-wrap.error.log - Auto-wrap error output

Troubleshooting

Logs not appearing

1. Check webhook URL configuration in ~/.mcp-audit-config.json
2. Verify MCP servers are wrapped in Claude Code config (~/.claude.json)
   • Each MCP should have "command": "node" and args should start with wrapper path
3. Check if LaunchAgent is running: launchctl list | grep mcp.audit
4. View auto-wrap logs: tail -f /var/log/mcp-auto-wrap.log
5. Restart Claude Code
6. Check webhook endpoint is accessible

New MCP not getting wrapped

1. Check LaunchAgent status: launchctl list | grep mcp.audit
2. Manually run auto-wrap script: sudo bash /usr/local/mcp-audit-logger/auto-wrap-mcps.sh
3. Check auto-wrap logs: cat /var/log/mcp-auto-wrap.log
4. Verify Claude config file path in LaunchAgent plist

Installation issues with Jamf

1. Verify Node.js is installed on target machines
2. Check Jamf policy logs for errors
3. Ensure Parameter 4 contains valid webhook URL
4. Verify file permissions on installed files
5. Check if jq is installed: which jq

Project Structure

mcp-audit-logger/
├── deploy-jamf.sh              # Self-contained deployment script (contains all code)
├── uninstall-jamf.sh           # Uninstall script for Jamf
├── JAMF-SETUP-GUIDE.md         # Complete Jamf deployment guide
├── JAMF-DEPLOYMENT.md          # Technical deployment reference
├── JAMF-CHECKLIST.md           # Quick deployment checklist
└── README.md                   # This file

Note: All code (wrapper.js, auto-wrap-mcps.sh, package.json, LaunchAgent plist) is embedded directly in deploy-jamf.sh as a single self-contained deployment script. This makes it easy to upload to Jamf and ensures consistency across deployments.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: See and guides above
• 💬 Discussions: GitHub Discussions

License

MIT

Acknowledgments

Built with Claude Code for enterprise MCP monitoring and compliance.