debug-mcp-servers

Diagnose and fix MCP server loading failures in Claude Code.

Updated Nov 9, 2025

Search Tags:#debugging #configuration #mcp #environment-variables #claude-code #server-loading

Ready to run

npx skills add https://github.com/markusstrasser/skills --skill debug-mcp-servers

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: debug-mcp-servers
Source: https://github.com/markusstrasser/skills/tree/main/debug-mcp-servers
Command: npx skills add https://github.com/markusstrasser/skills --skill debug-mcp-servers

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Debug why MCP servers aren't loading in Claude Code. Use this when user reports MCPs not appearing in /mcp list despite being configured.

Core Features & Use Cases

Systematic checks of MCP configuration across user and project scopes.
Guidance to verify local override settings and environment prerequisites to restore normal loading.
Real-world scenario: diagnose a hidden setting blocking all .mcp.json servers.

Quick Start

Run the debugging flow to identify and fix MCP loading issues in Claude Code.

Frequently Asked Questions about debug-mcp-servers

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

FAQPage Schema

Why are my MCP servers not loading in Claude Code despite being configured?▼

MCP server loading issues often stem from hidden settings in .claude/settings.local.json, missing environment variables, or misconfigurations across user and project scopes. Validating configuration with claude mcp list/get and inspecting local overrides identifies the blocker.

How do I diagnose MCP configuration issues across different scopes in Claude Code?▼

Diagnose MCP configuration by running claude mcp list/get to validate actual settings, then inspect user, project, and local scopes including .claude/settings.local.json. This systematic check reveals hidden overrides or missing environment prerequisites preventing servers from appearing in /mcp.

What causes configured MCP servers to not appear in the /mcp list?▼

Configured MCP servers fail to appear in the /mcp list when local settings override project configurations, environment variables are missing, or server prerequisites are unmet. Inspecting .claude/settings.local.json and verifying environment factors isolates the loading block.

Can a hidden local setting block all .mcp.json servers from loading in Claude?▼

Yes, a hidden setting in .claude/settings.local.json can block all .mcp.json servers from loading. Inspecting local override settings and validating the configuration with claude mcp list/get helps locate and remove the blocking entry to restore normal loading.

How do environment variables affect MCP server loading in Claude Code?▼

Environment variables provide necessary prerequisites for MCP server loading. If required variables are missing or incorrectly set, servers fail to load and do not appear in /mcp. Verifying environment configurations ensures servers initialize correctly across user and project scopes.