Capture MCP Tools Changed notifications - notifications/prompts/list_changed notifications

[AchintyaAshok]

Requesting to add support for https://modelcontextprotocol.io/specification/2024-11-05/server/tools#list-changed-notification.

Goal: when the MCP server emits a notification that its tools have changed, I would like Claude to refresh the tool list from the server and reflect the change in the /mcp menu for that server.

[coygeek]

Hey there,

This is a great suggestion. It would be a huge quality-of-life improvement for anyone using MCP servers that have dynamic tools.

I took a look through the latest documentation you provided to see if there was a manual workaround. From what I can tell, the current implementation seems to discover tools when the server is first connected.

The /mcp slash command lets you manage the connection and view the server's tools, but the docs don't mention a way to manually trigger a refresh of the tool list after the initial connection.

The MCP documentation page (en/docs/claude-code/mcp) mentions:

MCP prompts are dynamically discovered from connected servers.

And:

MCP commands are automatically available when:

• An MCP server is connected and active
• The server exposes prompts through the MCP protocol
• The prompts are successfully retrieved during connection

This seems to confirm that the tool/prompt discovery happens at connection time. I couldn't find any mention of the notifications/tools/list_changed event specifically.

For now, I guess the only way to force a refresh would be to remove and re-add the server with claude mcp remove <server-name> and claude mcp add .... Not ideal, but it might get the job done if you know the tool list has changed.

Having Claude Code listen for that list_changed notification and automatically refresh would be the perfect solution. It would make integrations feel much more seamless.

Fingers crossed the dev team sees this and adds it to the roadmap

[chipgpt]

I would like to see this as well. Currently there is support for dynamic tools in Cursor and VSCode but not in Claude Code.

[stefancplace]

It would be amazing to use this feature 👍

[kolkov]

Expert Implementation Approach for Dynamic MCP Tool Management

TL;DR

We've successfully implemented a comprehensive solution for this exact problem in our GODA MCP server (Go-based). Here's what we learned and recommend for Claude Code implementation.

Current Problem Analysis

Based on our research and implementation experience:

1. Claude Code uses conversation-level caching - mcp_list_tools items persist for entire conversations
2. notifications/tools/list_changed are sent but ignored by Claude Desktop/Code
3. Current workaround requires manual /mcp reconnection or app restart
4. VSCode and Cursor support this, but Claude Code doesn't

Our Working Solution

We implemented a server-side intelligent categorization system that works around Claude Code's limitations:

Architecture Overview

Server-Side (Go):
├── Tool Categorization (6 priority-based categories)
├── Dynamic Handler Registration/Deregistration
├── Environment-driven Configuration
└── MCP Notifications (for future compatibility)

Client Interaction:
├── set_tool_categories - Dynamic switching
├── get_tool_categories - Current status
├── Tool Profiles - Workflow-based presets
└── Proper handler cleanup on category changes

Key Technical Insights

1. Handler Persistence vs Tool Discovery

// CRITICAL: Must clear both tools AND handlers
s.tools = make(map[string]Tool)
s.handlers = make(map[string]HandlerFunc) // ← This is key!

2. Conversation-Level Cache Compatibility

// Send notification even though Claude Code ignores it (future-proof)
func (s *Server) notifyToolsListChanged() {
    notification := NewNotification("notifications/tools/list_changed", map[string]interface{}{})
    s.encoder.Encode(notification)
}

3. Token Optimization By Design

// Default: 38/81 tools (53% reduction), Minimal: 22/81 tools (75% reduction)
func GetEnabledCategories() []string {
    if envCategories == "" {
        return []string{"core", "checkpoint", "lighthouse"} // Smart defaults
    }
    // ... category parsing
}

Recommended Implementation for Claude Code

Phase 1: Basic Notification Support

// Listen for MCP notifications
onNotification('notifications/tools/list_changed', async () => {
    await this.refreshToolsList();
    this.invalidateConversationCache(); // Clear mcp_list_tools
});

Phase 2: Advanced Cache Strategy

interface MCPCacheStrategy {
    type: 'conversation' | 'session' | 'none';
    ttl?: number;
    invalidateOnNotification: boolean;
}

// Allow users to configure caching behavior
const config: MCPCacheStrategy = {
    type: 'session', // Cache per session, not conversation
    invalidateOnNotification: true
};

Phase 3: Smart Tool Management

// Server-side categorization support
interface ToolCategory {
    name: string;
    priority: number;
    enabled: boolean;
}

// Client-side filtering UI
const toolFilter = {
    categories: ['core', 'checkpoint'],
    maxTools: 25, // Performance limit
    autoOptimize: true
};

Real-World Performance Impact

Our implementation achieves:

• 53% token reduction with lighthouse included (38/81 tools)
• 75% token reduction in minimal mode (22/81 tools)
• Immediate tool deactivation when categories disabled
• Zero server restarts required for configuration changes

Testing Strategy

We verified handler deregistration works correctly:

# Tools available with lighthouse category
✅ mcp__goda__get_web_vitals() -> Success

# Switch to minimal categories
✅ set_tool_categories("core,checkpoint") -> 22 tools loaded

# Verify handler deregistration
❌ mcp__goda__get_web_vitals() -> "MCP error -32601: Tool not found"

Migration Path for Existing Servers

1. Implement category system in your MCP server
2. Add set_tool_categories command for dynamic switching
3. Clear handlers alongside tools during category changes
4. Send notifications for future Claude Code compatibility

Community Impact

This approach solves the broader MCP ecosystem problem:

• Reduces context bloat (50k+ tokens issue mentioned in related issues)
• Improves UX with workflow-based tool profiles
• Maintains backward compatibility with existing MCP clients
• Future-proofs for when Claude Code implements proper notification support

Code References

Full implementation available in our GODA project (Go):

• Categories System: internal/mcp/categories.go
• Handler Management: internal/mcp/server.go
• MCP Notifications: notifyToolsListChanged() method
• GitHub: Coming soon (will be open-sourced after initial release)

---

Would be happy to share more implementation details or collaborate on getting this into Claude Code core!

Quick Demo

If anyone wants to test this approach:

Option 1: Binary Download

# GODA binary with MCP categorization will be available soon
# Available for Windows, macOS, Linux
# Download link: TBD (after open-source release)

Option 2: Build from Source

# Source code will be available after initial release
# Requirements: Go 1.21+
# Build: go build -o goda ./cmd/goda/
# Run: ./goda mcp -serve

Configuration Example:

{
  "mcpServers": {
    "goda": {
      "command": "goda",
      "args": ["mcp", "-serve", "-headless=false"],
      "env": {
        "GODA_TOOL_CATEGORIES": "core,checkpoint,lighthouse"
      }
    }
  }
}

Try Dynamic Categorization:

# Tools change instantly, no restart needed
mcp__goda__set_tool_categories(categories: "core,lighthouse")
mcp__goda__set_tool_categories(categories: "*")  # All tools
mcp__goda__set_tool_categories(categories: "core,checkpoint")  # Minimal

The key insight: fix the problem at the server level while Claude Code catches up architecturally.

[tbuechner]

@kolkov This requires a reconnect after modifying the categories, right?

[bowlofarugula]

It's incredibly sad and confusing that Anthropic's own MCP clients don't support the basic discovery features of the protocol they created. Especially when those clients are proprietary so even if the community wanted to contribute that support, they can't.

How could MCP ever be taken seriously when only a fraction of the spec is supported even by its own authors?

It's not like this is a new feature. It was in the very first MCP spec version, front and center under the Tools documentation.