Troubleshoot MCP Connection
Diagnose and fix MCP server connection issues between Claude Code, Claude Desktop, and MCP servers. Covers Windows argument parsing, authentication failures, transport issues, and platform-specific debugging. Use when Claude Code or Claude Desktop fails to connect to an MCP server, when MCP tools don't appear in sessions, on "cannot attach the server" errors, when a working connection has stopped, or when setting up MCP on a new machine.
Install
npx skills add pjt222/agent-almanac --skill troubleshoot-mcp-connectiongit clone --depth 1 https://github.com/pjt222/agent-almanac.git /tmp/agent-almanac
mkdir -p ~/.claude/skills
cp -r /tmp/agent-almanac/i18n/caveman-lite/skills/troubleshoot-mcp-connection ~/.claude/skills/troubleshoot-mcp-connectionPersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# Troubleshoot MCP Connection Diagnose and resolve MCP server connection failures. ## When to Use - Claude Code or Claude Desktop fails to connect to an MCP server - MCP tools don't appear in sessions - "Cannot attach the server" errors - Connection was working but stopped - Setting up MCP on a new machine ## Inputs - **Required**: Error message or symptom description - **Required**: Which client (Claude Code, Claude Desktop, or both) - **Required**: Which MCP server (mcptools, Hugging Face, custom) - **Optional**: Recent changes to configuration or environment ## Procedure ### Step 1: Identify the Client and Configuration **Claude Code** (WSL): ```bash # View MCP configuration claude mcp list claude mcp get server-name # Configuration stored in cat ~/.claude.json | python3 -m json.tool ``` **Claude Desktop** (Windows): ```bash # Configuration file location cat "/mnt/c/Users/$USER/AppData/Roaming/Claude/claude_desktop_config.json" ``` **Got:** Configuration file is located and readable, showing the MCP server entries with command, args, and env fields. **If fail:** If the config file does not exist or is empty, the server was never configured. Follow the `configure-mcp-server` skill to set it up from scratch. ### Step 2: Test Server Independently **R mcptools**: ```bash # Test if R can start the server "/mnt/c/Program Files/R/R-4.5.0/bin/Rscript.exe" -e "mcptools::mcp_server()" ``` If this fails: - Check R path exists: `ls "/mnt/c/Program Files/R/"`
Details
- Skill name
troubleshoot-mcp-connection- Repository
- pjt222/agent-almanac
- Path
i18n/caveman-lite/skills/troubleshoot-mcp-connection/SKILL.md- License
- MIT
- Repo updated
- 18 November 2026
- Listed in
- BehiSecc/awesome-claude-skills
FAQ
What does the Troubleshoot MCP Connection skill do?
Diagnose and fix MCP server connection issues between Claude Code, Claude Desktop, and MCP servers. Covers Windows argument parsing, authentication failures, transport issues, and platform-specific debugging. Use when Claude Code or Claude Desktop fails to connect to an MCP server, when MCP tools don't appear in sessions, on "cannot attach the server" errors, when a working connection has stopped, or when setting up MCP on a new machine.
How do I install the Troubleshoot MCP Connection skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add pjt222/agent-almanac --skill troubleshoot-mcp-connection. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is Troubleshoot MCP Connection popular?
It lives in pjt222/agent-almanac, which has 45 GitHub stars and 4 forks, and is included in 1 curated skill list.
Related skills
Adapt Architecture
45pjt222/agent-almanac
Execute structural metamorphosis using strangler fig migration, chrysalis phases, and interface preservation. Covers transformation planning, parallel running, progressive cutover, rollback design, and post-metamorphosis stabilization for system architecture evolution. Use when assess-form has classified the system as READY for transformation, when migrating from monolith to microservices, when replacing a core subsystem while dependents continue operating, or when any architectural change must be gradual rather than big-bang.
Adaptic
45pjt222/agent-almanac
Master skill composing the 5-step synoptic cycle for panoramic synthesis across multiple domains. Orchestrates meditate, expand-awareness, observe, awareness, integrate-gestalt, and express-insight into a coherent process that produces unified understanding rather than sequential compromise. Use when a problem genuinely spans 3+ domains and the interactions between domains matter more than depth in any one, when sequential analysis feels like compromise rather than integration, or before major architectural decisions affecting multiple stakeholders.
Add Puzzle Type
45pjt222/agent-almanac
Scaffold a new puzzle type across all 10+ pipeline integration points in jigsawR. Creates the core puzzle module, wires it into the unified pipeline (generation, positioning, rendering, adjacency), adds ggpuzzle geom/stat layers, updates DESCRIPTION and config.yml, extends the Shiny app, and creates a comprehensive test suite. Use when adding a completely new puzzle type to the package or following the 10-point integration checklist to ensure nothing is missed end-to-end.
Unleash the Agents
45pjt222/agent-almanac
Launch all available agents in parallel waves for open-ended hypothesis generation on problems where the correct domain is unknown. Use when facing a cross-domain problem with no clear starting point, when single-agent approaches have stalled, or when diverse perspectives are more valuable than deep expertise. Produces a ranked hypothesis set with convergence analysis and adversarial refinement.
Track Ml Experiments
45pjt222/agent-almanac
Set up MLflow tracking server for experiment management, configure autologging for popular ML frameworks, compare runs with metrics and visualizations, and manage artifacts in remote storage backends for reproducible machine learning workflows. Use when starting a new ML project that requires experiment tracking, migrating from manual logs to automated tracking, comparing multiple training runs systematically, or building reproducible ML workflows with full lineage tracking.
Use Case Triage
43AlsKozlov/ru-legal
Triage AI use case по уровню риска — PROCEED / IMPACT ASSESS / RESTRICT / PROHIBIT. РФ specifics: combination 152-ФЗ ПДн + sectoral overlay (Банк России для финансовых; Минздрав для мед; Минобрнауки для education; и т.д.) + национальная стратегия AI (Указ Президента 490/2019).
Browse the most popular Claude skills, all ai, llms & agents skills, or write your own with the skills generator.