Content
[](https://terminaltrove.com/mcp-probe/)
# 🔍 MCP Probe - Advanced MCP Protocol Debugger & Interactive Client
[](https://www.rust-lang.org)
[](LICENSE)
[](Cargo.toml)
**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](https://github.com/conikeec/mcp-probe/releases/latest):
- **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)
```bash
curl -fsSL https://raw.githubusercontent.com/conikeec/mcp-probe/master/install.sh | bash
```
**Custom installation directory:**
```bash
curl -fsSL https://raw.githubusercontent.com/conikeec/mcp-probe/master/install.sh | INSTALL_DIR=~/.local/bin bash
```
**Install specific version:**
```bash
curl -fsSL https://raw.githubusercontent.com/conikeec/mcp-probe/master/install.sh | VERSION=v0.1.55 bash
```
### 🍺 Homebrew (macOS/Linux)
```bash
# 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:**
```bash
brew upgrade mcp-probe
```
### 📦 Cargo Install
```bash
cargo install mcp-cli
```
**Note**: The binary will be named `mcp-probe` even though the crate is `mcp-cli`.
### 🔨 From Source
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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**:
```bash
# 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.
```bash
# 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:**
```bash
# 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:**
```bash
# 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.
```bash
# 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.
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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
```bash
# 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)
```bash
mcp-probe debug --http-sse http://localhost:3000
# ✅ Most compatible with web servers
# ✅ Firewall-friendly
# ✅ Built-in error handling
```
#### WebSocket
```bash
mcp-probe debug --websocket ws://localhost:8080/mcp
# ✅ Real-time bidirectional communication
# ✅ Lower latency
# ⚠️ May require proxy configuration
```
#### STDIO (Development)
```bash
mcp-probe debug --stdio python my_server.py
# ✅ Perfect for local testing
# ✅ Direct process communication
# ⚠️ Limited to local development
```
#### TCP (Advanced)
```bash
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
```bash
# 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
1. 🍴 Fork the repository
2. 🌿 Create a feature branch
3. ✅ Add tests for new functionality
4. 📝 Update documentation
5. 🔄 Submit a pull request
---
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## 🤝 Support & Community
- **📖 Documentation**: [docs.example.com/mcp-probe](docs.example.com/mcp-probe)
- **🐛 Issues**: [GitHub Issues](https://github.com/your-org/mcp-probe/issues)
- **💬 Discussions**: [GitHub Discussions](https://github.com/your-org/mcp-probe/discussions)
- **🔧 Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md)
---
## 🚀 Quick Examples
### Example 1: Debug API Integration
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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**: `rustfmt` ensures consistent code style
- ✅ **Linting**: `clippy` with warnings as errors for code quality
- ✅ **Testing**: Full test suite across Linux, macOS, and Windows
- ✅ **Security Audit**: `cargo audit` for vulnerability scanning
- ✅ **Code Coverage**: Coverage reporting with codecov.io
- ✅ **Documentation**: Automatic docs.rs generation
#### Publishing Workflow
Releases to crates.io are fully automated:
1. **Trigger**: Create a GitHub release
2. **Checks**: All CI checks must pass
3. **Publish**:
- `mcp-core` published first (dependency)
- `mcp-cli` published second
4. **Tagging**: Git tag created automatically
#### Local Development Setup
```bash
# 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.toml` configuration
- **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:
- **[mcp-core](https://crates.io/crates/mcp-core)**: Core MCP protocol implementation
- **[mcp-cli](https://crates.io/crates/mcp-cli)**: Interactive TUI debugger
#### Installation
```bash
# 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](https://rust-lang.org/)** - For memory safety, performance, and the amazing ecosystem that makes systems programming a joy
- 🤖 **[Anthropic](https://anthropic.com/)** - 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.**
Connection Info
You Might Also Like
everything-claude-code
Complete Claude Code configuration collection - agents, skills, hooks,...
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
cc-switch
All-in-One Assistant for Claude Code, Codex & Gemini CLI across platforms.
servers
Model Context Protocol Servers
servers
Model Context Protocol Servers
Agent-Reach
Give your AI agent eyes to see the entire internet. Read & search Twitter,...