<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:

•Claude Code config: ~/.config/claude/claude_desktop_config.json
•Direct URL: http://localhost:9900 with optional auth
•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":{"limit":5}}' \
  http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

# Format output as pretty JSON
mcp call tool_name --params '{}' --format pretty http://localhost:9900

Interactive Shell

Open persistent connection for multiple commands:

bash

mcp shell http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

# Then in shell:
# mcp> tools
# mcp> call describe --params '{"action":"describe"}'

Web Interface

Visual debugging in browser:

bash

mcp web http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"
# Opens http://localhost:41999

</commands> <example-server>

Example: Gateway Pattern MCP Server

Many MCP servers use a gateway pattern - a single tool with an action parameter for progressive disclosure:

bash

# List all operations
mcp call server-tool --params '{"action":"describe"}' http://localhost:9900 \
  --headers "Authorization=Bearer $AUTH_TOKEN"

# Call specific operation
mcp call server-tool --params '{"action":"resource_list","params":{"limit":5}}' \
  http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

Common Debug Commands

bash

# Check if server is responding
curl -s http://localhost:9900/health

# List all tools via mcptools
mcp tools http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

# Get operation descriptions
mcp call server-tool --params '{"action":"describe"}' --format pretty \
  http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

# Test a specific operation
mcp call server-tool --params '{"action":"resource_list","params":{"limit":3}}' \
  --format pretty http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

</example-server> <troubleshooting>

Common Issues

Connection refused

•Check if server is running: curl http://localhost:9900/health
•Check if process is running (e.g., ps aux | grep mcp-server)
•Check logs: tail -20 /path/to/server/logs/error.log

401 Unauthorized

•Verify token: echo $AUTH_TOKEN
•Check mcptools header syntax: Authorization=Bearer (mcptools uses =, HTTP uses :)

Tool not found

•Gateway pattern servers use a single tool with action param
•Not direct tool names - check server documentation for tool name

Empty/error results

•Check server permissions and configuration
•Run server-specific diagnostics if available
•Check server logs for errors

mcptools not found

•Install: brew tap f/mcptools && brew install mcp
•Or: go install github.com/f/mcptools/cmd/mcptools@latest

</troubleshooting> <workflow>

Typical Debug Session

•
Verify connectivity
bash
```
curl -s http://localhost:9900/health
```

•

List available tools

bash

mcp tools http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

•

Get operation descriptions

bash

mcp call server-tool --params '{"action":"describe"}' --format pretty \
  http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

•

Test specific operation

bash

mcp call server-tool --params '{"action":"resource_list","params":{"limit":3}}' \
  --format pretty http://localhost:9900 --headers "Authorization=Bearer $AUTH_TOKEN"

•

If issues, check logs

bash

tail -50 /path/to/server/logs/error.log

</workflow> <output-interpretation>

Reading MCP Results

MCP tools return JSON with this structure:

json

{
  "content": [
    {
      "type": "text",
      "text": "{ ... actual result as JSON string ... }"
    }
  ]
}

The inner text field contains the actual result, often as a JSON string that needs parsing. Use jq to extract:

bash

mcp call server-tool --params '...' --format json http://localhost:9900 \
  --headers "Authorization=Bearer $AUTH_TOKEN" \
  | jq -r '.content[0].text' | jq .

</output-interpretation>