MCP Tool Integration: Selective tool registration and filtering

Problem

When integrating MCP (Model Context Protocol) servers like repomix, we encounter the issue of receiving too many tools that aren't useful to our use case. For example, repomix provides file-read/write tools that we already have in our existing tool suite.

Current State

The current implementation includes a filter_tools_regex field in AgentBase to filter tools by name after they are loaded from MCP servers. However, this approach has limitations:

1. Client-side filtering only: We can only filter tools after they've been loaded, not prevent them from being initialized in the first place
2. Regex-based filtering: This is a somewhat crude approach that requires users to write complex regex patterns
3. No selective registration: We can't selectively choose which tools to register from an MCP server during initialization

Proposed Solution

For a more elegant solution, we should consider:

Phase 1: Enhanced MCP Integration

• Add a register_mcp_tools() function that:
  • Sends MCP config to the server
  • Queries the server to list available tool names
  • Allows selective registration of specific tools by name
  • Provides a way to exclude certain tools or tool patterns

Phase 2: Spec-based Tool Selection

• Move towards a ToolSpec-first approach where:
  • Users can specify exactly which tools they want from each MCP server
  • Tool selection happens at the specification level, not at runtime filtering
  • Better integration with the existing tool registry system

Example API Design

# Instead of loading all tools and filtering
mcp_config = {
    "mcpServers": {
        "repomix": {
            "command": "uvx",
            "args": ["mcp-server-repomix"],
            "include_tools": ["pack_codebase"],  # Only load specific tools
            "exclude_tools": ["file_read", "file_write"]  # Exclude conflicting tools
        }
    }
}

# Or via tool specs
tools = [
    ToolSpec(name="repomix.pack_codebase", source="mcp://repomix"),
    # Other tools...
]

Benefits

1. Reduced overhead: Only initialize the tools we actually need
2. Better UX: Users don't need to write complex regex patterns
3. Cleaner architecture: Tool selection happens at the specification level
4. Future-proof: Aligns with the ToolSpec-first direction of the SDK

Questions for Discussion

1. Should we keep the filter_tools_regex field for backward compatibility, or remove it in favor of more explicit tool selection?
2. How should we handle tool name conflicts between MCP servers and built-in tools?
3. Should tool filtering be a server-side concern (in the MCP server) or client-side (in the agent-sdk)?

Related

• PR #356: Unify tool initialization — Step 1: global registry + lazy materialization
• Issue #350: Tool initialization unification

This issue was created based on discussion in PR #356 where @xingyaoww noted that the regex filtering approach might not be necessary if we implement proper selective MCP tool registration.

Start by reading AgentBase's current filter_tools_regex behavior, then review PR #356 and issue #350 for the proposed tool-initialization direction. Clarify the selective MCP registration API, compatibility expectations, conflict handling, and whether filtering is client- or server-side; done requires an agreed scope and acceptance criteria for tool selection.