feat: add MCP tool filtering support

[devtalker]

Add MCP Tool Filtering Support

This PR implements tool filtering capabilities for MCP servers, addressing multiple community requests for this feature.

Problem

Currently, Agent SDK automatically fetches all available tools from MCP servers without the ability to select specific tools. This creates several issues:

• Unwanted tools occupy LLM context and affect tool selection accuracy
• Security concerns when limiting tool access scope
• Tool name conflicts between multiple servers
• Need for different tool subsets across different agents

Solution

Implements a two-level filtering system:

Server-level filtering:

server = MCPServerStdio(
    params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]},
    allowed_tools=["read_file", "write_file"],  # whitelist
    excluded_tools=["delete_file"]  # blacklist
)

Agent-level filtering:

agent = Agent(
    name="Assistant",
    mcp_servers=[server1, server2],
    mcp_config={
        "allowed_tools": {"server1": ["read_file", "write_file"]},
        "excluded_tools": {"server2": ["dangerous_tool"]}
    }
)

Features

• ✅ Server-level allowed_tools/excluded_tools parameters for all MCP server types
• ✅ Agent-level filtering via mcp_config
• ✅ Hierarchical filtering (server-level first, then agent-level)
• ✅ Comprehensive test coverage (8 test cases)
• ✅ Updated documentation with examples

Related Issues

#376, #851, #830, #863

Testing

All existing tests pass + 8 new test cases covering various filtering scenarios.

[devtalker]

Hi @rm-openai! 👋
I've implemented a comprehensive MCP tool filtering feature that addresses the community requests in issues #376, #830, #851, #863. Based on the community discussions, this seems to be a feature many users have been eagerly waiting for! Would you be able to take a look when you have a moment? I'd really appreciate your feedback and guidance on this implementation. Thanks! 🙏

[rm-openai]

I like this. Would however prefer an interface that looked something like this:

ToolFilterCallable = Callable[[ToolFilterContext, Tool], MaybeAwaitable[bool]]
class ToolFilterStatic(TypedDict):
  allowed_tool_names: NotRequired[list[str]]
  blocked_tool_names: NotRequired[list[str]]

and then the MCPServer class would take tool_filter: ToolFilterCallable | ToolFilterStatic | None

thoughts?

[devtalker]

@rm-openai Thanks for your suggestions!
I like this approach! It's very similar to the is_enabled pattern we use in function tools, which makes the API more consistent and intuitive. Supporting a callable for dynamic filtering gives us much more flexibility - we can make runtime decisions based on various conditions, just like we do with function tools. I'll update the PR to implement this design. 🙏

[devtalker]

Hi @rm-openai! 👋

Thank you for the detailed feedback! I've completely redesigned the implementation following your suggested interface pattern.

🔄 Major Changes in This Update:

1. Implemented Your Suggested Interface:

• Added ToolFilterCallable = Callable[[ToolFilterContext, Tool], MaybeAwaitable[bool]]
• Created ToolFilterStatic TypedDict with allowed_tool_names and blocked_tool_names
• MCPServer classes now accept tool_filter: ToolFilterCallable | ToolFilterStatic | None

2. Enhanced Dynamic Filtering Support:
The new interface supports powerful dynamic filtering capabilities:

# Context-aware filtering
def context_filter(context: ToolFilterContext, tool) -> bool:
    # Access agent information
    agent_name = context.agent.name
    # Access server information  
    server_name = context.server_name
    # Custom logic based on runtime context
    return some_dynamic_logic(agent_name, server_name, tool)

# Async filtering for complex operations
async def async_filter(context: ToolFilterContext, tool) -> bool:
    result = await some_async_check(context, tool)
    return result

server = MCPServerStdio(
    params={"command": "npx", "args": [...]},
    tool_filter=context_filter  # or async_filter
)

3. Simplified Static Filtering:

from agents.mcp import create_static_tool_filter

server = MCPServerStdio(
    tool_filter=create_static_tool_filter(
        allowed_tool_names=["read_file", "write_file"],
        blocked_tool_names=["delete_file"]
    )
)

4. Architecture Improvements:

• Removed Agent-level filtering complexity as discussed
• Moved all filtering logic to the MCP server layer for better separation of concerns
• Maintains full backward compatibility

Would you be able to take another look when you have a moment? Thanks again for the great input!