<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

undefined

<objective> 支持Claude在开发会话中直接测试和调试MCP服务器。可直接调用MCP工具、查看原始响应，实时诊断问题。 </objective> <when-to-use> 在以下场景使用此技能： - 开发过程中测试MCP服务器 - 调试MCP工具未返回预期数据的问题 - 探索MCP服务器支持的操作 - 验证MCP服务器的连通性和身份认证 - 同时在应用和MCP服务器代码仓库中开展工作 </when-to-use> <prerequisites> 本技能使用 `mcptools` (https://github.com/f/mcptools) 进行MCP通信。

在使用MCP调试命令前，请确保已安装mcptools：

bash

undefined

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

go install github.com/f/mcptools/cmd/mcptools@latest


如果未找到mcptools，请先安装再继续操作。 </prerequisites>

<config-discovery>
MCP服务器配置可来自多个来源：

1. **Claude Code配置**：`~/.config/claude/claude_desktop_config.json`
2. **直接URL**：带可选身份认证的 `http://localhost:9900`
3. **mcptools别名**：此前通过 `mcp alias add` 保存的别名

要查找可用的服务器：

```bash

Scan all known config locations

mcp configs scan

List saved aliases

mcp alias list


</config-discovery>

<commands>

mcp alias list


</config-discovery>

<commands>

List Tools

列出工具

See what tools/operations an MCP server provides:

bash

undefined

查看MCP服务器提供的工具/操作：

bash

undefined

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

undefined

mcp tools --format pretty http://localhost:9900

undefined

Call a Tool

调用工具

Execute an MCP tool directly with parameters:

bash

undefined

直接带参数执行MCP工具：

bash

undefined

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

undefined

mcp call tool_name --params '{}' --format pretty http://localhost:9900

undefined

Interactive Shell

交互式Shell

Open persistent connection for multiple commands:

bash

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

打开持久连接执行多条命令：

bash

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

Then in shell:

mcp> tools

mcp> call describe --params '{"action":"describe"}'

undefined

undefined

Web Interface

Web界面

Visual debugging in browser:

bash

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

在浏览器中进行可视化调试：

bash

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

Opens http://localhost:41999


</commands>

<example-server>


</commands>

<example-server>

Example: Gateway Pattern MCP Server

示例：网关模式MCP服务器

Many MCP servers use a gateway pattern - a single tool with an

action

parameter for progressive disclosure:

bash

undefined

很多MCP服务器采用网关模式——单个工具带有

action

参数用于逐步展示功能：

bash

undefined

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"

undefined

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

undefined

Common Debug Commands

常用调试命令

bash

undefined

bash

undefined

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>

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>

连接被拒绝

检查服务器是否正在运行：
```
curl http://localhost:9900/health
```
检查进程是否运行（例如
```
ps aux | grep mcp-server
```
）
检查日志：
```
tail -20 /path/to/server/logs/error.log
```

401未授权

验证令牌：
```
echo $AUTH_TOKEN
```
检查mcptools头语法：
```
Authorization=Bearer
```
（mcptools使用
```
=
```
，HTTP使用
```
:
```
）

未找到工具

网关模式服务器使用带
```
action
```
参数的单个工具
不是直接使用工具名称——请查阅服务器文档获取工具名称

结果为空/报错

检查服务器权限和配置
运行可用的服务器专属诊断工具
检查服务器日志中的错误

未找到mcptools

安装：
```
brew tap f/mcptools && brew install mcp
```

或：

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>

验证连通性
bash
```
curl -s http://localhost:9900/health
```

列出可用工具

bash

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

获取操作说明

bash

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

测试特定操作

bash

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

如果出现问题，检查日志
bash
```
tail -50 /path/to/server/logs/error.log
```

</workflow> <output-interpretation>

Reading MCP Results

解读MCP结果

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>

MCP工具返回的JSON结构如下：

json

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

内层的

text

字段包含实际结果，通常是需要解析的JSON字符串。可使用

jq

提取：

bash

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

</output-interpretation>

mcp-debug

Original

Translation

Check if installed

Check if installed

Install via Homebrew (macOS)

Install via Homebrew (macOS)

Or via Go

Or via Go

Scan all known config locations

Scan all known config locations

List saved aliases

List saved aliases

List Tools

列出工具

HTTP server with bearer auth

HTTP server with bearer auth

Using an alias

Using an alias

Pretty JSON output

Pretty JSON output

Call a Tool

调用工具

Call with JSON params

Call with JSON params

Gateway-style (single tool with action param)

Gateway-style (single tool with action param)

Format output as pretty JSON

Format output as pretty JSON

Interactive Shell

交互式Shell

Then in shell:

Then in shell:

mcp> tools

mcp> tools

mcp> call describe --params '{"action":"describe"}'

mcp> call describe --params '{"action":"describe"}'

Web Interface

Web界面

Opens http://localhost:41999

Opens http://localhost:41999

Example: Gateway Pattern MCP Server

示例：网关模式MCP服务器

List all operations

List all operations

Call specific operation

Call specific operation

Common Debug Commands

常用调试命令

Check if server is responding

Check if server is responding

List all tools via mcptools

List all tools via mcptools

Get operation descriptions

Get operation descriptions

Test a specific operation

Test a specific operation

Common Issues

常见问题

Typical Debug Session

典型调试会话

Reading MCP Results

解读MCP结果