MCPSpy is a real-time monitoring tool for Model Context Protocol (MCP) communications, built on eBPF to observe MCP traffic at kernel level. It focuses on the JSON-RPC 2.0 messages exchanged between MCP clients and servers over supported transports (Stdio and HTTP/HTTPS, including Server-Sent Events). When you run MCPSpy, you’ll get real-time visibility into MCP message flows, with options to disable the TUI, output JSONL logs, and run security analyses for prompt-injection and potential data leakage. Use the default TUI mode for interactive exploration, or pipe JSONL output for automated parsing and integration with your observability stack. If you enable security features, MCPSpy can leverage a HuggingFace model via an API to detect prompt-injection patterns in both tool calls and tool responses.

Prerequisites:

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

Option A: Install and run from Docker (recommended to avoid host setup)

1. Pull and run the latest MCPSpy image: docker pull ghcr.io/alex-ilgayev/mcpspy:latest docker run --rm -it --privileged ghcr.io/alex-ilgayev/mcpspy:latest

Option B: Build from source (requires Go and build dependencies)

1. Install prerequisites:
   • Go 1.24+ (see Go install steps below)
   • clang/llvm, libbpf, build-essential, and Docker tools as needed
2. Install Go (example for Linux): 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 export PATH=$PATH:/usr/local/go/bin
3. Build MCPSpy: git clone https://github.com/alex-ilgayev/mcpspy.git cd mcpspy make all

   Run the built binary (if applicable):

   sudo ./mcpspy

Option C: Docker-based Quick Start (manual build steps can be skipped if you use the image above)

1. Build Docker image locally (from repo clone): make image
2. Or pull prebuilt image as shown in Option A.

Tips:

• Ensure your host allows privileged containers or has appropriate CAP_NET_ADMIN capabilities for eBPF tracing.
• If you encounter kernel headers or build issues, confirm kernel headers match your running kernel and that libbpf-dev is installed.
• The security features rely on HuggingFace tokens. Provide a valid --hf-token when enabling --security, and consider setting a model with --security-model. The default threshold is 0.5; adjust with --security-threshold as needed.
• The Kubernetes deployment guide demonstrates monitoring MCP traffic from clusters; you may also run MCPSpy in standalone mode or via Docker for local testing.
• When using JSONL output (-o), you can tail the file or stream it into log aggregators for centralized analysis.