feat: Add progressive tool discovery system #1643
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Implements optional progressive disclosure of MCP tools through semantic grouping
and lazy-loading. Servers can organize tools into semantic groups with gateway
tools that load actual tools on-demand, achieving significant reduction in context
token usage.
## Architecture
### Core Components
- ToolGroup: Semantic organization of related tools
- ToolGroupRegistry & ToolGroupManager: Discovery infrastructure
- Server.enable_discovery_with_groups(): Simple API to enable discovery
- is_discovery_enabled: Property to check discovery status
- Client-side tool refresh: Automatic handling via ToolListChangedNotification
### Key Features
- Hybrid mode: Mix direct tools with grouped tools
- Lazy loading: Tools load only when needed
- Non-blocking refresh: Tool refresh happens in background
- Backward compatible: Discovery is entirely opt-in
- No protocol changes: Works with existing MCP clients
## Usage Example
\`\`\`python
from mcp.server import Server
from mcp import ToolGroup, Tool
math_group = ToolGroup(
name='math',
description='Mathematical operations',
tools=[
Tool(name='add', description='Add numbers', inputSchema={...}),
Tool(name='subtract', description='Subtract numbers', inputSchema={...}),
]
)
server = Server('my-service')
server.enable_discovery_with_groups([math_group])
\`\`\`
## Testing
- 5 new discovery-specific tests: All passing
- 41/44 total tests passing (3 pre-existing unrelated failures)
- Backward compatibility verified with SDK examples
- Real-world examples with live weather APIs
## Files Changed
New files:
- src/mcp/server/discovery/__init__.py
- src/mcp/server/discovery/manager.py
- src/mcp/server/discovery/tool_group.py
- tests/test_discovery.py
- tests/test_discovery_integration.py
- examples/discovery/ (with server, agent, and README)
Modified files:
- src/mcp/__init__.py (export ToolGroup)
- src/mcp/client/session.py (callback support)
- src/mcp/client/session_group.py (tool refresh handling)
- src/mcp/server/lowlevel/server.py (discovery integration)
- tests/client/test_session_group.py (5 new tests)
## Benefits
- Token efficiency: Significant reduction in context token usage for large tool sets
- Scalability: Supports servers with many tools
- LLM autonomy: LLM decides which tools to load
- Clean architecture: Semantic grouping is explicit
- Backward compatible: No breaking changes, fully opt-in
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview
This PR implements optional progressive disclosure of MCP tools through semantic grouping and lazy-loading. Servers can organize tools into semantic groups with gateway tools that load actual tools on-demand, achieving significant reduction in context token usage.
Problem Being Solved
MCP servers with 50+ tools currently expose all tool definitions upfront, causing significant context bloat. This wastes valuable context budget and makes it harder for LLMs to reason effectively.
Solution
Progressive tool discovery allows servers to:
Key Features
is_discovery_enableddefaults to FalseImplementation
New components:
Testing
All tests pass:
Backward Compatibility
100% compatible:
Benefits