Claude Code MCP Server Incident Response Guide

When your MCP server stops responding or throws errors during a Claude Code session, productivity comes to a halt. This guide provides a systematic approach to diagnosing, troubleshooting, and recovering from MCP server incidents using practical commands and recovery procedures.

Identifying MCP Server Failures

MCP (Model Context Protocol) servers extend Claude Code’s capabilities by connecting to external tools and services. Common failure indicators include:

Server timeout errors after startup
Authentication failures when connecting to services
Tool call failures with “server not available” messages
Unexpected disconnections during active sessions

Before diving into fixes, verify that the issue is indeed MCP-related. Run this command in your terminal:

claude --verbose

Look for error messages containing “MCP” or the specific server name. The verbose output shows connection attempts and helps narrow down whether the failure occurs at startup or during runtime.

Initial Diagnostic Steps

Check Server Status

The first step is verifying which MCP servers are currently registered and their status. Claude Code stores server configurations in your user directory. Check the configuration file:

cat ~/.claude/settings.json | grep -A 5 "mcp"

This reveals your active MCP server configurations. If servers appear missing from the output, the configuration may have been corrupted or overwritten.

Review Server Logs

MCP servers typically write logs to standard error output. When starting Claude Code, capture stderr to a file for analysis:

claude 2> mcp-debug.log

Search the log for error patterns:

grep -i "error\|exception\|timeout" mcp-debug.log

Most MCP servers follow predictable error patterns. Connection timeouts usually indicate network issues or server unavailability, while authentication errors point to credential problems.

Common Incident Types and Solutions

Connection Timeout Issues

If an MCP server fails to connect within the expected timeout window, the server may be unreachable or overloaded. For instance, if you’re using the filesystem MCP server and it times out, try restarting it:

# Kill existing server process
pkill -f "mcp-server-filesystem"

# Restart with explicit path
npx @modelcontextprotocol/server-filesystem /your/project/path

The tdd skill and pdf skill both rely on MCP servers for file operations. When these fail, your testing and documentation workflows stall.

Authentication Failures

Many MCP servers require API keys or tokens. If authentication fails, check your environment variables:

echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

For servers requiring OAuth or API tokens, ensure credentials are set before starting Claude Code. Create a startup script that exports necessary variables:

#!/bin/bash
export GITHUB_TOKEN="your-token-here"
export NOTION_API_KEY="your-key-here"
claude "$@"

Server Process Crashes

When an MCP server process crashes unexpectedly, it often leaves orphaned processes. Clean up before restarting:

# List all node processes related to MCP
ps aux | grep mcp

# Kill specific server
kill -9 $(ps aux | grep "server-name" | grep -v grep | awk '{print $2}')

The frontend-design skill and other visual tools depend on stable MCP server processes. Crashes here affect design iteration workflows.

Advanced Recovery Procedures

Configuration Reset

If diagnostics reveal configuration corruption, reset the MCP settings:

# Backup current config
cp ~/.claude/settings.json ~/.claude/settings.json.backup

# Remove MCP section (Claude will recreate on next startup)
# Edit settings.json and remove mcpServers object

After resetting, restart Claude Code with verbose logging to capture the fresh configuration process.

Skill Dependency Verification

Some skills depend on specific MCP servers. The supermemory skill requires memory server connectivity, while database skills need their respective MCP servers running. Verify skill requirements:

# List available skills
ls ~/.claude/skills/

# Check skill dependencies
cat ~/.claude/skills/skill-name.md | grep -i "requires\|mcp"

When troubleshooting, disable non-essential skills temporarily to isolate the problematic server. Re-enable them one at a time after recovery.

Port Conflicts

MCP servers bind to specific ports. Port conflicts cause immediate startup failures. Check for existing listeners:

lsof -i :port-number

Common MCP ports include 3000, 8080, and 5432. If another process occupies the required port, either terminate that process or reconfigure the MCP server to use a different port.

Prevention Strategies

Health Check Scripts

Implement a startup health check that verifies MCP server availability before launching Claude Code:

#!/bin/bash
# mcp-healthcheck.sh

for server in "server-filesystem" "server-github" "server-brave-search"; do
  if ! pgrep -f "$server" > /dev/null; then
    echo "Warning: $server not running"
  fi
done

Run this script before starting Claude Code sessions that require specific MCP functionality.

Configuration Versioning

Track MCP configuration changes in git. Add your settings to version control:

cd ~/.claude
git init
git add settings.json
git commit -m "MCP configuration baseline"

This enables quick rollback if a configuration change introduces problems.

Monitoring and Alerts

For teams running MCP servers in production environments, implement monitoring. The algorithmic-art skill and similar creative tools benefit from uptime monitoring when integrated into production pipelines.

Summary

MCP server incidents disrupt Claude Code workflows but follow recognizable patterns. Start with verbose logging to identify the failure type, then apply the appropriate recovery procedure. Connection issues yield to restart and network checks, while authentication problems require credential verification. For complex issues, configuration reset combined with health check scripts provides a reliable recovery path.

Regular maintenance—including configuration versioning, health checks, and monitoring—prevents incidents before they impact productivity. Keep your MCP servers running smoothly and maintain uninterrupted development sessions.

Built by theluckystrike — More at zovo.one