mcp-debug_skill

This skill lets you test and debug MCP servers directly, view raw responses, and diagnose issues during development sessions.

Python

16

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill technickai/ai-coding-config --skill mcp-debug

SKILL.md6.1 KB

Overview

This skill enables direct, hands-on testing and debugging of MCP servers during development. It provides commands and workflows to call MCP tools, inspect raw responses, and diagnose connectivity, auth, and tool behavior in real time. Use it to quickly reproduce issues and validate server capabilities.

How this skill works

The skill uses the mcptools command-line client to discover server configs, list available tools, call specific operations, and open an interactive shell or web UI for visual inspection. It exposes patterns for gateway-style servers (single tool with an action param), shows how to pass auth headers, and explains how to parse returned JSON content that often contains nested JSON strings.

When to use it

When developing or testing an MCP server locally
When a tool returns unexpected or empty data
To explore what operations an MCP server supports
When verifying server connectivity and authentication
While working across application and MCP server repositories simultaneously

Best practices

Install and verify mcptools before debugging (brew or go install)
Start with a health check (curl /health) before deeper calls
Use mcp tools to list operations, then mcp call with --params for targeted tests
For gateway servers, call the single server-tool with action and params rather than guessing tool names
Pipe mcptools JSON output through jq to extract the inner text JSON, then pretty-print for inspection
Keep sensitive tokens out of logs; use environment variables for Authorization headers

Example use cases

List all available MCP tools to confirm server API surface: mcp tools <url>
Describe gateway-style operations: mcp call server-tool --params '{"action":"describe"}'
Test a specific operation with parameters and pretty output: mcp call server-tool --params '{"action":"resource_list","params":{"limit":3}}' --format pretty
Open a persistent shell to run multiple commands without retyping headers: mcp shell <url>
Run the mcptools web UI to inspect and replay calls in a browser

FAQ

Install via Homebrew (brew tap f/mcptools && brew install mcp) or with Go: go install github.com/f/mcptools/cmd/mcptools@latest. Confirm with which mcp or which mcpt.

Why does the tool output look like nested JSON strings?

MCP responses often wrap the actual result inside content[0].text as a JSON string. Extract it with jq: mcp call ... --format json | jq -r '.content[0].text' | jq .