MCPSpy - MCP Monitoring with 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
• 🛡️ Prompt Injection Detection: Real-time detection of prompt injection and jailbreak attempts using ML models
• 🐛 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 (TUI mode is default)
sudo mcpspy

# Start monitoring with static console output (disable TUI)
sudo mcpspy --tui=false

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

# Stop monitoring with Ctrl+C (or 'q' in TUI mode)

Prompt Injection Detection

MCPSpy includes optional real-time prompt injection detection using HuggingFace's Inference API. When enabled, it analyzes MCP tool calls for potential injection attacks and jailbreak attempts.

Detection coverage:

1. Request-based injection: Detects malicious prompts in tool call arguments
2. Response-based injection: Detects malicious content in tool responses that could manipulate the agent

# Enable security scanning with HuggingFace token
sudo mcpspy --security --hf-token=hf_xxxxx

# Use a custom detection model
sudo mcpspy --security --hf-token=hf_xxxxx --security-model=protectai/deberta-v3-base-prompt-injection-v2

# Adjust detection threshold (default: 0.5)
sudo mcpspy --security --hf-token=hf_xxxxx --security-threshold=0.7

# Run analysis synchronously (blocks until analysis completes)
sudo mcpspy --security --hf-token=hf_xxxxx --security-async=false

Security CLI Flags:

Supported Models:

• protectai/deberta-v3-base-prompt-injection-v2 (default, publicly accessible)
• meta-llama/Llama-Prompt-Guard-2-86M (deprecated on HF Inference API)

When a potential injection is detected, MCPSpy displays a security alert with risk level (low/medium/high/critical), category, and the analyzed content.

Output Format

TUI Mode (Default)

MCPSpy runs in interactive Terminal UI mode by default. The TUI provides:

• Interactive table view with scrolling
• Detailed message inspection (press Enter)
• Filtering by transport, type, and actor
• Multiple density modes for different screen sizes
• Real-time statistics

Static Console Output

When running with --tui=false:

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

Stdio Transport - Request:

{
  "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" }
  },
  "error": {},
  "raw": "{...}"
}

Stdio Transport - Response:

{
  "timestamp": "2024-01-15T12:34:56.890Z",
  "transport_type": "stdio",
  "stdio_transport": {
    "from_pid": 12346,
    "from_comm": "python",
    "to_pid": 12345,
    "to_comm": "python"
  },
  "type": "response",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Weather in New York: 20°C"
      }
    ],
    "isError": false
  },
  "error": {},
  "request": {
    "type": "request",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "get_weather",
      "arguments": { "city": "New York" }
    },
    "error": {}
  },
  "raw": "{...}"
}

HTTP/HTTPS Transport - Request:

{
  "timestamp": "2024-01-15T12:34:56.789Z",
  "transport_type": "http",
  "http_transport": {
    "pid": 47837,
    "comm": "python",
    "host": "127.0.0.1:12345",
    "is_request": true
  },
  "type": "request",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "New York" }
  },
  "error": {},
  "raw": "{...}"
}

HTTP/HTTPS Transport - Response:

{
  "timestamp": "2024-01-15T12:34:56.890Z",
  "transport_type": "http",
  "http_transport": {
    "pid": 47837,
    "comm": "python",
    "host": "127.0.0.1:12345"
  },
  "type": "response",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Weather in New York: 20°C"
      }
    ],
    "isError": false
  },
  "error": {},
  "request": {
    "type": "request",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "get_weather",
      "arguments": { "city": "New York" }
    },
    "error": {}
  },
  "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

8. Security Analyzer (pkg/security/)

• Optional component for real-time prompt injection detection
• Subscribes to MCP message events from the event bus
• Analyzes high-risk methods (tools/call, resources/read, prompts/get)
• Uses HuggingFace Inference API with configurable ML models
• Publishes security alerts when injections are detected
• Supports async and sync analysis modes

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+).

Agentic Workflows Setup

MCPSpy supports development with AI coding assistants like Claude Code. Since mcpspy requires root privileges for eBPF operations, you need to configure passwordless sudo to enable autonomous test execution.

Configuring Sudoers for Passwordless Execution

Create a sudoers rule that allows your user to run mcpspy without a password. The E2E tests use the binary at build/mcpspy-linux-amd64 (or build/mcpspy-linux-arm64 on ARM):

# Option 1: Using visudo (opens editor)
sudo visudo -f /etc/sudoers.d/mcpspy
# Add this line (replace YOUR_USERNAME and adjust path as needed):
# YOUR_USERNAME ALL=(ALL) NOPASSWD: /home/YOUR_USERNAME/mcpspy/build/mcpspy-linux-amd64, /home/YOUR_USERNAME/mcpspy/.worktrees/*/build/mcpspy-linux-amd64

# Option 2: One-liner (replace YOUR_USERNAME and path)
echo 'YOUR_USERNAME ALL=(ALL) NOPASSWD: /home/YOUR_USERNAME/mcpspy/build/mcpspy-linux-amd64, /home/YOUR_USERNAME/mcpspy/.worktrees/*/build/mcpspy-linux-amd64' | sudo tee /etc/sudoers.d/mcpspy && sudo chmod 440 /etc/sudoers.d/mcpspy

The .worktrees/* pattern enables passwordless execution from git worktrees. Note that sudoers * doesn't match /, so both patterns are needed.

After configuration, verify it works:

sudo /path/to/build/mcpspy-linux-amd64 --help  # Should not prompt for password

This enables AI assistants to run E2E tests (make test-e2e) which require sudo for eBPF operations.

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)