skills.rest
markusstrasser
markusstrasserCOMMUNITY
Explore all skills by this author →
GitHub

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
One-click install
npx skills add https://github.com/markusstrasser/skills --skill debug-mcp-servers
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
rhpdsrhpds

14-debugging-troubleshooting

Diagnose Claude Code MCP servers, tool failures, permissions, and context issues.

Official
Intermediate
nathanvalenathanvale
6

mcp-manager

Manage MCP server configuration in Claude Code including adding, listing, enabling, and disabling servers.

Community
Basic
andy-austinandy-austin

connect-mcp-server

Connect MCP servers to Claude Code via HTTP, stdio, and SSH transports.

Community
Advanced
web-infra-devweb-infra-dev
12.8k

rspack-sftrace

Trace Rust function calls and convert them to perfetto protobuf traces.

Official
Advanced