skills.rest
saintgo7
saintgo7COMMUNITY
Explore all skills by this author →
GitHub

gem-llm-debug-mcp

Diagnose MCP server failures in the GEM-LLM Claude Code environment.

Updated Apr 4, 2026
Search Tags:#troubleshooting#claude code#mcp#npx#settings.json#log inspection#token auth
One-click install
npx skills add https://github.com/saintgo7/claude-skills --skill gem-llm-debug-mcp
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: gem-llm-debug-mcp
Source: https://github.com/saintgo7/claude-skills/tree/main/gem-llm-debug-mcp
Command: npx skills add https://github.com/saintgo7/claude-skills --skill gem-llm-debug-mcp

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

gem-llm-debug-mcp helps you diagnose why an MCP (Model Context Protocol) server fails to start or connect, why MCP tools don’t appear, or why specific MCP servers (like GitHub, filesystem, Firecrawl, or Mermaid) are misconfigured.

Core Features & Use Cases

  • MCP configuration verification: Checks ~/.claude/settings.json for valid mcpServers definitions (command/args/env) and detects placeholder tokens that were never replaced.
  • Package resolution checks: Uses npx -y <package> --help dry-runs to confirm the MCP server package name and availability.
  • Runtime log inspection & symptom-based branching: Finds relevant Claude Code MCP logs and tail-checks stderr to map symptoms to likely root causes (missing tools, permission errors, GitHub 401/403, npx hangs).

Quick Start

Tell the AI to debug your MCP startup and tool-listing problem by analyzing your ~/.claude/settings.json, running npx -y <mcp-package> --help resolution checks, and then locating and tailing the relevant MCP-related logs for the failure symptom you observe.

Frequently Asked Questions about gem-llm-debug-mcp

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

FAQPage Schema
How do I fix MCP server connection failures in Claude Code?▼

Fix MCP server connection failures by validating the `mcpServers` configuration in `~/.claude/settings.json`, running `npx` package resolution checks, and tailing stderr logs to isolate the root cause.

Why are my MCP tools missing or not appearing in the Claude Code environment?▼

MCP tools are missing when the server fails to start properly or the package name is incorrect. Inspect MCP stderr logs and perform `npx -y <package> --help` dry-runs to confirm server availability and resolve startup errors.

How to troubleshoot GitHub 401 or 403 errors with MCP integrations?▼

Troubleshoot GitHub 401/403 MCP errors by safely inspecting your environment variables in `~/.claude/settings.json` to detect placeholder authentication tokens that were never replaced with valid credentials.

Does this approach work for debugging filesystem permission denials in MCP servers?▼

Yes, this approach works for debugging filesystem permission denials by inspecting MCP logs and mapping runtime symptoms to root causes, resolving configuration issues for servers like Firecrawl, Mermaid, or Pandoc.

What is the best way to diagnose unclear MCP server runtime errors?▼

The best way to diagnose unclear MCP server runtime errors is tailing the MCP stderr logs to map specific symptoms to likely root causes, bypassing unclear log outputs to determine corrective action.

Related Skills

Explore More Software Engineering Skills→
minorun365minorun365
97

sync-settings

Synchronize Claude Code settings bidirectionally with a GitHub repository.

Community
Intermediate
mgkyawzayyamgkyawzayya
1

debug

Diagnose container agent issues by inspecting logs, mounts, and environment variables.

Community
Intermediate
Mattyreed1Mattyreed1

mcp-setup

Configures and debugs MCP server integrations for Claude Desktop and Claude Code.

Community
Advanced
lorenzovenicelorenzovenice
19

debug

Diagnose containerized AI agent issues via log analysis and configuration verification.

Community
Advanced