MCPSpy - MCP Monitoring with eBPF 🕵️✨

███╗   ███╗ ██████╗██████╗ ███████╗██████╗ ██╗   ██╗
████╗ ████║██╔════╝██╔══██╗██╔════╝██╔══██╗╚██╗ ██╔╝
██╔████╔██║██║     ██████╔╝███████╗██████╔╝ ╚████╔╝ 
██║╚██╔╝██║██║     ██╔═══╝ ╚════██║██╔═══╝   ╚██╔╝  
██║ ╚═╝ ██║╚██████╗██║     ███████║██║        ██║   
╚═╝     ╚═╝ ╚═════╝╚═╝     ╚══════╝╚═╝        ╚═╝   

MCPSpy - Real-time monitoring for Model Context Protocol communication using eBPF

Overview

MCPSpy is a powerful command-line tool that leverages eBPF (Extended Berkeley Packet Filter) technology to monitor Model Context Protocol (MCP) communication at the kernel level. It provides real-time visibility into JSON-RPC 2.0 messages exchanged between MCP clients and servers by hooking into low-level system calls.

The Model Context Protocol supports three transport protocols for communication:

• Stdio: Communication over standard input/output streams
• Streamable HTTP: Direct HTTP request/response communication with server-sent events
• SSE (Server-Sent Events): HTTP-based streaming communication (Deprecated)

MCPSpy supports monitoring of both Stdio and HTTP/HTTPS transports (including Server-Sent Events), providing comprehensive coverage of MCP communication channels.

Why MCPSpy?

The Model Context Protocol is becoming the standard for AI tool integration, but understanding what's happening under the hood can be challenging. MCPSpy addresses this by providing:

• 🔒 Security Analysis: Monitor what data is being transmitted, detect PII leakage, and audit tool executions
• 🐛 Debugging: Troubleshoot MCP integrations by seeing the actual message flow
• 📊 Performance Monitoring: Track message patterns and identify bottlenecks
• 🔍 Compliance: Ensure MCP communications meet regulatory requirements
• 🎓 Learning: Understand how MCP works by observing real communications

Installation

Prerequisites

• Linux kernel version 5.15 or later
• Root privileges (required for eBPF)

Download Pre-built Binary (Auto-detect OS + Arch)

Download the latest release from the release page:

# Set platform-aware binary name
BIN="mcpspy-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')"

# Download the correct binary
wget "https://github.com/alex-ilgayev/mcpspy/releases/latest/download/${BIN}"

# Make it executable and move to a directory in your PATH
chmod +x "${BIN}"
sudo mv "${BIN}" /usr/local/bin/mcpspy

✅ Note: Currently supported platforms: linux-amd64, linux-arm64

Build from Source

Install Dependencies

First, install the required system dependencies:

sudo apt-get update
# Install build essentials, eBPF dependencies
sudo apt-get install -y clang clang-format llvm make libbpf-dev build-essential
# Install Python 3 and pip (for e2e tests)
sudo apt-get install -y python3 python3-pip python3-venv
# Install docker and buildx (if not already installed)
sudo apt-get install -y docker.io docker-buildx

Install Go

MCPSpy requires Go 1.24 or later. Install Go using one of these methods:

Option 1: Install from the official Go website (Recommended)

# Download and install Go 1.24.1 (adjust version as needed)
wget https://go.dev/dl/go1.24.1.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.1.linux-amd64.tar.gz

# Add Go to PATH (add this to your ~/.bashrc or ~/.profile for persistence)
export PATH=$PATH:/usr/local/go/bin

Option 2: Install via snap

sudo snap install go --classic

Build MCPSpy

Clone the repository and build MCPSpy:

# Clone the repository
git clone https://github.com/alex-ilgayev/mcpspy.git
cd mcpspy

# Build the project
make all

Docker

# Build Docker image
make image
# Or pull the latest image
docker pull ghcr.io/alex-ilgayev/mcpspy:latest
# Or pull a specific image release
docker pull ghcr.io/alex-ilgayev/mcpspy:v0.1.0

# Run the container
docker run --rm -it --privileged ghcr.io/alex-ilgayev/mcpspy:latest

Kubernetes

MCPSpy can be deployed in Kubernetes clusters to monitor MCP traffic from AI/LLM services like LangFlow, LangGraph, and other applications that use the Model Context Protocol.

# Deploy MCPSpy as a DaemonSet
kubectl apply -f https://raw.githubusercontent.com/alex-ilgayev/mcpspy/main/deploy/kubernetes/mcpspy.yaml

Real-World Use Cases in Kubernetes

1. Monitoring LangFlow/LangGraph Deployments

   • Observe MCP traffic between LangFlow/LangGraph and AI services
   • Debug integration issues in complex AI workflows
   • Audit AI interactions for security and compliance

2. AI Service Monitoring

   • Track interactions with both remote and local MCP servers
   • Identify performance bottlenecks in AI service calls
   • Detect potential data leakage in AI communications

3. Development and Testing

   • Test MCP implementations in containerized environments
   • Validate AI service integrations before production deployment
   • Ensure consistent behavior across different environments

For detailed instructions and real-world examples of monitoring AI services in Kubernetes, see the Kubernetes Usage Guide.

Usage

Basic Usage

# Start monitoring MCP communication
sudo mcpspy

# Start monitoring with raw message buffers
sudo mcpspy -b

# Start monitoring and save output to JSONL file
sudo mcpspy -o output.jsonl

# Stop monitoring with Ctrl+C

Output Format

Console Output

12:34:56.789 python[12345] → python[12346] REQ tools/call (get_weather) Execute a tool
12:34:56.890 python[12346] → python[12345] RESP OK

JSONL Output

{
  "timestamp": "2024-01-15T12:34:56.789Z",
  "transport_type": "stdio",
  "stdio_transport": {
    "from_pid": 12345,
    "from_comm": "python",
    "to_pid": 12346,
    "to_comm": "python"
  },
  "type": "request",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "New York" }
  },
  "raw": "{...}"
}

For HTTP/HTTPS transport:

{
  "timestamp": "2024-01-15T12:34:56.789Z",
  "transport_type": "http",
  "type": "request",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "New York" }
  },
  "raw": "{...}"
}

Architecture

MCPSpy uses an event-driven architecture with a publish-subscribe pattern to decouple components and enable extensibility. The system consists of several components that communicate through a central event bus:

1. Event Bus (pkg/bus/)

• Central communication hub using publish-subscribe pattern
• Enables asynchronous event processing
• Using github.com/asaskevich/EventBus library

2. eBPF Program (bpf/)

• Hooks into vfs_read and vfs_write kernel functions for stdio transport
• Hooks into TLS library functions (SSL_read, SSL_write) for HTTP/HTTPS transport
• Filters potential MCP traffic by detecting JSON patterns
• Sends events to userspace via ring buffer
• Minimal performance impact with early filtering

3. eBPF Loader (pkg/ebpf/)

• Manages the lifecycle of eBPF programs and resources
• Loads pre-compiled eBPF objects into the kernel using cilium/ebpf library
• Converts raw binary events from kernel space into structured Go data types
• Publishes events to the event bus for downstream processing

4. HTTP Session Manager (pkg/http/)

• Subscribes to TLS-related events from the event bus
• Manages HTTP/HTTPS sessions and correlates request/response pairs
• Handles TLS payload interception and parsing
• Supports chunked transfer encoding and Server-Sent Events (SSE)
• Reconstructs complete HTTP messages from fragmented TLS data
• Publishes reconstructed HTTP bodies to the event bus for MCP parsing

5. MCP Protocol Parser (pkg/mcp/)

• Subscribes to data events from the event bus (stdio and HTTP TLS payloads)
• Validates JSON-RPC 2.0 message format
• Parses MCP-specific methods and parameters
• Correlates read operations and write operations into a single MCP message (relevant for stdio transport)
• Supports both stdio and HTTP/HTTPS transports (including SSE)
• Publishes parsed MCP messages to the event bus

6. Output Handlers (pkg/output/)

• Subscribe to MCP message events from the event bus
• Console display with colored, formatted output
• JSONL output for programmatic analysis
• Real-time statistics tracking

7. Event Logger (pkg/eventlogger/)

• Subscribes to all events on the event bus for debugging
• Provides detailed logging of event flow through the system
• Configurable log levels for different event types

Development

Building

# Generate eBPF bindings and build
make all

# Build Docker image
make image

Testing

MCPSpy includes comprehensive end-to-end tests that simulate real MCP communication across different transports:

# (Optional) Set up test environment
make test-e2e-setup

# Run all tests (requires root privileges)
make test-e2e

# Run individual transport tests
make test-e2e-stdio   # Test stdio transport
make test-e2e-https   # Test HTTP/HTTPS transport

The test suite includes:

• MCP server and client simulators for both stdio and HTTP transports
• Message validation against expected outputs
• Multiple message type coverage
• SSL/TLS encrypted HTTP communication testing

Limitations

• FS Events Buffer Size: Limited to 16KB per message. This means MCP messages with buffer size greater than 16KB will be missed / ignored.
• FS Events Constructed of Multiple Messages: MCPSpy currently does not support reconstructing MCP messages that are split across multiple read or write syscalls. This means that if an MCP message is larger than the buffer size used in a single syscall, it may be missed or ignored.
• Inode Collision for Stdio Transport: Inode numbers are only unique within a filesystem. If monitoring processes across multiple filesystems or mount namespaces, inode collisions are theoretically possible but rare in practice for pipe-based stdio communication.
• Platform: Linux only (kernel 5.15+).

Contributing

We welcome contributions! Feel free to open an issue or a pull request.

License

• User-mode code (Mainly Go): Apache 2.0 (see LICENSE)
• eBPF C programs (bpf/*): GPL-2.0-only (see LICENSE-BPF)

---

Made with ❤️ by Alex Ilgayev