mcp-spy

Debug MCP server communication. Use for troubleshooting MCP integrations, viewing traffic, and analyzing latency.

Repository: johnlindquist/claude
Last source activity: December 12, 2025 at 06:09
Detected SKILL.md language: English
Stars: 25
Forks: 7

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/johnlindquist/claude --skill mcp-spy

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

# All errors
grep -i "error" ~/.claude/debug/mcp-*.log

# Parse error responses
grep "\"error\":" ~/.claude/debug/mcp-*.log | jq '.'

# Test server connection
curl -X POST http://localhost:3000/mcp/list_tools \
  -H "Content-Type: application/json" \
  -d '{}'

# View server logs (if running as process)
tail -f logs/mcp-server.log

# Or in terminal running server
# Logs appear in stdout

# Call tool directly
curl -X POST http://localhost:3000/mcp/call_tool \
  -H "Content-Type: application/json" \
  -d '{
    "name": "beads_ready",
    "args": {}
  }'

# Pretty print JSON messages
grep "message" ~/.claude/debug/mcp-*.log | jq '.'

# Check request format
gemini -m pro -o text -e "" "Validate this MCP request format:

$(grep "request" ~/.claude/debug/mcp-*.log | tail -1)

Check:
1. Required fields present
2. Types correct
3. Schema compliance"

# Check if port in use
lsof -i :3000

# Check server process
ps aux | grep mcp

# Start with verbose
node server/index.ts --verbose

# List available tools
curl http://localhost:3000/mcp/list_tools | jq '.tools[].name'

# Check tool registration
grep "registerTool\|toolRegistry" server/*.ts

# Profile tool execution
time curl -X POST http://localhost:3000/mcp/call_tool \
  -H "Content-Type: application/json" \
  -d '{"name": "slow_tool", "args": {}}'

# Check for blocking operations
grep -i "await\|sync" tools/slow_tool/index.ts

# Find malformed JSON
grep -B 5 "JSON\|parse" ~/.claude/debug/mcp-*.log | grep -i error

# Validate JSON
echo '{"test": ...}' | jq '.'

# Real-time log monitoring
tail -f ~/.claude/debug/mcp-*.log | grep --line-buffered "tool_use\|result"

# Count calls per tool
grep "tool_use" ~/.claude/debug/mcp-*.log | \
  grep -oP '"name":"[^"]*"' | \
  sort | uniq -c | sort -rn

#!/bin/bash
# mcp-health.sh

echo "=== MCP Server Health ==="

# Check server
if curl -s http://localhost:3000/health > /dev/null 2>&1; then
  echo "Server: UP"
else
  echo "Server: DOWN"
fi

# Recent errors
ERRORS=$(grep -c "error" ~/.claude/debug/mcp-*.log 2>/dev/null || echo 0)
echo "Recent errors: $ERRORS"

# Tool count
TOOLS=$(curl -s http://localhost:3000/mcp/list_tools 2>/dev/null | jq '.tools | length' || echo 0)
echo "Registered tools: $TOOLS"

mcp-spy

Install options

Review the source files

MCP Spy - Debug MCP Communication

Overview

Traffic Analysis

View Recent Traffic

Filter by Type

Latency Analysis

Measure Response Times

Find Slow Calls

MCP Spy - Debug MCP Communication

Overview

Traffic Analysis

View Recent Traffic

Filter by Type

Latency Analysis

Measure Response Times

Find Slow Calls

Failed Request Analysis

Find Failures

Common Issues

MCP Server Debug

Check Server Status

Server Logs

Test Tool Directly

Protocol Debugging

Inspect Messages

Validate Requests

Troubleshooting Guide

Server Won't Start

Tool Not Found

Slow Responses

JSON Parse Errors

Monitoring

Watch Traffic Live

Traffic Stats

Health Dashboard

Best Practices

name	mcp-spy
description	Debug MCP server communication. Use for troubleshooting MCP integrations, viewing traffic, and analyzing latency.

mcp-spy

Source facts

Install options

Review the source files

More from this repository

More from this repository

MCP Spy - Debug MCP Communication

Overview

Traffic Analysis

View Recent Traffic

Filter by Type

Latency Analysis

Measure Response Times

Find Slow Calls

MCP Spy - Debug MCP Communication

Overview

Traffic Analysis

View Recent Traffic

Filter by Type

Latency Analysis

Measure Response Times

Find Slow Calls

Failed Request Analysis

Find Failures

Common Issues

MCP Server Debug

Check Server Status

Server Logs

Test Tool Directly

Protocol Debugging

Inspect Messages

Validate Requests

Troubleshooting Guide

Server Won't Start

Tool Not Found

Slow Responses

JSON Parse Errors

Monitoring

Watch Traffic Live

Traffic Stats

Health Dashboard

Best Practices