skills.rest
iterate
iterateOFFICIAL
Explore all skills by this author →
Website𝕏@iterateGitHub

debug-mcp-server

Debug MCP server connections using the official MCP Inspector.

198|19|Updated Sep 15, 2025
Search Tags:#debugging#authentication#mcp#tool calls#transport#inspector#stdio sse http
One-click install
npx skills add https://github.com/iterate/iterate --skill debug-mcp-server
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debug-mcp-server
Source: https://github.com/iterate/iterate/tree/main/.agents/skills/debug-mcp-server
Command: npx skills add https://github.com/iterate/iterate --skill debug-mcp-server

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps you rapidly debug why a Model Context Protocol (MCP) server won’t connect or can’t successfully initialize and execute tool calls, reducing time lost to guesswork.

Core Features & Use Cases

  • Inspector-based verification: Use the official MCP Inspector to confirm transport behavior (stdio, SSE, HTTP) and to inspect initialization, auth, tools/resources/prompts, and schemas.
  • Targeted CLI smoke tests: Reproduce failures by running scripted tool calls like tools/list and the smallest failing tools to validate the exact failure point.
  • Auth-safe debugging: Pass required headers (e.g., bearer tokens) without committing secrets by using your Doppler-run environment.

Quick Start

Use the MCP Inspector to verify the server can respond to tools/list, then reproduce the failing tool call with the same transport and exact auth headers.

Frequently Asked Questions about debug-mcp-server

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug an MCP server that won't connect or execute tool calls?▼

Debug MCP server connection issues by using the official MCP Inspector to validate transport behavior, inspect initialization, authentication, and tool availability before reproducing the failing tool calls.

Why does my MCP server authentication fail when making tool calls?▼

MCP server authentication fails when required headers like bearer tokens are missing or incorrect; debug this by passing required auth headers safely through your Doppler-run environment during Inspector CLI smoke tests.

How do I troubleshoot missing tools or resources on my stdio or SSE MCP server?▼

Troubleshoot missing MCP tools or resources by running the tools/list command in the MCP Inspector UI and CLI to verify the server can respond and confirm tool schemas across stdio, SSE, and HTTP transports.

Can I use the MCP Inspector to reproduce a failing tool call with specific transport parameters?▼

Yes, you can use the MCP Inspector in CLI mode to reproduce the smallest failing tool calls by applying the exact transport parameters and authentication headers to validate the precise failure point.

What is the best way to verify MCP server initialization and tool availability across different transports?▼

Verify MCP server initialization and tool availability by running the official MCP Inspector in both UI and CLI modes to inspect schemas and confirm transport behavior across stdio, SSE, and Streamable HTTP connections.

MCP server tool calls can't be reproduced in client environments, how do I find the exact failure point?▼

Find the exact MCP tool call failure point by running scripted CLI smoke tests in the MCP Inspector, executing tools/list before the smallest failing tools with correct headers and transport parameters.

Related Skills

Explore More Software Engineering Skills→
MarbleSodasMarbleSodas

1password

Retrieve and inject 1Password secrets into Hermes command workflows.

Community
Intermediate
matt-rileymatt-riley
1

github-actions-failure-triage

Diagnose failing GitHub Actions runs and map failures to workflow YAML.

Community
Advanced
yu-iskwyu-iskw

develop-mcp-server-ts

Develop MCP servers in TypeScript with the official SDK.

Community
Intermediate
nicholasglazernicholasglazer
27

status

Diagnose gnosis-mcp health via connectivity, schema, and corpus checks.

Community
Intermediate