MCP Server Troubleshooting

Problem: Server configured but tools don't load

Symptom: Server is in config but ToolSearch returns nothing and tools aren't in the deferred list.

Cause: Server was added by editing settings.json or mcp.json directly instead of using claude mcp add.

Fix:

# Register properly
claude mcp add-json server-name '{"command":"...","args":[...],"env":{...}}' -s user

# Verify
claude mcp get server-name
# Should show "Status: ✓ Connected"

# Restart Claude Code for tools to appear in session

Prevention: NEVER edit ~/.claude/settings.json mcpServers or ~/.claude/mcp.json directly. Always use claude mcp add or claude mcp add-json.

Problem: Server shows "Failed to connect"

Symptom: claude mcp list shows ✗ Failed to connect.

Possible causes: 1. Dependency not installed — The npx package may need to download. Try running the command manually to see errors. 2. Missing credentials — Check env vars point to files that exist. 3. Service not running — For HTTP/SSE servers (Figma, Chrome DevTools), the app must be running first. 4. Python venv broken — For google-analytics, the venv may need rebuilding.

Debug steps:

# Test the server manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' > /tmp/mcp-test.txt
ENVVAR=value npx -y @package/name < /tmp/mcp-test.txt > /tmp/mcp-out.txt 2> /tmp/mcp-err.txt &
sleep 8; kill %1 2>/dev/null
cat /tmp/mcp-out.txt  # Should have JSON response
cat /tmp/mcp-err.txt  # Check for errors

Problem: Google OAuth token expired

Symptom: Server connects but API calls fail with auth errors.

Fix: 1. Delete the tokens file for the affected service: - Gmail: ~/.gmail-mcp/credentials.json - Drive: ~/.config/google-drive-mcp/tokens.json - Calendar: ~/.config/google-calendar-mcp/tokens.json 2. Restart Claude Code 3. The server will open a browser for re-authentication

Problem: Tools load mid-session but disappear after restart

Symptom: Works in current session but not after restart.

Cause: Server was added to project scope instead of user scope.

Fix:

claude mcp remove server-name
claude mcp add-json server-name '...' -s user  # Note: -s user

Problem: Duplicate server entries across config files

Locations Claude Code reads (in order of precedence): 1. ~/.claude.json — Primary config (managed by claude mcp commands) 2. ~/.claude/mcp.json — Secondary global config 3. .mcp.json — Project-level config (in working directory)

If the same server name appears in multiple files, behavior is unpredictable. Keep everything in ~/.claude.json via claude mcp add -s user.

Config file reference

Problem: HTTP MCP needs auth but mcp-remote fails

Symptom: Incompatible auth server: does not support dynamic client registration

Cause: mcp-remote requires the OAuth server to support RFC 7591 dynamic client registration. Some services (like Slack) only support client_secret_post and will never work with mcp-remote.

How to check before trying mcp-remote:

curl https://SERVICE/.well-known/oauth-authorization-server | jq .token_endpoint_auth_methods_supported
# If result is ["client_secret_post"] only → use static Bearer token
# If result includes "none" → mcp-remote / PKCE may work

Fix — use static Bearer token in HTTP headers:

# Create a Slack app at api.slack.com, install it, get xoxp- token
# Then register as HTTP type with Authorization header:
claude mcp add-json slack '{
  "type": "http",
  "url": "https://mcp.slack.com/mcp",
  "headers": {
    "Authorization": "Bearer xoxp-YOUR-TOKEN-HERE"
  }
}' -s user

See slack.md for the full Slack setup process.