MCP Multi-Server Documentation

A Python library for managing connections to multiple Model Context Protocol (MCP) servers with unified capability discovery and intelligent routing.

Overview

MCP Multi-Server simplifies the complexity of working with multiple MCP servers by providing:

  • Unified Management: Single interface to connect and manage multiple MCP servers simultaneously

  • Automatic Discovery: Discover and aggregate tools, resources, templates and prompts from all connected servers

  • Intelligent Routing: Automatically route tool calls, resource reads, and prompt retrievals to the correct server

  • Collision Detection: Detect and warn about duplicate tool or prompt names across servers

  • Namespace Support: Use namespaced URIs (server:uri) for unambiguous resource routing

  • Type Safety: Full type hints and Pydantic validation for configuration and data models

Key Features

Multi-Server Orchestration

Connect to multiple MCP servers and manage them through a single client interface with automatic lifecycle management using Python’s async context managers.

Capability Aggregation

Automatically discover and aggregate all capabilities (tools, resources, resource templates, prompts) from all connected servers into a unified view.

Smart Routing

  • Tools & Prompts: Auto-route by name - no need to specify which server

  • Resources: Support for namespaced URIs (server:resource://path) for explicit routing

  • Explicit Override: Optionally specify target server for any operation

Developer Experience

  • Simple programmatic or file-based configuration

  • Comprehensive error handling

  • Full async/await support

  • Synchronous client option for non-async code

  • Rich logging for debugging

Quick Start

Installation

pip install mcp-multi-server

Or with Poetry:

poetry add mcp-multi-server

Basic Usage

import asyncio
from mcp_multi_server import MultiServerClient

async def main():
    # Connect to multiple servers from config file
    async with MultiServerClient.from_config("mcp_servers.json") as client:
        # List all tools from all servers
        tools = client.list_tools()
        print(f"Found {len(tools.tools)} tools across all servers")

        # Call a tool (automatically routed to correct server)
        result = await client.call_tool(
            "read_file",
            {"path": "/path/to/file.txt"}
        )

        # List resources with server namespaces
        resources = client.list_resources()

        # Read a resource (auto-routing via namespace)
        content = await client.read_resource(
            "filesystem:file:///path/to/file.txt"
        )

        # Get a prompt with parameters
        prompt = await client.get_prompt(
            "code_review",
            {"language": "python"}
        )

asyncio.run(main())

Synchronous Usage

For non-async code, use SyncMultiServerClient:

from mcp_multi_server import SyncMultiServerClient

# Using context manager (recommended)
with SyncMultiServerClient.from_config("mcp_servers.json") as client:
    tools = client.list_tools()
    result = client.call_tool("read_file", {"path": "/path/to/file.txt"})
    resources = client.list_resources()

The sync client runs a background event loop thread and provides the same API as the async client, with optional timeout parameters on blocking methods.

Configuration

Create a mcp_servers.json file:

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": ["-m", "my_servers.filesystem_server"]
    },
    "database": {
      "command": "python",
      "args": ["-m", "my_servers.database_server"]
    }
  }
}

Documentation Contents

Use Cases

  • AI Agents: Build agents that can interact with multiple data sources and tools

  • Multi-Domain Applications: Access capabilities from different domains (filesystem, database, APIs)

  • Microservices: Aggregate capabilities from multiple microservices

  • Development Tools: Create unified interfaces for development tooling

Next Steps

Project Status

  • Version: 1.1.0.post1

  • Status: Production Ready

  • Python: 3.10+

  • Test Coverage: 81%

  • License: MIT

Support