mcp server
mcp-probe
A Model Context Protocol (MCP) client library and debugging toolkit in Rust. This foundation provides both a production-ready SDK for building MCP integrations and the core architecture for an interac
Set up
Runs on your computer. Pick your agent and operating system.
This project does not publish an install method we can turn into a config. Follow the README instead.
README
synced Oct 14, 2026
🔍 MCP Probe - Advanced MCP Protocol Debugger & Interactive Client
MCP Probe is a powerful Terminal User Interface (TUI) for debugging, testing, and interacting with Model Context Protocol (MCP) servers. It provides an intuitive, feature-rich alternative to command-line MCP inspectors with real-time protocol analysis, capability discovery, and interactive tool execution.
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🔍 MCP PROBE ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🖥️ TUI │ │ 🔌 Transport │ │ 🔧 MCP Server │ │
│ │ Interface │◄──►│ Layer │◄──►│ (Any impl.) │ │
│ │ │ │ │ │ │ │
│ │ • Capabilities │ │ • HTTP/SSE │ │ • Tools (373+) │ │
│ │ • Search │ │ • WebSocket │ │ • Resources │ │
│ │ • Response View │ │ • STDIO │ │ • Prompts │ │
│ │ • Debugging │ │ • TCP │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────┤
│ │ 📊 REAL-TIME PROTOCOL ANALYSIS │
│ │ • Message Tracing • Session Management • Error Detection │
│ │ • JSON Validation • Response Formatting • Performance Metrics │
│ └─────────────────────────────────────────────────────────────────────────────┘
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
🚀 Why MCP Probe?
vs. Traditional MCP Inspector Tools
| Feature | Traditional CLI Tools | MCP Probe TUI |
|---|---|---|
| Capability Discovery | Manual JSON parsing | 🎯 Interactive browsing with search |
| Tool Execution | Complex curl commands | 🖱️ Point-and-click with parameter forms |
| Response Analysis | Raw JSON dumps | 📊 Multi-format viewer (Tree/Summary/Raw) |
| Error Debugging | Scattered logs | 🔍 Centralized error tracking with suggestions |
| Session Management | Stateless commands | 💾 Persistent sessions with history |
| Multi-Transport | Single transport focus | 🔌 HTTP/SSE, WebSocket, STDIO, TCP support |
| Real-time Monitoring | Snapshot-based | ⚡ Live protocol stream analysis |
Key Advantages
- 🎮 Interactive: Navigate 373+ tools with fuzzy search and auto-completion
- 🔍 Visual: Color-coded responses, scrollable viewers, progress indicators
- 📊 Analytical: Built-in protocol validation, message correlation, timing analysis
- 🛠️ Developer-Friendly: Session export, parameter templates, debugging hints
- 🚀 Fast: Rust-powered performance with async I/O and efficient TUI rendering
📦 Installation
MCP Probe offers multiple installation methods for your convenience:
📥 Pre-built Binaries (Recommended)
Download the latest binary for your platform from GitHub Releases:
- Linux (x86_64):
mcp-probe-x86_64-unknown-linux-gnu.tar.gz - Linux (ARM64):
mcp-probe-aarch64-unknown-linux-gnu.tar.gz - macOS (Intel):
mcp-probe-x86_64-apple-darwin.tar.gz - macOS (Apple Silicon):
mcp-probe-aarch64-apple-darwin.tar.gz - Windows (x86_64):
mcp-probe-x86_64-pc-windows-msvc.zip
🌐 One-liner Install (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/conikeec/mcp-probe/master/install.sh | bash
Custom installation directory:
curl -fsSL https://raw.githubusercontent.com/conikeec/mcp-probe/master/install.sh | INSTALL_DIR=~/.local/bin bash
Install specific version:
curl -fsSL https://raw.githubusercontent.com/conikeec/mcp-probe/master/install.sh | VERSION=v0.1.55 bash
🍺 Homebrew (macOS/Linux)
# Add the tap
brew tap conikeec/tap
# Install mcp-probe
brew install mcp-probe
# Or in one command
brew install conikeec/tap/mcp-probe
Update:
brew upgrade mcp-probe
📦 Cargo Install
cargo install mcp-cli
Note: The binary will be named mcp-probe even though the crate is mcp-cli.
🔨 From Source
# Clone the repository
git clone https://github.com/conikeec/mcp-probe.git
cd mcp-probe
# Build and install
cargo build --release
cargo install --path .
# Or run directly
cargo run -- --help
🛡️ Verification
All binaries are provided with SHA256 checksums. You can verify your download:
# Download checksum file
curl -LO https://github.com/conikeec/mcp-probe/releases/latest/download/mcp-probe-x86_64-unknown-linux-gnu.tar.gz.sha256
# Verify (Linux/macOS)
sha256sum -c mcp-probe-x86_64-unknown-linux-gnu.tar.gz.sha256
# Verify (macOS alternative)
shasum -a 256 -c mcp-probe-x86_64-apple-darwin.tar.gz.sha256
Quick Start
# Test with a local MCP server
cargo run -- debug --http-sse http://localhost:3000
# Connect to remote server
cargo run -- debug --http-sse https://api.example.com/mcp
# Use WebSocket transport
cargo run -- debug --websocket ws://localhost:8080/mcp
# STDIO mode for local development
cargo run -- debug --stdio python my_mcp_server.py
🎯 Section 1: MCP Client Usage
MCP Probe serves as a comprehensive MCP client for developers and integrators who need to interact with MCP servers programmatically or interactively.
🔧 Client Configuration
# Basic connection with default settings
mcp-probe debug --http-sse http://localhost:3000
# Advanced configuration
mcp-probe debug \
--http-sse http://localhost:3000 \
--timeout 30 \
--max-retries 3 \
--session-file my_session.json
💡 Interactive Workflow
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🎮 INTERACTIVE CLIENT WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1️⃣ DISCOVERY PHASE │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ ┌─ Connection ─┐ ┌─ Capabilities ─┐ ┌─ Search & Filter ─┐ │ │
│ │ │• Auto-detect │ │• Tools: 373 │ │• Fuzzy matching │ │ │
│ │ │• Protocol │ │• Resources: 1 │ │• Category filter │ │ │
│ │ │• Session ID │ │• Prompts: 3 │ │• Real-time index │ │ │
│ │ └──────────────┘ └─────────────────┘ └───────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ 2️⃣ INTERACTION PHASE │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ ┌─ Parameter Input ─┐ ┌─ Execution ─┐ ┌─ Response Analysis ─┐ │ │
│ │ │• Smart forms │ │• Real-time │ │• Multi-format view │ │ │
│ │ │• Type validation │ │• Progress │ │• Error highlighting │ │ │
│ │ │• Auto-completion │ │• Correlation │ │• Export options │ │ │
│ │ └───────────────────┘ └──────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ 3️⃣ ANALYSIS PHASE │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ ┌─ Session Review ─┐ ┌─ Error Analysis ─┐ ┌─ Export & Share ─┐ │ │
│ │ │• Message history │ │• Root cause hints │ │• JSON export │ │ │
│ │ │• Timing metrics │ │• Fix suggestions │ │• Session replay │ │ │
│ │ │• Protocol trace │ │• Debug logs │ │• Report sharing │ │ │
│ │ └─────────────────────└───────────────────┘ └─────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
🔍 Smart Capability Discovery
Fuzzy Search Engine: Find tools instantly among hundreds of capabilities
# Search examples (press '/' to activate)
/github # Find GitHub-related tools
/repo list # Find repository listing functions
/add_numbers # Direct tool name match
Auto-Parameter Detection: Intelligent form generation from JSON schemas
# Example: GitHub repo listing tool
┌─────────────────────────────────────┐
│ 📋 org (REQUIRED) [string] │
│ 💡 The organization name... │
│ > myorganization │
├─────────────────────────────────────┤
│ 📝 per_page (optional) [integer] │
│ 💡 Results per page (max 100) │
│ > 50 │
└─────────────────────────────────────┘
🚀 Execution Patterns
Direct Command Mode:
# Syntax: category.name {"param": "value"}
tools.add_numbers {"a": 10, "b": 20}
resources.readme_content
prompts.generate_docs {"style": "technical"}
Interactive Mode: Use TUI navigation for guided execution
Batch Mode: Execute multiple operations with session scripts
🔍 Section 2: Advanced Protocol Discovery & Session Management
MCP Probe features a sophisticated protocol discovery system that automatically detects and adapts to different MCP protocol versions, providing seamless connectivity across the evolving MCP ecosystem.
🚀 Intelligent Protocol Discovery
Automatic Protocol Detection: MCP Probe automatically detects the protocol version based on endpoint patterns and server behavior, eliminating manual configuration.
# MCP Probe automatically detects the protocol version from these patterns:
mcp-probe debug --http-sse http://localhost:8931/mcp # Modern Streamable HTTP
mcp-probe debug --http-sse http://localhost:8931/sse # Legacy HTTP+SSE
mcp-probe debug --stdio python server.py # Standard Transport
📊 Protocol Version Matrix
| Protocol Version | Spec Date | Endpoints | Session Management | Transport Method | Status |
|---|---|---|---|---|---|
| Modern Streamable HTTP | 2025-03-26 | /mcp | Mcp-Session-Id header | HTTP/SSE Streaming | ✅ Current |
| Legacy HTTP+SSE | 2024-11-05 | /sse, /events | sessionId query param | HTTP + Server-Sent Events | ✅ Supported |
| Standard Transport | 2025-03-26 | stdio | N/A (process-based) | Process I/O | ✅ Supported |
| WebSocket | 2025-03-26 | /ws, /websocket | Connection-based | WebSocket frames | 🔄 Planned |
| TCP | 2025-03-26 | Raw socket | Connection-based | TCP stream | 🔄 Planned |
🔧 Session Negotiation Workflows
Modern Streamable HTTP (Recommended)
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🌟 MODERN STREAMABLE HTTP WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Client MCP Probe Server │
│ │ │ │ │
│ │ │ │ │
│ │──── 1. Connection ──────►│────── POST /mcp ──────────►│ │
│ │ │ Mcp-Session-Id: [auto] │ │
│ │ │ │ │
│ │◄─── Session Created ─────│◄───── 200 + Session ───────│ │
│ │ │ Mcp-Session-Id: abc123 │ │
│ │ │ │ │
│ │──── 2. Initialize ──────►│────── POST /mcp ──────────►│ │
│ │ │ Mcp-Session-Id: abc123 │ │
│ │ │ {"method": "initialize"} │ │
│ │ │ │ │
│ │◄─── Capabilities ────────│◄───── 200 OK ──────────────│ │
│ │ │ Server capabilities │ │
│ │ │ │ │
│ │──── 3. Ready State ─────►│──────── Persistent ────────►│ │
│ │ │ Session Active │ │
│ │
│ ✅ Single endpoint simplicity 🔒 Header-based security │
│ ✅ Built-in session management ⚡ Automatic resumability │
│ ✅ Firewall-friendly 📊 Full streaming support │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Legacy HTTP+SSE (Backward Compatibility)
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 📡 LEGACY HTTP+SSE WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Client MCP Probe Server │
│ │ │ │ │
│ │ │ │ │
│ │──── 1. Discover ────────►│────── GET /events ────────►│ │
│ │ │ Accept: text/event-stream │ │
│ │ │ │ │
│ │◄─── Session Info ────────│◄───── SSE Stream ──────────│ │
│ │ │ data: {"sessionId": "xyz"}│ │
│ │ │ │ │
│ │──── 2. Initialize ──────►│─── POST /sse?sessionId=xyz─►│ │
│ │ │ {"method": "initialize"} │ │
│ │ │ │ │
│ │◄─── Capabilities ────────│◄───── 200 OK ──────────────│ │
│ │ │ Server capabilities │ │
│ │ │ │ │
│ │──── 3. SSE Listen ──────►│─── GET /sse?sessionId=xyz──►│ │
│ │ │ Accept: text/event-stream │ │
│ │ │ │ │
│ │◄─── Event Stream ────────│◄──── SSE Messages ─────────│ │
│ │ │ Continuous updates │ │
│ │
│ 🔄 Dual-endpoint architecture 📡 Query-based sessions │
│ 🔄 Separate discovery phase ⚡ Event-driven updates │
│ 🔄 Legacy compatibility 📊 SSE streaming support │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Standard Transport (Development)
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🔧 STANDARD TRANSPORT WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Client MCP Probe Process │
│ │ │ │ │
│ │ │ │ │
│ │──── 1. Spawn Process ───►│────── exec/spawn ─────────►│ │
│ │ │ python server.py │ │
│ │ │ │ │
│ │◄─── Process Ready ───────│◄───── stdin/stdout ────────│ │
│ │ │ Process initialization │ │
│ │ │ │ │
│ │──── 2. Initialize ──────►│────── JSON-RPC ───────────►│ │
│ │ │ via stdin │ │
│ │ │ │ │
│ │◄─── Capabilities ────────│◄───── JSON-RPC ────────────│ │
│ │ │ via stdout │ │
│ │ │ │ │
│ │──── 3. Bidirectional ───►│──── stdin/stdout pipes ────►│ │
│ │ │ Full-duplex communication │ │
│ │
│ 🚀 Direct process control 🔧 Perfect for development │
│ 🚀 No network complexity ⚡ Immediate debugging │
│ 🚀 Local filesystem access 📊 Full protocol support │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
🎯 Interactive vs Non-Interactive Command Sequences
Interactive Mode (TUI) - Guided Discovery
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🖥️ INTERACTIVE TUI WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: CONNECTION & DISCOVERY │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 🔌 Auto-detect Protocol → 📡 Establish Session → 🔍 Discover Tools │ │
│ │ • Parse endpoint URL • Header/query sessions • Fuzzy search │ │
│ │ • Detect /mcp vs /sse • Auto-resume capability • Category filter │ │
│ │ • Security validation • Background monitoring • Real-time index │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ Phase 2: INTERACTIVE EXECUTION │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 📋 Parameter Forms → ⚡ Real-time Execution → 📊 Response Analysis│ │
│ │ • Smart type detection • Progress indicators • Multi-format view │ │
│ │ • Schema-driven hints • Error correlation • Error highlighting │ │
│ │ • Auto-completion • Session persistence • Export options │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ Phase 3: ANALYSIS & DEBUGGING │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 📈 Session Review → 🔧 Error Investigation → 📤 Export & Share │ │
│ │ • Message history • Root cause analysis • JSON export │ │
│ │ • Timing metrics • Fix suggestions • Session replay │ │
│ │ • Protocol trace • Debug logs • Report generation │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ 🎮 User Experience: Visual, guided, exploratory │
│ ⌨️ Hotkeys: Tab navigation, / search, Enter execute │
│ 🔍 Features: Fuzzy search, parameter forms, real-time feedback │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Interactive Mode Commands:
# Launch TUI with automatic protocol detection
mcp-probe debug --http-sse http://localhost:8931/mcp
# TUI Navigation Flow:
# 1. Tab → Navigate between panels
# 2. / → Activate fuzzy search
# 3. ↑↓ → Browse capabilities
# 4. Enter → Open parameter form
# 5. Tab → Execute with parameters
# 6. V → Cycle response views
# 7. F2 → Save session
# Smart Parameter Forms:
# • Auto-detects field types from JSON Schema
# • Provides contextual hints and validation
# • Supports environment variable injection
# • Real-time syntax validation
Non-Interactive Mode (CLI) - Automation-Friendly
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ⚡ NON-INTERACTIVE CLI WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: RAPID CONNECTION │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 🚀 Direct Connect → 📊 Quick Capability Dump │ │
│ │ • Protocol auto-detection • Structured output │ │
│ │ • No user interaction • Machine-readable format │ │
│ │ • CI/CD friendly • Error codes for automation │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ Phase 2: BATCH EXECUTION │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 📝 Command Scripts → ⚙️ Automated Testing → 📄 Report Output │ │
│ │ • Direct tool execution • Comprehensive test suite • JSON/CSV export │ │
│ │ • Parameter validation • Protocol compliance • CI integration │ │
│ │ • Bulk operations • Performance monitoring • Success/fail codes│ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ Phase 3: PRODUCTION VALIDATION │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 🔍 Health Checks → 📊 Performance Analysis → 🚨 Alert Integration│ │
│ │ • Endpoint discovery • Response time metrics • Monitoring systems │ │
│ │ • Protocol compliance • Memory usage tracking • Automated alerts │ │
│ │ • Schema validation • Error rate analysis • Report webhooks │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ 🤖 Use Cases: CI/CD pipelines, monitoring, automation │
│ ⚡ Features: Zero interaction, structured output, exit codes │
│ 🔧 Integration: Scripts, Docker, Kubernetes health checks │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Non-Interactive Mode Commands:
# Quick capability overview
mcp-probe debug --http-sse http://localhost:8931/mcp --non-interactive
# Automated testing with reports
mcp-probe test --http-sse http://localhost:8931/mcp --report --output-dir ./reports
# Endpoint discovery for load balancers
mcp-probe test --discover http://api.company.com --report
# CI/CD integration examples
mcp-probe test --http-sse $MCP_SERVER_URL --fail-fast --timeout 30
if [ $? -eq 0 ]; then echo "✅ MCP server healthy"; else echo "❌ MCP server failed"; fi
# Batch operations for monitoring
mcp-probe validate --http-sse http://prod-server/mcp --suite compliance
🔍 Advanced Endpoint Discovery
Multi-Endpoint Discovery: MCP Probe can discover and test multiple MCP endpoints from a base URL, perfect for load balancers and multi-service deployments.
# Discover all MCP endpoints under a domain
mcp-probe test --discover https://api.company.com
# Discovery automatically tests these patterns:
# • https://api.company.com/mcp (Modern)
# • https://api.company.com/sse (Legacy)
# • https://api.company.com/events (Discovery)
# • https://api.company.com/v1/mcp (Versioned)
# • https://api.company.com/api/mcp (Nested)
# Output shows availability and capabilities:
✅ Modern Streamable HTTP - 47 tools, 3 resources, 2 prompts
✅ Legacy HTTP+SSE - 47 tools, 3 resources, 2 prompts
❌ Versioned API - Connection failed
⚠️ Nested API - Invalid response format
🛡️ Security & Session Management
Automatic Security Validation
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🔒 SECURITY VALIDATION │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 🛡️ Connection Security │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ • HTTPS enforcement for production URLs │ │
│ │ • Origin validation to prevent DNS rebinding │ │
│ │ • Session ID format validation (cryptographic strength) │ │
│ │ • Certificate verification for remote servers │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ 🔐 Session Management │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ • Automatic session discovery and renewal │ │
│ │ • Secure session ID generation and tracking │ │
│ │ • Background session monitoring for ephemeral servers │ │
│ │ • Session resumption after network interruptions │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ⚡ Performance & Reliability │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ • Connection pooling and keep-alive │ │
│ │ • Automatic retry with exponential backoff │ │
│ │ • Request timeout and circuit breaker patterns │ │
│ │ • Memory-efficient streaming for large responses │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
📈 Protocol Compliance Testing
Comprehensive Test Suites: MCP Probe includes extensive test suites for validating protocol compliance across different versions.
# Full protocol compliance testing
mcp-probe validate --http-sse http://localhost:8931/mcp --suite all
# Specific compliance areas:
mcp-probe validate --suite initialization # Connection & handshake
mcp-probe validate --suite capabilities # Tool/resource discovery
mcp-probe validate --suite schema # JSON Schema validation
mcp-probe validate --suite security # Security best practices
mcp-probe validate --suite performance # Response time & throughput
# Generate detailed compliance reports
mcp-probe validate --suite all --report --output-dir ./compliance-reports
🔧 Section 3: MCP Deployment Troubleshooting
MCP Probe excels as a diagnostic tool for MCP deployments, providing deep insights into protocol behavior, performance bottlenecks, and integration issues.
🚨 Diagnostic Features
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 🔍 TROUBLESHOOTING DASHBOARD │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 🔴 CONNECTION DIAGNOSTICS 🟡 PROTOCOL ANALYSIS │
│ ┌─────────────────────────────┐ ┌─────────────────────────────────────┐ │
│ │ • Transport validation │ │ • Message correlation │ │
│ │ • Authentication checks │ │ • Response time analysis │ │
│ │ • Firewall/proxy detection │ │ • Error pattern recognition │ │
│ │ • SSL/TLS verification │ │ • Capability compatibility │ │
│ └─────────────────────────────┘ └─────────────────────────────────────┘ │
│ │
│ 🟢 PERFORMANCE MONITORING 🟣 ERROR INVESTIGATION │
│ ┌─────────────────────────────┐ ┌─────────────────────────────────────┐ │
│ │ • Request/response latency │ │ • Stack trace analysis │ │
│ │ • Throughput measurement │ │ • JSON schema validation │ │
│ │ • Memory usage tracking │ │ • Serialization debugging │ │
│ │ • Connection stability │ │ • Integration compatibility │ │
│ └─────────────────────────────┘ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
🛠️ Common Issues & Solutions
Issue 1: Connection Failures
Symptoms: "Transport connection failed", "Connection refused"
Diagnosis with MCP Probe:
# 1. Test basic connectivity
mcp-probe debug --http-sse http://localhost:3000
# 2. Check different transports
mcp-probe debug --websocket ws://localhost:8080/mcp
mcp-probe debug --stdio python server.py
# 3. Monitor protocol flow
# Look for: Connection status, SSL handshake, authentication
Troubleshooting Guide:
- ✅ Server is running and listening on correct port
- ✅ Firewall rules allow connections
- ✅ SSL certificates are valid (for HTTPS)
- ✅ Authentication credentials are correct
Issue 2: Tool Execution Failures
Symptoms: "Serialization error", "Invalid parameters", "Tool not found"
Diagnosis with MCP Probe:
# 1. Verify tool discovery
# Navigate to Tools section, check tool list
# 2. Inspect parameter schemas
# Select tool -> Parameter form should show required fields
# 3. Check raw response data
# Use 'V' key to cycle through response formats
Common Root Causes:
- 🔧 Parameter Mismatch: Use Parameter Form to validate inputs
- 🔧 Tool Name Prefix Issues: Check clean vs. full tool names
- 🔧 JSON Format Errors: Validate JSON in response viewer
- 🔧 Server-Side Errors: Review error messages in message history
Issue 3: Performance Problems
Symptoms: Slow responses, timeouts, memory issues
Diagnosis with MCP Probe:
# 1. Monitor timing metrics
# Check message history for response times
# 2. Analyze message sizes
# Use Raw JSON view to inspect payload sizes
# 3. Track connection stability
# Watch for reconnection attempts in logs
📊 Protocol Debugging
Message Flow Analysis:
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 📈 PROTOCOL MESSAGE FLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Client MCP Probe Server │
│ │ │ │ │
│ │──── initialize ────────►│────── HTTP/POST ──────────►│ │
│ │ │ │ │
│ │◄─── init_response ──────│◄───── 200 OK ──────────────│ │
│ │ │ │ │
│ │──── tools/list ────────►│────── HTTP/POST ──────────►│ │
│ │ │ │ │
│ │◄─── tools_response ─────│◄───── 200 OK ──────────────│ │
│ │ │ │ │
│ │──── tools/call ────────►│────── HTTP/POST ──────────►│ │
│ │ │ (params) │ │
│ │ │ │ │
│ │◄─── result/error ───────│◄───── 200/400/500 ─────────│ │
│ │ │ │ │
│ │
│ 🔍 MCP Probe captures and analyzes each step: │
│ • Request correlation (session ID tracking) │
│ • Response time measurement │
│ • Error classification and suggestions │
│ • JSON schema validation │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
🎯 Environment Validation
Development Environment Checklist:
# 1. Server Implementation Validation
✅ Server responds to initialize request
✅ Capabilities are properly declared
✅ Tool schemas are valid JSON Schema
✅ Error responses include helpful messages
# 2. Integration Testing
✅ Authentication flow works correctly
✅ Session management is stable
✅ All transport types are supported
✅ Error handling is graceful
# 3. Performance Validation
✅ Response times are within SLA
✅ Memory usage is reasonable
✅ Concurrent requests are handled
✅ Rate limiting is implemented correctly
📚 Command Cheat Sheet
🔧 Basic Commands
# Connection
mcp-probe debug --http-sse <url> # HTTP Server-Sent Events
mcp-probe debug --websocket <url> # WebSocket connection
mcp-probe debug --stdio <command> # STDIO transport
mcp-probe debug --tcp <host:port> # Raw TCP connection
# Configuration
mcp-probe debug <transport> --timeout 30 # Request timeout
mcp-probe debug <transport> --max-retries 3 # Retry attempts
mcp-probe debug <transport> --session-file <f> # Session persistence
⌨️ TUI Navigation Hotkeys
Global Navigation
| Key | Action | Description |
|---|---|---|
Tab | Cycle Focus | Move between panels |
F1 | Help | Show/hide help dialog |
F2 | Save Session | Export current session |
F3 | Toggle JSON | Switch JSON view mode |
F4 | Clear History | Reset message history |
F5 | Environment | Set environment variables |
Q | Quit | Exit application |
Capability Browser
| Key | Action | Description |
|---|---|---|
Enter | Select | Open capability details |
↑/↓ | Navigate | Move through categories/items |
←/→ | Page | Previous/next page |
/ | Search | Activate fuzzy search |
Esc | Back | Return to categories |
Search Interface
| Key | Action | Description |
|---|---|---|
/ | Activate | Open search dialog |
Type | Query | Enter search terms |
↑/↓ | Navigate | Browse search results |
Enter | Select | Choose result |
Esc | Cancel | Close search |
Parameter Forms
| Key | Action | Description |
|---|---|---|
↑/↓ | Navigate | Move between fields (auto-edit) |
Type | Edit | Enter parameter values |
Enter | Save | Save field and move to next |
Tab | Execute | Run with current parameters |
Esc | Cancel | Close parameter form |
Response Viewer
| Key | Action | Description |
|---|---|---|
R | Open | View selected response |
V | View Mode | Cycle formats (Formatted/Raw/Tree/Summary) |
↑/↓ | Scroll V | Vertical scrolling |
←/→ | Scroll H | Horizontal scrolling |
PgUp/PgDn | Fast Scroll | Page up/down |
Home/End | Jump | Go to top/bottom |
Esc | Close | Exit response viewer |
🎮 Interactive Commands
Direct Tool Execution
# Syntax: category.name {json_params}
tools.add_numbers {"a": 10, "b": 20}
tools.github_list_repos {"org": "microsoft", "per_page": 10}
resources.readme_content
prompts.code_review {"language": "rust", "style": "detailed"}
Environment Variables
# Set variables for tool injection
KEY=value,API_TOKEN=secret123,ORG=myorg
# Variables automatically injected into tool calls
tools.api_call {} # Will include ORG=myorg if tool expects it
📁 File System Organization
MCP Probe automatically organizes all generated files in a clean, structured directory hierarchy in your home directory.
🏠 Directory Structure
~/.mcp-probe/
├── logs/ # All log files with timestamps
│ ├── mcp-probe-debug.log # TUI mode debug log
│ └── mcp-probe-YYYYMMDD_HHMMSS.log # CLI mode logs
├── reports/ # All generated reports with date prefixes
│ ├── YYYYMMDD-test-report-HHMMSS.json
│ ├── YYYYMMDD-validation-report-HHMMSS.json
│ └── YYYYMMDD-discovery-report-HHMMSS.json
├── sessions/ # Saved session files
│ └── debug-session-YYYYMMDD_HHMMSS.json
└── config/ # Configuration files
└── mcp-probe.toml
🗂️ Path Management Commands
# Show directory structure and usage
mcp-probe paths show
# Clean up old files (dry run)
mcp-probe paths cleanup --days 30
# Actually clean up files older than 7 days
mcp-probe paths cleanup --days 7 --force
# Open MCP Probe directory in file manager
mcp-probe paths open
📅 Automatic Date Prefixing
All reports are automatically prefixed with dates for easy organization:
- Format:
YYYYMMDD-report-name-HHMMSS.extension - Example:
20250622-test-report-143052.json - Benefits: Chronological sorting, easy cleanup, no file conflicts
🧹 Automated Cleanup
MCP Probe includes intelligent cleanup features:
# Show what would be cleaned up
mcp-probe paths cleanup --days 30
# Clean files older than 30 days
mcp-probe paths cleanup --days 30 --force
# The paths show command gives cleanup recommendations
mcp-probe paths show
🔍 Advanced Features
📊 Response Analysis Modes
1. Formatted View (Default)
- ✨ Syntax highlighting for JSON
- 📋 Structured analysis with field breakdown
- 🔍 Error highlighting and suggestions
- 📈 Content statistics and metadata
2. Raw JSON View
- 📄 Pretty-printed JSON output
- 🔍 Full response data visibility
- 📋 Copy-friendly format
- 🛠️ Debug-oriented display
3. Tree View
- 🌳 Hierarchical data visualization
- 📁 Collapsible object/array nodes
- 📊 Type indicators for each field
- 🎯 Easy navigation of nested structures
4. Summary View
- 📈 High-level response overview
- 📊 Key metrics and statistics
- ⚡ Quick status assessment
- 🎯 Action-oriented insights
🔒 Session Management
# Auto-save sessions
mcp-probe debug --http-sse http://localhost:3000 --session-file debug.json
# Session contains:
# • Connection parameters
# • Message history with timing
# • Error logs and diagnostics
# • Environment variables
# • Response cache for offline analysis
🌐 Multi-Transport Support
HTTP Server-Sent Events (Recommended)
mcp-probe debug --http-sse http://localhost:3000
# ✅ Most compatible with web servers
# ✅ Firewall-friendly
# ✅ Built-in error handling
WebSocket
mcp-probe debug --websocket ws://localhost:8080/mcp
# ✅ Real-time bidirectional communication
# ✅ Lower latency
# ⚠️ May require proxy configuration
STDIO (Development)
mcp-probe debug --stdio python my_server.py
# ✅ Perfect for local testing
# ✅ Direct process communication
# ⚠️ Limited to local development
TCP (Advanced)
mcp-probe debug --tcp localhost:9000
# ✅ Low-level protocol access
# ✅ Custom transport implementations
# ⚠️ Requires manual protocol handling
🛠️ Development & Contributing
Project Structure
mcp-probe/
├── crates/
│ ├── mcp-core/ # Core MCP protocol implementation
│ │ ├── src/
│ │ │ ├── client.rs # High-level MCP client
│ │ │ ├── transport/ # Transport layer abstractions
│ │ │ └── messages/ # Protocol message definitions
│ │ └── Cargo.toml
│ └── mcp-cli/ # TUI application
│ ├── src/
│ │ ├── tui.rs # Terminal UI implementation
│ │ ├── search.rs # Capability search engine
│ │ └── main.rs # CLI entry point
│ └── Cargo.toml
├── target/ # Build artifacts
├── Cargo.toml # Workspace configuration
└── README.md
Building from Source
# Debug build
cargo build
# Release build (recommended for performance)
cargo build --release
# Run tests
cargo test
# Run with logging
RUST_LOG=debug cargo run -- debug --http-sse http://localhost:3000
Contributing Guidelines
- 🍴 Fork the repository
- 🌿 Create a feature branch
- ✅ Add tests for new functionality
- 📝 Update documentation
- 🔄 Submit a pull request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🤝 Support & Community
- 📖 Documentation: docs.example.com/mcp-probe
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 🔧 Contributing: See CONTRIBUTING.md
🚀 Quick Examples
Example 1: Debug API Integration
# Connect to your MCP server
mcp-probe debug --http-sse https://api.yourservice.com/mcp
# 1. Verify connection and capabilities
# 2. Search for relevant tools: /api or /user
# 3. Test tool execution with real parameters
# 4. Analyze responses for integration issues
# 5. Export session for team sharing
Example 2: Performance Testing
# Set up performance monitoring
mcp-probe debug --http-sse http://localhost:3000 --session-file perf_test.json
# 1. Execute high-frequency tool calls
# 2. Monitor response times in message history
# 3. Check for memory leaks or connection issues
# 4. Review session file for timing analysis
Example 3: Development Workflow
# Local development testing
mcp-probe debug --stdio python my_mcp_server.py
# 1. Rapid iteration on server code
# 2. Test tool schemas and validation
# 3. Debug parameter handling
# 4. Verify error response formats
🔧 Development Automation & CI/CD
🚀 Automated Quality Checks
MCP Probe includes comprehensive automation for code quality and CI/CD:
Development Scripts
# Run all checks (formatting, clippy, tests)
./scripts/check.sh
# Auto-fix formatting and clippy issues
./scripts/fix.sh
# Publish to crates.io (with all checks)
./scripts/release.sh
Continuous Integration
Our GitHub Actions CI pipeline automatically runs:
- ✅ Code Formatting:
rustfmtensures consistent code style - ✅ Linting:
clippywith warnings as errors for code quality - ✅ Testing: Full test suite across Linux, macOS, and Windows
- ✅ Security Audit:
cargo auditfor vulnerability scanning - ✅ Code Coverage: Coverage reporting with codecov.io
- ✅ Documentation: Automatic docs.rs generation
Publishing Workflow
Releases to crates.io are fully automated:
- Trigger: Create a GitHub release
- Checks: All CI checks must pass
- Publish:
mcp-corepublished first (dependency)mcp-clipublished second
- Tagging: Git tag created automatically
Local Development Setup
# Install development tools
cargo install cargo-audit cargo-tarpaulin
# Set up git hooks (optional)
cargo install cargo-husky
Code Quality Standards
- Formatting: Enforced via
rustfmt.tomlconfiguration - Linting: Zero tolerance for clippy warnings
- Testing: Comprehensive test coverage required
- Documentation: All public APIs must be documented
📦 Crate Publishing
Both crates are available on crates.io:
Installation
# Install the CLI tool
cargo install mcp-cli
# Add core library to your project
[dependencies]
mcp-core = "0.1.0"
💝 Credits & Acknowledgments
Made with ❤️ in Rust
This project wouldn't be possible without:
- 🦀 Rust Programming Language - For memory safety, performance, and the amazing ecosystem that makes systems programming a joy
- 🤖 Anthropic - For creating the Model Context Protocol (MCP) specification and advancing the field of AI collaboration tools
- 🌟 The Rust Community - For the incredible crates that power MCP Probe: Ratatui, Tokio, Serde, Clap, and countless others
- 🛠️ Open Source Contributors - Every bug report, feature suggestion, and pull request makes this tool better
Special thanks to the Ratatui team for creating the foundation that makes our beautiful TUI possible! 🎨
🎯 MCP Probe: Making MCP protocol debugging as intuitive as it should be.