fix: resolve MCP server availability discrepancy issue#1339
fix: resolve MCP server availability discrepancy issue#1339atxtechbro wants to merge 1 commit intomainfrom
Conversation
Closes #1338 Problem: - Claude Code reported having access to MCP servers (github-write, git) that weren't actually connected - These servers appeared in internal tool approval list but weren't in mcp/mcp.json - After removing servers and running setup.sh, Claude still thought they were available due to cached information Solution: 1. Added documentation clarifying which MCP servers are actually available vs approved 2. Created diagnostic tool to help users troubleshoot MCP server availability 3. Updated setup.sh to clear Claude Code's cache when MCP config changes 4. Added cross-references in existing MCP documentation Changes: - New: bin/claude-mcp-diagnostic - diagnostic tool for MCP issues - New: docs/mcp-server-availability.md - comprehensive guide on server availability - Modified: setup.sh - clears ~/.claude/statsig/* cache on MCP config changes - Modified: docs/mcp-*.md - added references to new availability guide This ensures Claude Code correctly reports MCP server availability after configuration changes.
|
⏳ Code review in progress. Analyzing for code quality issues and best practices. Detailed findings will be posted upon completion. Using Amazon Q Developer for GitHubAmazon Q Developer1 is an AI-powered assistant that integrates directly into your GitHub workflow, enhancing your development process with intelligent features for code development, review, and transformation. Slash Commands
FeaturesAgentic Chat Code Review CustomizationYou can create project-specific rules for Amazon Q Developer to follow:
Example rule: FeedbackTo provide feedback on Amazon Q Developer, create an issue in the Amazon Q Developer public repository. For more detailed information, visit the Amazon Q for GitHub documentation. Footnotes
|
![amazon-q-developer[bot]](https://avatars.githubusercontent.com/in/1220912?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overall Assessment
This PR effectively addresses the MCP server availability discrepancy issue with a comprehensive solution that includes diagnostic tooling, clear documentation, and automatic cache management. The approach is well-structured and addresses the root cause of the problem.
Key Strengths
- Comprehensive diagnostic tool: The
claude-mcp-diagnosticscript provides valuable troubleshooting capabilities for users experiencing MCP server issues - Clear documentation: The new
mcp-server-availability.mdguide clearly explains the difference between approved and actually available servers - Automatic cache clearing: The setup.sh modification prevents stale cache issues by automatically clearing Claude Code's cache when MCP configuration changes
- Cross-references: Good integration with existing documentation through appropriate cross-references
Critical Changes Requested
- File termination issues: Both
bin/claude-mcp-diagnosticanddocs/mcp-server-availability.mdlack proper newline termination, which violates POSIX standards - Enhanced error handling: The cache clearing logic in setup.sh could be more robust with better empty directory handling
- Improved diagnostics: The MCP server listing test could capture and display actual output for better troubleshooting
Minor Improvements
- Version extraction regex could be more flexible for different version formats
- JSON configuration example needs clarification about environment variable substitution
- Cache clearing recommendations could include safety checks
The solution effectively resolves the reported issue and provides users with the tools needed to understand and troubleshoot MCP server availability. With the suggested improvements, this will be a solid addition to the dotfiles repository.
| echo -e " - Try restarting your terminal session" | ||
| echo -e " - Run: ${GREEN}claude logout && claude login${NC}" | ||
|
|
||
| echo -e "\n${BLUE}${DIVIDER}${NC}" No newline at end of file |
There was a problem hiding this comment.
The script lacks a proper file termination with a newline character, which could cause issues on some systems and violates POSIX standards. Files should end with a newline character.
| # 1. Check Claude Code installation | ||
| echo -e "${YELLOW}1. Claude Code Installation:${NC}" | ||
| if command -v claude &>/dev/null; then | ||
| CLAUDE_VERSION=$(claude --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown") |
There was a problem hiding this comment.
The regex pattern for version extraction could be more robust. The current pattern [0-9]+\.[0-9]+\.[0-9]+ might miss pre-release versions or versions with additional components like 1.2.3-beta or 1.2.3.4. Consider using a more flexible pattern to handle various version formats.
| # 4. Test MCP server listing | ||
| echo -e "${YELLOW}4. Claude MCP Server List:${NC}" | ||
| echo "Running: claude mcp list" | ||
| if claude mcp list 2>/dev/null; then | ||
| echo -e "${GREEN}✓ MCP servers listed successfully${NC}" | ||
| else |
There was a problem hiding this comment.
The MCP server listing test could provide more useful diagnostic information. Currently it only shows success/failure, but capturing and displaying the actual output would help users understand what servers are detected versus what they expect.
| # 4. Test MCP server listing | |
| echo -e "${YELLOW}4. Claude MCP Server List:${NC}" | |
| echo "Running: claude mcp list" | |
| if claude mcp list 2>/dev/null; then | |
| echo -e "${GREEN}✓ MCP servers listed successfully${NC}" | |
| else | |
| # 4. Test MCP server listing | |
| echo -e "${YELLOW}4. Claude MCP Server List:${NC}" | |
| echo "Running: claude mcp list" | |
| MCP_OUTPUT=$(claude mcp list 2>&1) | |
| if [[ $? -eq 0 ]]; then | |
| echo -e "${GREEN}✓ MCP servers listed successfully${NC}" | |
| echo " Detected servers:" | |
| echo "$MCP_OUTPUT" | sed 's/^/ /' | |
| else | |
| echo -e "${RED}✗ Failed to list MCP servers${NC}" | |
| echo " Error output:" | |
| echo "$MCP_OUTPUT" | sed 's/^/ /' | |
| fi |
|
|
||
| # Clear Claude Code's stale MCP cache to ensure it picks up config changes | ||
| # This prevents Claude from reporting removed servers as still available | ||
| if [[ -d "$HOME/.claude/statsig" ]]; then | ||
| echo "Clearing Claude Code cache to sync MCP server availability..." | ||
| rm -rf "$HOME/.claude/statsig"/* 2>/dev/null || true |
There was a problem hiding this comment.
The cache clearing logic has a potential issue with the wildcard expansion. If the directory is empty, the rm -rf "$HOME/.claude/statsig"/* command might fail or behave unexpectedly. The current || true handles this, but it would be cleaner to check if files exist first.
| # Clear Claude Code's stale MCP cache to ensure it picks up config changes | |
| # This prevents Claude from reporting removed servers as still available | |
| if [[ -d "$HOME/.claude/statsig" ]]; then | |
| echo "Clearing Claude Code cache to sync MCP server availability..." | |
| rm -rf "$HOME/.claude/statsig"/* 2>/dev/null || true | |
| # Clear Claude Code's stale MCP cache to ensure it picks up config changes | |
| # This prevents Claude from reporting removed servers as still available | |
| if [[ -d "$HOME/.claude/statsig" ]]; then | |
| echo "Clearing Claude Code cache to sync MCP server availability..." | |
| if [[ -n "$(ls -A "$HOME/.claude/statsig" 2>/dev/null)" ]]; then | |
| rm -rf "$HOME/.claude/statsig"/* 2>/dev/null || true | |
| echo -e "${GREEN}✓ Claude Code cache cleared${NC}" | |
| else | |
| echo -e "${GREEN}✓ Claude Code cache already empty${NC}" | |
| fi | |
| fi |
|
|
||
| - [MCP Environment Setup](mcp-environment.md) | ||
| - [MCP Client Integration](mcp-client-integration.md) | ||
| - [Setting up all MCP servers](../mcp/setup-all-mcp-servers.sh) No newline at end of file |
There was a problem hiding this comment.
The documentation file lacks a proper file termination with a newline character, which could cause issues with some text processing tools and violates POSIX standards. Files should end with a newline character.
| 2. Add configuration to `mcp/mcp.json`: | ||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "playwright": { /* existing config */ }, | ||
| "github": { |
There was a problem hiding this comment.
The JSON configuration example shows environment variable substitution with ${GITHUB_TOKEN}, but it's not clear if this syntax is actually supported by the MCP configuration system. Consider clarifying whether this is literal text that should be replaced manually or if the system supports environment variable expansion.
| 2. Add configuration to `mcp/mcp.json`: | |
| ```json | |
| { | |
| "mcpServers": { | |
| "playwright": { /* existing config */ }, | |
| "github": { | |
| 2. Add configuration to `mcp/mcp.json`: | |
| ```json | |
| { | |
| "mcpServers": { | |
| "playwright": { /* existing config */ }, | |
| "github": { | |
| "command": "mcp-server-github", | |
| "args": [], | |
| "env": { | |
| "GITHUB_TOKEN": "your-actual-token-here" | |
| } | |
| } | |
| } | |
| } |
Note: Replace "your-actual-token-here" with your actual GitHub token, or use environment variable expansion if supported by your MCP client.
| echo -e "${BLUE}${DIVIDER}${NC}" | ||
|
|
||
| echo -e "\n1. To clear potential cache issues:" |
There was a problem hiding this comment.
The cache clearing recommendation uses a potentially dangerous wildcard pattern. If ~/.claude/statsig contains unexpected files or subdirectories, this could remove more than intended. Consider using a more targeted approach or adding safety checks.
| echo -e "${BLUE}${DIVIDER}${NC}" | |
| echo -e "\n1. To clear potential cache issues:" | |
| echo -e "\n1. To clear potential cache issues:" | |
| echo -e " ${GREEN}# Check what will be removed first:${NC}" | |
| echo -e " ${GREEN}ls -la ~/.claude/statsig/${NC}" | |
| echo -e " ${GREEN}# Then clear the cache:${NC}" | |
| echo -e " ${GREEN}rm -rf ~/.claude/statsig/*${NC}" |
1 participant
Summary
Fixes the issue where Claude Code incorrectly reports having access to MCP servers that aren't actually connected.
Closes #1338
Problem
mcp/mcp.jsonand running setup.sh, Claude still reported them as availableSolution
claude-mcp-diagnosticto help users troubleshoot MCP server availability issuesChanges
bin/claude-mcp-diagnostic- Diagnostic tool for MCP server issuesdocs/mcp-server-availability.md- Comprehensive guide on server availability vs. approval listsetup.sh- Now clears~/.claude/statsig/*cache when updating MCP configdocs/mcp-environment.md- Added reference to availability guidedocs/mcp-client-integration.md- Added important note about server availabilityTesting
setup.shto apply the changesclaude-mcp-diagnosticto verify MCP server configurationclaude mcp listto confirm only configured servers appearls ~/.claude/statsig/should be empty after setupImpact