Skip to main content

Overview

MultiMCPHandler allows you to connect to multiple MCP servers at once, aggregating all their tools into a unified interface.

Basic Usage

Parameters

  • commands (List[str]): List of command strings for each server
  • server_params_list: List of server parameter objects
  • timeout_seconds (int): Connection timeout for all servers (default: 5)
  • include_tools (List[str]): Optional list of tool names to include from all servers
  • exclude_tools (List[str]): Optional list of tool names to exclude from all servers
  • tool_name_prefix (str): Optional single prefix for all servers (becomes prefix_0, prefix_1, etc.)
  • tool_name_prefixes (List[str]): Optional list of specific prefixes for each server (must match number of servers)

Features

  • Multiple Connections: Connect to multiple servers simultaneously
  • Unified Interface: All tools from all servers available in one place
  • Server Introspection: Get information about each server and its tools
  • Automatic Cleanup: Properly closes all connections after task completion

Server Introspection

Example with Structured Output

Tool Name Prefixes

When connecting to multiple servers of the same type, tools may have identical names (e.g., both SQLite servers have create_table). Use prefixes to distinguish them: Specify exact prefixes for each server:

Using tool_name_prefix (Auto-indexed)

Use a single base prefix that gets automatically indexed:

Prefix Benefits

  • Prevents Collisions: Multiple servers with same tool names work together
  • Clear Identification: Agents know exactly which server’s tool to use
  • Better Instructions: Task descriptions can reference specific prefixed tools

When to Use

  • Need to work with multiple MCP servers simultaneously
  • Want to aggregate tools from different servers
  • Need to coordinate operations across multiple databases/services
  • Want unified tool interface for multiple connections
  • Use prefixes when servers have overlapping tool names