MCPSpy
CLAUDE.md519 starsChanged 12 months agoApache-2.0View on GitHub
MCPSpy is a CLI utility that uses eBPF to monitor MCP (Model Context Protocol) communication by tracking stdio operations and analyzing JSON-RPC 2.0 messages. MCPSpy uses an event-driven architecture with a publish-subscribe pattern: Debug mode allows inspecting raw eBPF events and derived events for troubleshooting parsing issues, developing new protocol support, or understanding the event flow. Available event types: - Raw eBPF: fs_read, fs_write, library, tls_send, tls_recv, tls_free - Derived: http_request, http_response, http_sse, mcp_message, fs_aggregated_read, fs_aggregated_write, security_alert, llm_message, tool_usage Flags:…
In this repository5 other files it gives its agents.
- tests/CLAUDE.mdCLAUDE.md
- git-commit-creatorSkill
- github-issue-creatorSkill
- go-testingSkill
- security-integration-testsSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 59
Use efficient data structures
- Very specific: line 177
Default model is protectai/deberta-v3-base-prompt-injection-v2 (non-gated)
- Very specific: line 182
Use worktrees to run multiple Claude sessions on separate feature branches.
- Very specific: line 183
Use the .worktrees/ directory to keep things organized in terms of permissions:
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
MCPSpy Project Rules
Project Overview
MCPSpy is a CLI utility that uses eBPF to monitor MCP (Model Context Protocol) communication by tracking stdio operations and analyzing JSON-RPC 2.0 messages.
Technology Stack
- Go 1.24+ for the main application
- C for eBPF programs
- cilium/ebpf for loading eBPF programs
- Docker for containerization
Project Structure
mcpspy/
├── cmd/mcpspy/ # CLI entry point
├── pkg/
│ ├── bus/ # Event bus for publish-subscribe communication
│ ├── ebpf/ # eBPF loading and management
│ ├── event/ # Event definitions and handling
│ ├── eventlogger/ # Event logging component
│ ├── fs/ # Filesystem (stdio) session management and JSON aggregation
│ ├── http/ # HTTP transport parsing and analysis
│ ├── mcp/ # MCP protocol parsing and analysis
│ ├── output/ # Output formatting (console, and file output)
│ └── security/ # Prompt injection detection via HuggingFace API
│ ├── hf/ # HuggingFace Inference API client
│ └── testdata/ # Test samples for security integration tests
├── internal/
│ └── testing/ # Testing utilities (mock event bus, etc.)
├── bpf/ # eBPF C programs
├── tests/ # Test files
├── deploy/docker/ # Docker configuration
└── .github/workflows/ # CI/CD workflowsArchitecture
MCPSpy uses an event-driven architecture with a publish-subscribe pattern:
- Event Bus (
pkg/bus/): Central communication hub that decouples components - Components communicate by publishing and subscribing to typed events
- The eBPF loader publishes raw events from kernel space
- The HTTP session manager and MCP parser subscribe to relevant events
- Output handlers subscribe to parsed MCP messages
MCP Protocol Context
- MCP uses JSON-RPC 2.0 format
- Messages have jsonrpc: "2.0" field
- Three message types: Request, Response, Notification
- Track method names like "tools/call", "resources/read", etc.
- Focus on both stdio and HTTP transport (streamable HTTP).
Performance Guidelines
- Use efficient data structures
- Minimize data copying between kernel and userspace
- Filter early in eBPF to reduce overhead
- Event bus uses asynchronous processing to avoid blocking
Building
make buildRunning
# Run with TUI mode (default)
sudo ./mcpspy
# Run with static console output (for testing/debugging)
sudo ./mcpspy --tui=false
# It is must be stopped by sending SIGINT (Ctrl+C) or SIGTERM.
# In TUI mode, you can also press 'q' to quit.Debug Mode
Debug mode allows inspecting raw eBPF events and derived events for troubleshooting parsing issues, developing new protocol support, or understanding the event flow.
# Show all events
sudo ./mcpspy debug
# Show only MCP messages with payloads
sudo ./mcpspy debug --events mcp_message --payload
# Filter by PID
sudo ./mcpspy debug --pid 12345
# Filter by process name
sudo ./mcpspy debug --comm claude
# Debug HTTP parsing issues
sudo ./mcpspy debug --events tls_recv,http_request,http_response --payload
# Show HTTP headers
sudo ./mcpspy debug --events http_request,http_response --headers
# Combine filters with headers
sudo ./mcpspy debug --events http_request,http_response --pid 12345 --headers --payloadAvailable event types:
- Raw eBPF:
fs_read,fs_write,library,tls_send,tls_recv,tls_free - Derived:
http_request,http_response,http_sse,mcp_message,fs_aggregated_read,fs_aggregated_write,security_alert,llm_message,tool_usage
Flags:
--events, -e: Filter by event type(s), comma-separated--pid, -p: Filter by specific PID--comm, -c: Filter by process name (substring match)--host: Filter by URL regex (matches against host+path, e.g.,api\.anthropic\.com/v1/messages)--payload: Show payload/buffer data for events--headers: Show HTTP headers for HTTP events
Testing
Running all tests (unit tests, and end-to-end tests for both stdio and https transports):
make testRunning unit tests:
make test-unitRunning end-to-end tests (including mcpspy, and verifying the output):
make test-e2e-stdio
make test-e2e-https
# Or
make test-e2eRunning scenario tests (without mcpspy):
make test-scenario-stdio
make test-scenario-https
make test-scenario-security # Security/injection testNote: E2E tests automatically run MCPSpy in static mode (--tui=false) to capture output for validation. The test configuration is in tests/e2e_config.yaml.
Integration Tests
Integration tests verify functionality with real external services. Currently includes security/prompt injection detection tests with HuggingFace API:
# Run integration tests (requires HF_TOKEN)
HF_TOKEN=hf_xxx make test-integration
# Override the model (default: protectai/deberta-v3-base-prompt-injection-v2)
HF_TOKEN=hf_xxx HF_MODEL=your-model-name make test-integrationTest structure:
pkg/security/testdata/samples.json- Test samples (benign and malicious)pkg/security/hf/integration_test.go- HF client integration testspkg/security/integration_test.go- Full analyzer integration tests with event bus
Notes:
- Integration tests use build tag
//go:build integration - Default model is
protectai/deberta-v3-base-prompt-injection-v2(non-gated) - Unit tests run without API calls via mock HTTP server
Git Worktrees for Parallel Claude Sessions
Use worktrees to run multiple Claude sessions on separate feature branches. Use the .worktrees/ directory to keep things organized in terms of permissions:
# Create worktree with new branch
git worktree add .worktrees/MCPSpy-<feature> -b feat/<feature-name>
# Work in the new directory
cd .worktrees/MCPSpy-<feature> && claude
# Cleanup after merge
git worktree remove .worktrees/MCPSpy-<feature>Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

