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.

45 stars 4 forksAI, LLMs & Agents

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add pjt222/agent-almanac --skill troubleshoot-mcp-connection
Manual install
git 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-connection

Personal 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/"`
Read the full skill on GitHub

Details

Skill name
troubleshoot-mcp-connection
Path
i18n/caveman-lite/skills/troubleshoot-mcp-connection/SKILL.md
License
MIT
Repo updated
18 November 2026

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

45

pjt222/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.

Software DevelopmentIn 1 list

Adaptic

45

pjt222/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.

OtherIn 1 list

Add Puzzle Type

45

pjt222/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.

Testing & QAIn 1 list

Unleash the Agents

45

pjt222/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.

AI, LLMs & AgentsIn 1 list

Track Ml Experiments

45

pjt222/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.

AI, LLMs & AgentsIn 1 list

Use Case Triage

43

AlsKozlov/ru-legal

Triage AI use case по уровню риска — PROCEED / IMPACT ASSESS / RESTRICT / PROHIBIT. РФ specifics: combination 152-ФЗ ПДн + sectoral overlay (Банк России для финансовых; Минздрав для мед; Минобрнауки для education; и т.д.) + национальная стратегия AI (Указ Президента 490/2019).

AI, LLMs & Agents

Browse the most popular Claude skills, all ai, llms & agents skills, or write your own with the skills generator.