How MCPSpy Works
MCPSpy is an eBPF-based monitoring tool designed to observe Model Context Protocol (MCP) traffic between clients and servers at the kernel level. It operates without modifying applications, instead hooking into low-level system calls to record every tool call exchanged in JSON-RPC 2.0 messages. This approach ensures minimal overhead while providing real-time visibility into MCP communications.
While Server-Sent Events (SSE) support exists, it is noted as deprecated in the protocol’s documentation. By intercepting traffic at the kernel level, MCPSpy captures both requests and responses, enabling detailed auditing and analysis of interactions between MCP clients and servers.
MCPSpy’s architecture relies on eBPF (Extended Berkeley Packet Filter), a technology that allows safe and efficient kernel-level monitoring. This method enables the tool to inspect system calls related to MCP traffic without requiring modifications to the applications themselves. The captured data is then processed and displayed in various formats, including a Terminal User Interface (TUI), static console output, or structured JSONL files for further analysis.
Root privileges are required to load eBPF programs, reflecting the tool’s need to operate at a low level within the system.
Use Cases
MCPSpy is primarily used for monitoring and observability in AI and LLM-based systems that rely on the Model Context Protocol. Its capabilities span security analysis, debugging, performance monitoring, and compliance verification, making it valuable in both development and production environments.
In Kubernetes deployments, MCPSpy can monitor MCP traffic from AI/LLM services such as LangFlow and LangGraph. This is particularly useful for debugging integration issues in complex AI workflows, auditing AI interactions for security and compliance, and tracking interactions with both remote and local MCP servers. By providing visibility into message patterns, the tool helps identify performance bottlenecks and potential data leakage risks in AI communications.
For development and testing purposes, MCPSpy allows developers to validate MCP implementations in containerized environments. It ensures consistent behavior across different environments by capturing and analyzing real-time MCP traffic. This is especially useful for testing AI service integrations before deployment, where understanding the exact flow of messages can prevent issues in production.
Security is a critical use case for MCPSpy, particularly in detecting prompt injection and jailbreak attempts. Detection coverage includes both request-based and response-based injections, where malicious prompts or manipulated responses could compromise the integrity of AI agents. Users can customize detection models, adjust thresholds, and run analyses synchronously or asynchronously to balance performance and accuracy.
Compliance and regulatory requirements are also addressed by MCPSpy, as it provides detailed logs of MCP communications.
Key Features & Capabilities
By default, it operates in TUI mode, providing an interactive table view with features such as scrolling, detailed message inspection, filtering by transport type and actor, and multiple density modes for different screen sizes. This interactive approach allows users to navigate large volumes of data efficiently.
For users who prefer a non-interactive output, MCPSpy can be configured to display static console output. This format presents messages in a timestamped, structured format, showing process IDs, command names, message types (request or response), and relevant payload details. This is particularly useful for logging and automated processing.
Each line in the JSONL file represents a single MCP message, including metadata such as timestamps, transport type, process identifiers, and the full message payload. This structured format supports further processing, archiving, and analysis using standard data tools and pipelines.
When enabled, the tool uses HuggingFace’s Inference API to analyze MCP tool calls for signs of malicious activity. Detection is configurable, with options to specify the detection model, adjust the threshold for risk assessment, and choose between synchronous or asynchronous analysis.
This flexibility ensures that the tool can be integrated into existing workflows without significant disruption, providing consistent monitoring across different stages of development and production.
Docker images are also available, simplifying deployment in containerized environments.
MCPSpy’s command-line interface is intuitive, with flags to enable or disable features such as TUI mode, security scanning, and output redirection. For example, users can start monitoring with static console output using the --tui=false flag or save output to a JSONL file with the -o flag. Security-related flags, such as --security, --hf-token, and --security-model, allow for customization of prompt injection detection to meet specific requirements.
Each release includes pre-built binaries for Linux AMD64 and ARM64 architectures, along with corresponding Docker images. Checksums are provided for verification, ensuring the integrity of downloaded binaries.