mcp-debug

<objective>
Enable Claude to directly test and debug MCP servers during development sessions. Call
MCP tools directly, see raw responses, and diagnose issues in real-time.
</objective>

<when-to-use>
Use this skill when:
- Testing an MCP server during development
- Debugging why an MCP tool isn't returning expected data
- Exploring what operations an MCP server supports
- Verifying MCP server connectivity and auth
- Working across application and MCP server repos simultaneously
</when-to-use>

<prerequisites>
This skill uses `mcptools` (https://github.com/f/mcptools) for MCP communication.

Before using MCP debug commands, ensure mcptools is installed:

```bash
# Check if installed
which mcp || which mcpt

# Install via Homebrew (macOS)
brew tap f/mcptools && brew install mcp

# Or via Go
go install github.com/f/mcptools/cmd/mcptools@latest
```

If mcptools is not found, install it first before proceeding. </prerequisites>

<config-discovery>
MCP server configs can come from multiple sources:

1. **Claude Code config**: `~/.config/claude/claude_desktop_config.json`
2. **Direct URL**: `http://localhost:9900` with optional auth
3. **mcptools aliases**: Previously saved with `mcp alias add`

To find available servers:

```bash
# Scan all known config locations
mcp configs scan

# List saved aliases
mcp alias list
```

</config-discovery>

<commands>

## List Tools

See what tools/operations an MCP server provides:

```bash
# HTTP server with bearer auth
mcp tools http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

# Using an alias
mcp tools server-alias

# Pretty JSON output
mcp tools --format pretty http://localhost:9900
```

## Call a Tool

Execute an MCP tool directly with parameters:

```bash
# Call with JSON params
mcp call describe --params '{"action":"describe"}' http://localhost:9900 \
  --headers "Authorization=Bearer $AUTH_TOKEN"

# Gateway-style (single tool with action param)
mcp call server-tool --params '{"action":"messages_recent","params