# ToolMux 🛠️
🚀 **98.65% Token Reduction** - Efficient MCP server aggregation with HTTP/SSE support and on-demand loading
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
## The Problem
Traditional MCP bridges load **all tool schemas upfront**, consuming 15-20% of your token budget before you even start:
- Large deployments can have hundreds of tools across multiple servers
- Each schema consumes tokens even if never used
- Mixed stdio/HTTP servers require separate client implementations
- **Result**: Token budgets exhausted before real work begins
## The Solution
ToolMux exposes only **4 meta-tools** with unified stdio/HTTP support and loads servers on-demand:
| Approach | Tools Loaded | Token Usage | Transport Support | Functionality |
|----------|--------------|-------------|-------------------|---------------|
| **Traditional Bridge** | All schemas | 15-20% tokens | Single protocol | ✅ Full access |
| **ToolMux** | 4 meta-tools | 1.35% tokens | Mixed stdio/HTTP | ✅ Full access |
## Real Performance
In a deployment with 200+ tools across 11 MCP servers (stdio + HTTP):
- **Before**: ~20% token usage for schema loading
- **After**: 1.35% token usage with ToolMux
- **Savings**: 98.65% reduction in overhead
- **Bonus**: Unified interface for mixed transport protocols
## Requirements
- **Python 3.10+** (required for fastmcp dependency)
- pip3 (Python package manager)
- Virtual environment support (recommended)
**Dependencies**:
- `fastmcp>=0.2.0` - FastMCP runtime for MCP protocol support
- `httpx>=0.24.0` - HTTP client for HTTP/SSE MCP servers
- `websockets>=11.0.0` - WebSocket support for real-time communication
- `pydantic>=2.6.0` - Data validation and settings management
- `click>=8.0.0` - CLI interface and command handling
**Note**: Python 3.10+ is required for full functionality including HTTP/SSE transport support.
## Installation
### Quick Install (Recommended)
```bash
uvx toolmux
```
That's it! ToolMux will auto-configure on first run.
**🎉 Now available on PyPI: https://pypi.org/project/toolmux/**
### Latest Updates (v1.2.1)
- ✅ **Fixed**: First-time setup now properly copies all bundled resources (`Prompt/`, `scripts/`, `examples/`)
- ✅ **Enhanced**: Complete local access to agent instructions and scripts after installation
- ✅ **Improved**: Better user experience with all resources available in `~/toolmux/`
### Alternative Methods
#### Install as Persistent Tool
```bash
uv tool install toolmux
```
#### Install from Git (Development)
```bash
uvx --from git+https://github.com/subnetangel/ToolMux toolmux
```
#### Install Specific Version
```bash
uvx toolmux@1.2.1
```
#### Manual Install (Development)
```bash
# Clone the repository
git clone https://github.com/subnetangel/ToolMux.git
cd ToolMux
# Install dependencies
pip install -r requirements.txt
# Run directly
python toolmux.py
```
## Quick Start
### 1. Install and First Run
```bash
# Install ToolMux
uvx toolmux
# First run creates configuration
toolmux --list-servers
```
On first run, ToolMux creates:
- `~/toolmux/mcp.json` - Your main configuration file
- `~/toolmux/examples/` - Reference configurations for copy-paste
### 2. Configure Your Servers
Edit `~/toolmux/mcp.json` to add your MCP servers:
```json
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
"description": "Local filesystem access"
},
"brave-search": {
"command": "uvx",
"args": ["mcp-server-brave-search"],
"env": {"BRAVE_API_KEY": "your-key"},
"description": "Web search using Brave Search API"
},
"remote-api": {
"transport": "http",
"base_url": "https://api.example.com/mcp",
"headers": {"Authorization": "Bearer your-token"},
"timeout": 30,
"description": "Remote HTTP MCP server"
}
}
}
```
### 3. Run ToolMux
```bash
# Basic usage
toolmux
# With custom config
toolmux --config /path/to/custom.json
# List configured servers
toolmux --list-servers
# See all options
toolmux --help
```
## How It Works
ToolMux exposes 4 efficient meta-tools:
### 🔍 Discovery
```bash
catalog_tools # List all available tools from all servers
```
### 📋 Schema
```bash
get_tool_schema({"name": "read_file"}) # Get parameters for specific tool
```
### ⚡ Execute
```bash
invoke({"name": "read_file", "args": {"path": "/tmp/test.txt"}}) # Run any tool
```
### 📊 Stats
```bash
get_tool_count # Show tool count by server
```
## HTTP/SSE MCP Support 🌐
ToolMux supports **mixed configurations** with both stdio and HTTP/SSE MCP servers:
### Architecture
```
Q CLI (stdio) ↔ ToolMux (stdio) ↔ Mixed MCP Servers
├── stdio servers
└── HTTP/SSE servers
```
### Benefits
- **Unified Interface**: Q CLI sees all tools as single stdio server
- **Mixed Deployments**: Combine local stdio + remote HTTP servers
- **Transparent Routing**: ToolMux handles protocol translation
- **Backward Compatible**: Existing stdio configs unchanged
- **Scalable**: Add HTTP servers without Q CLI changes
### HTTP Server Configuration
```json
{
"servers": {
"local-stdio": {
"command": "python",
"args": ["server.py"]
},
"remote-http": {
"transport": "http",
"base_url": "https://api.example.com/mcp",
"headers": {"Authorization": "Bearer token"},
"timeout": 30,
"sse_endpoint": "/events"
}
}
}
```
### Authentication Options
- **Bearer Tokens**: `"Authorization": "Bearer your-token"`
- **API Keys**: `"X-API-Key": "your-api-key"`
- **OAuth**: `"Authorization": "Bearer oauth-token"`
- **Custom Headers**: Any additional headers needed
### Testing HTTP Support
```bash
# Start test HTTP server
python test_http_server.py
# Test mixed configuration
python test_http_transport.py
# Run ToolMux with mixed servers
./toolmux.py --config mixed_servers.json
```
## Adding Servers
ToolMux uses a single `mcp.json` configuration file. Copy examples from `~/toolmux/examples/` into your main config.
### Popular MCP Servers
#### Filesystem Access
```json
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
"description": "Local filesystem access"
}
```
#### Web Search (Brave)
```json
"brave-search": {
"command": "uvx",
"args": ["mcp-server-brave-search"],
"env": {"BRAVE_API_KEY": "your-api-key"},
"description": "Web search using Brave Search API"
}
```
#### Database Access (SQLite)
```json
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "/path/to/database.sqlite"],
"description": "SQLite database queries"
}
```
#### GitHub Integration
```json
"github": {
"command": "uvx",
"args": ["mcp-server-github"],
"env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"},
"description": "GitHub repository and issue management"
}
```
#### HTTP MCP Server
```json
"remote-api": {
"transport": "http",
"base_url": "https://api.example.com/mcp",
"headers": {"Authorization": "Bearer your-token"},
"timeout": 30,
"description": "Remote HTTP MCP server"
}
```
### Configuration Reference
All server configurations support:
- `command` + `args`: Command to run (stdio servers)
- `transport`: "http" for HTTP servers (default: stdio)
- `base_url`: HTTP server endpoint
- `headers`: HTTP headers for authentication
- `timeout`: Request timeout in seconds
- `env`: Environment variables
- `cwd`: Working directory
- `description`: Human-readable description
## Agent Integration
### Q CLI Integration
#### Quick Start (Recommended)
```json
{
"name": "simple-toolmux-agent",
"mcpServers": {
"toolmux": {
"command": "uvx",
"args": ["toolmux"],
"timeout": 30000
}
},
"tools": ["*"],
"systemPrompt": "Use catalog_tools to see available tools, get_tool_schema for parameters, and invoke to execute tools."
}
```
#### Complete Configuration
See `toolmux/examples/q-cli-agent.json` for a comprehensive Q CLI configuration with:
- Detailed system prompt explaining ToolMux workflow
- All 4 meta-tools explicitly listed
- Hooks and examples
- Alternative installation methods
#### Available Examples
After installation, examples are available in the package:
```bash
# Find example configurations
python -c "import toolmux; import os; print(os.path.join(os.path.dirname(toolmux.__file__), 'examples'))"
```
- `q-cli-simple.json` - Minimal configuration to get started
- `q-cli-agent.json` - Complete configuration with all features
- `example_agent_config.json` - Legacy example (updated for v1.2.1)
### Other AI Clients
Include the agent instructions from the installed package to ensure proper meta-tool usage:
```bash
# After installing with uvx/uv, find the instructions at:
python -c "import toolmux; import os; print(os.path.join(os.path.dirname(toolmux.__file__), 'Prompt', 'AGENT_INSTRUCTIONS.md'))"
```
## Files Included
### Core Package
- `toolmux/main.py` - Main multiplexer server
- `toolmux/examples/` - Configuration examples and templates
- `toolmux/Prompt/AGENT_INSTRUCTIONS.md` - Agent behavior guide
- `toolmux/scripts/toolmux_hook.sh` - Q CLI agent hook
### Configuration Files
- `mcp.json` - Default server configuration (created on first run)
- Example configurations in `toolmux/examples/`:
- `q-cli-simple.json` - Minimal Q CLI setup
- `q-cli-agent.json` - Complete Q CLI configuration
- `example_agent_config.json` - Legacy example (updated for v1.2.1)
## Benefits
✅ **98.65% token reduction** - Only 4 tools vs hundreds of schemas
✅ **On-demand loading** - Servers start when needed
✅ **Standard config** - Uses familiar `mcp.json` format
✅ **Zero breaking changes** - Works with any MCP server
✅ **Full functionality** - Access all tools through meta-tools
## Use Cases
Perfect for:
- **AI Assistants** with multiple MCP servers
- **Token-constrained environments**
- **Large MCP deployments** (10+ servers)
- **Development workflows** with many tools
## Architecture
### System Overview
```mermaid
graph TB
subgraph "AI Client Layer"
QCli["Q CLI Agent"]
Claude["Claude Desktop"]
Custom["Custom AI Client"]
end
subgraph "ToolMux Core"
TM["ToolMux Server<br/>(4 Meta-Tools)"]
Cache["Tool Cache"]
Router["Protocol Router"]
end
subgraph "MCP Server Layer"
subgraph "Stdio Servers"
FS["Filesystem<br/>Server"]
SQLite["SQLite<br/>Server"]
Git["Git<br/>Server"]
end
subgraph "HTTP/SSE Servers"
API1["Remote API<br/>Server"]
Search["Search<br/>Service"]
Cloud["Cloud<br/>Service"]
end
end
QCli -.->|stdio| TM
Claude -.->|stdio| TM
Custom -.->|stdio| TM
TM --> Cache
TM --> Router
Router -->|stdio| FS
Router -->|stdio| SQLite
Router -->|stdio| Git
Router -->|HTTP/SSE| API1
Router -->|HTTP/SSE| Search
Router -->|HTTP/SSE| Cloud
style TM fill:#e1f5fe
style Router fill:#f3e5f5
style Cache fill:#e8f5e8
```
### Token Usage Comparison
```mermaid
pie title Token Usage: Traditional vs ToolMux
"Traditional: Schema Loading" : 18.65
"Traditional: Actual Work" : 81.35
"ToolMux: Meta-Tools" : 1.35
"ToolMux: Actual Work" : 98.65
```
### Mixed Transport Architecture
```mermaid
graph LR
subgraph "Client"
Agent["AI Agent<br/>(Q CLI)"]
end
subgraph "ToolMux"
Core["ToolMux Core<br/>stdio interface"]
HTTP["HTTP Client"]
Stdio["Stdio Manager"]
end
subgraph "MCP Servers"
S1["Local Server 1<br/>(stdio)"]
S2["Local Server 2<br/>(stdio)"]
S3["Remote Server 1<br/>(HTTP)"]
S4["Remote Server 2<br/>(SSE)"]
end
Agent -->|stdio| Core
Core --> HTTP
Core --> Stdio
Stdio -->|subprocess| S1
Stdio -->|subprocess| S2
HTTP -->|HTTPS| S3
HTTP -->|WebSocket/SSE| S4
style Core fill:#e1f5fe
style HTTP fill:#fff3e0
style Stdio fill:#e8f5e8
```
## Interaction Flow
### Tool Discovery and Execution Flow
```mermaid
sequenceDiagram
participant Agent as AI Agent
participant TM as ToolMux
participant Cache as Tool Cache
participant Server as MCP Server
Note over Agent,Server: 1. Discovery Phase
Agent->>TM: catalog_tools()
TM->>Cache: Check cached tools
alt Cache Miss
TM->>Server: Start server (on-demand)
Server-->>TM: Server ready
TM->>Server: List tools
Server-->>TM: Tool list
TM->>Cache: Cache tools
else Cache Hit
Cache-->>TM: Return cached tools
end
TM-->>Agent: All available tools
Note over Agent,Server: 2. Schema Retrieval
Agent->>TM: get_tool_schema({"name": "read_file"})
TM->>Cache: Check schema cache
alt Schema Cached
Cache-->>TM: Return schema
else Schema Not Cached
TM->>Server: Get tool schema
Server-->>TM: Tool schema
TM->>Cache: Cache schema
end
TM-->>Agent: Tool schema
Note over Agent,Server: 3. Tool Execution
Agent->>TM: invoke({"name": "read_file", "args": {...}})
TM->>Server: Execute tool
Server-->>TM: Tool result
TM-->>Agent: Execution result
```
### HTTP vs Stdio Server Handling
```mermaid
flowchart TD
Start([Tool Request]) --> Check{Server Type?}
Check -->|stdio| StdioFlow[Stdio Flow]
Check -->|HTTP| HTTPFlow[HTTP Flow]
subgraph "Stdio Processing"
StdioFlow --> StartProc[Start subprocess]
StartProc --> SendJSON[Send JSON-RPC]
SendJSON --> ReadResp[Read response]
ReadResp --> StdioResult[Return result]
end
subgraph "HTTP Processing"
HTTPFlow --> HTTPReq[HTTP Request]
HTTPReq --> Auth[Add authentication]
Auth --> SendHTTP[Send to endpoint]
SendHTTP --> ParseHTTP[Parse response]
ParseHTTP --> HTTPResult[Return result]
end
StdioResult --> End([Result to Agent])
HTTPResult --> End
style StdioFlow fill:#e8f5e8
style HTTPFlow fill:#fff3e0
```
### On-Demand Server Loading
```mermaid
stateDiagram-v2
[*] --> Idle: ToolMux starts
Idle --> CheckCache: Tool request received
CheckCache --> ServerRunning: Server already running
CheckCache --> StartServer: Server not running
StartServer --> Initializing: Launch server process
Initializing --> Ready: Server responds
Initializing --> Failed: Server fails to start
Ready --> ServerRunning: Server available
ServerRunning --> ExecuteTool: Forward request
ExecuteTool --> ServerRunning: Tool executed
ServerRunning --> Idle: Request complete
Failed --> [*]: Error returned
note right of StartServer
Only starts when
tool is requested
end note
note right of ServerRunning
Server stays running
for subsequent requests
end note
```
### Error Handling Flow
```mermaid
flowchart TD
Request[Tool Request] --> Validate{Valid Request?}
Validate -->|No| ValidationError[Return validation error]
Validate -->|Yes| FindServer{Server exists?}
FindServer -->|No| ServerError[Return server not found]
FindServer -->|Yes| CheckRunning{Server running?}
CheckRunning -->|No| StartServer[Start server]
CheckRunning -->|Yes| ExecuteTool[Execute tool]
StartServer --> StartSuccess{Start successful?}
StartSuccess -->|No| StartError[Return startup error]
StartSuccess -->|Yes| ExecuteTool
ExecuteTool --> ToolSuccess{Tool executed?}
ToolSuccess -->|No| ToolError[Return execution error]
ToolSuccess -->|Yes| Success[Return result]
ValidationError --> ErrorResponse[Format error response]
ServerError --> ErrorResponse
StartError --> ErrorResponse
ToolError --> ErrorResponse
ErrorResponse --> End[Return to agent]
Success --> End
style ValidationError fill:#ffebee
style ServerError fill:#ffebee
style StartError fill:#ffebee
style ToolError fill:#ffebee
style Success fill:#e8f5e8
```
## License
MIT License - see LICENSE file for details
---
*Built for the MCP community to make AI assistants more efficient* 🤖
Raw data
{
"_id": null,
"home_page": null,
"name": "toolmux",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, multiplexer, aggregation, toolmux, ai, agents, tools",
"author": null,
"author_email": "JP Ruiz <juanpa.ruiz@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/87/6bb88358c1c91f90264ca6dc045ece3de07e844ee2b9f2a6893f516ba7b4/toolmux-1.2.1.tar.gz",
"platform": null,
"description": "# ToolMux \ud83d\udee0\ufe0f\n\n\ud83d\ude80 **98.65% Token Reduction** - Efficient MCP server aggregation with HTTP/SSE support and on-demand loading\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://modelcontextprotocol.io/)\n\n## The Problem\n\nTraditional MCP bridges load **all tool schemas upfront**, consuming 15-20% of your token budget before you even start:\n\n- Large deployments can have hundreds of tools across multiple servers\n- Each schema consumes tokens even if never used\n- Mixed stdio/HTTP servers require separate client implementations\n- **Result**: Token budgets exhausted before real work begins\n\n## The Solution\n\nToolMux exposes only **4 meta-tools** with unified stdio/HTTP support and loads servers on-demand:\n\n| Approach | Tools Loaded | Token Usage | Transport Support | Functionality |\n|----------|--------------|-------------|-------------------|---------------|\n| **Traditional Bridge** | All schemas | 15-20% tokens | Single protocol | \u2705 Full access |\n| **ToolMux** | 4 meta-tools | 1.35% tokens | Mixed stdio/HTTP | \u2705 Full access |\n\n## Real Performance\n\nIn a deployment with 200+ tools across 11 MCP servers (stdio + HTTP):\n- **Before**: ~20% token usage for schema loading\n- **After**: 1.35% token usage with ToolMux \n- **Savings**: 98.65% reduction in overhead\n- **Bonus**: Unified interface for mixed transport protocols\n\n## Requirements\n\n- **Python 3.10+** (required for fastmcp dependency)\n- pip3 (Python package manager)\n- Virtual environment support (recommended)\n\n**Dependencies**:\n- `fastmcp>=0.2.0` - FastMCP runtime for MCP protocol support\n- `httpx>=0.24.0` - HTTP client for HTTP/SSE MCP servers\n- `websockets>=11.0.0` - WebSocket support for real-time communication\n- `pydantic>=2.6.0` - Data validation and settings management\n- `click>=8.0.0` - CLI interface and command handling\n\n**Note**: Python 3.10+ is required for full functionality including HTTP/SSE transport support.\n\n## Installation\n\n### Quick Install (Recommended)\n```bash\nuvx toolmux\n```\n\nThat's it! ToolMux will auto-configure on first run.\n\n**\ud83c\udf89 Now available on PyPI: https://pypi.org/project/toolmux/**\n\n### Latest Updates (v1.2.1)\n- \u2705 **Fixed**: First-time setup now properly copies all bundled resources (`Prompt/`, `scripts/`, `examples/`)\n- \u2705 **Enhanced**: Complete local access to agent instructions and scripts after installation\n- \u2705 **Improved**: Better user experience with all resources available in `~/toolmux/`\n\n### Alternative Methods\n\n#### Install as Persistent Tool\n```bash\nuv tool install toolmux\n```\n\n#### Install from Git (Development)\n```bash\nuvx --from git+https://github.com/subnetangel/ToolMux toolmux\n```\n\n#### Install Specific Version\n```bash\nuvx toolmux@1.2.1\n```\n\n#### Manual Install (Development)\n```bash\n# Clone the repository\ngit clone https://github.com/subnetangel/ToolMux.git\ncd ToolMux\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run directly\npython toolmux.py\n```\n\n## Quick Start\n\n### 1. Install and First Run\n```bash\n# Install ToolMux\nuvx toolmux\n\n# First run creates configuration\ntoolmux --list-servers\n```\n\nOn first run, ToolMux creates:\n- `~/toolmux/mcp.json` - Your main configuration file\n- `~/toolmux/examples/` - Reference configurations for copy-paste\n\n### 2. Configure Your Servers\nEdit `~/toolmux/mcp.json` to add your MCP servers:\n\n```json\n{\n \"servers\": {\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/home/user\"],\n \"description\": \"Local filesystem access\"\n },\n \"brave-search\": {\n \"command\": \"uvx\", \n \"args\": [\"mcp-server-brave-search\"],\n \"env\": {\"BRAVE_API_KEY\": \"your-key\"},\n \"description\": \"Web search using Brave Search API\"\n },\n \"remote-api\": {\n \"transport\": \"http\",\n \"base_url\": \"https://api.example.com/mcp\",\n \"headers\": {\"Authorization\": \"Bearer your-token\"},\n \"timeout\": 30,\n \"description\": \"Remote HTTP MCP server\"\n }\n }\n}\n```\n\n### 3. Run ToolMux\n```bash\n# Basic usage\ntoolmux\n\n# With custom config\ntoolmux --config /path/to/custom.json\n\n# List configured servers\ntoolmux --list-servers\n\n# See all options\ntoolmux --help\n```\n\n## How It Works\n\nToolMux exposes 4 efficient meta-tools:\n\n### \ud83d\udd0d Discovery\n```bash\ncatalog_tools # List all available tools from all servers\n```\n\n### \ud83d\udccb Schema\n```bash\nget_tool_schema({\"name\": \"read_file\"}) # Get parameters for specific tool\n```\n\n### \u26a1 Execute \n```bash\ninvoke({\"name\": \"read_file\", \"args\": {\"path\": \"/tmp/test.txt\"}}) # Run any tool\n```\n\n### \ud83d\udcca Stats\n```bash\nget_tool_count # Show tool count by server\n```\n\n## HTTP/SSE MCP Support \ud83c\udf10\n\nToolMux supports **mixed configurations** with both stdio and HTTP/SSE MCP servers:\n\n### Architecture\n```\nQ CLI (stdio) \u2194 ToolMux (stdio) \u2194 Mixed MCP Servers\n \u251c\u2500\u2500 stdio servers\n \u2514\u2500\u2500 HTTP/SSE servers\n```\n\n### Benefits\n- **Unified Interface**: Q CLI sees all tools as single stdio server\n- **Mixed Deployments**: Combine local stdio + remote HTTP servers \n- **Transparent Routing**: ToolMux handles protocol translation\n- **Backward Compatible**: Existing stdio configs unchanged\n- **Scalable**: Add HTTP servers without Q CLI changes\n\n### HTTP Server Configuration\n```json\n{\n \"servers\": {\n \"local-stdio\": {\n \"command\": \"python\", \n \"args\": [\"server.py\"]\n },\n \"remote-http\": {\n \"transport\": \"http\",\n \"base_url\": \"https://api.example.com/mcp\",\n \"headers\": {\"Authorization\": \"Bearer token\"},\n \"timeout\": 30,\n \"sse_endpoint\": \"/events\"\n }\n }\n}\n```\n\n### Authentication Options\n- **Bearer Tokens**: `\"Authorization\": \"Bearer your-token\"`\n- **API Keys**: `\"X-API-Key\": \"your-api-key\"`\n- **OAuth**: `\"Authorization\": \"Bearer oauth-token\"`\n- **Custom Headers**: Any additional headers needed\n\n### Testing HTTP Support\n```bash\n# Start test HTTP server\npython test_http_server.py\n\n# Test mixed configuration\npython test_http_transport.py\n\n# Run ToolMux with mixed servers\n./toolmux.py --config mixed_servers.json\n```\n\n## Adding Servers\n\nToolMux uses a single `mcp.json` configuration file. Copy examples from `~/toolmux/examples/` into your main config.\n\n### Popular MCP Servers\n\n#### Filesystem Access\n```json\n\"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/home/user\"],\n \"description\": \"Local filesystem access\"\n}\n```\n\n#### Web Search (Brave)\n```json\n\"brave-search\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-brave-search\"],\n \"env\": {\"BRAVE_API_KEY\": \"your-api-key\"},\n \"description\": \"Web search using Brave Search API\"\n}\n```\n\n#### Database Access (SQLite)\n```json\n\"sqlite\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-sqlite\", \"--db-path\", \"/path/to/database.sqlite\"],\n \"description\": \"SQLite database queries\"\n}\n```\n\n#### GitHub Integration\n```json\n\"github\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-github\"],\n \"env\": {\"GITHUB_PERSONAL_ACCESS_TOKEN\": \"your-token\"},\n \"description\": \"GitHub repository and issue management\"\n}\n```\n\n#### HTTP MCP Server\n```json\n\"remote-api\": {\n \"transport\": \"http\",\n \"base_url\": \"https://api.example.com/mcp\",\n \"headers\": {\"Authorization\": \"Bearer your-token\"},\n \"timeout\": 30,\n \"description\": \"Remote HTTP MCP server\"\n}\n```\n\n### Configuration Reference\n\nAll server configurations support:\n- `command` + `args`: Command to run (stdio servers)\n- `transport`: \"http\" for HTTP servers (default: stdio)\n- `base_url`: HTTP server endpoint\n- `headers`: HTTP headers for authentication\n- `timeout`: Request timeout in seconds\n- `env`: Environment variables\n- `cwd`: Working directory\n- `description`: Human-readable description\n\n## Agent Integration\n\n### Q CLI Integration\n\n#### Quick Start (Recommended)\n```json\n{\n \"name\": \"simple-toolmux-agent\",\n \"mcpServers\": {\n \"toolmux\": {\n \"command\": \"uvx\",\n \"args\": [\"toolmux\"],\n \"timeout\": 30000\n }\n },\n \"tools\": [\"*\"],\n \"systemPrompt\": \"Use catalog_tools to see available tools, get_tool_schema for parameters, and invoke to execute tools.\"\n}\n```\n\n#### Complete Configuration\nSee `toolmux/examples/q-cli-agent.json` for a comprehensive Q CLI configuration with:\n- Detailed system prompt explaining ToolMux workflow\n- All 4 meta-tools explicitly listed\n- Hooks and examples\n- Alternative installation methods\n\n#### Available Examples\nAfter installation, examples are available in the package:\n```bash\n# Find example configurations\npython -c \"import toolmux; import os; print(os.path.join(os.path.dirname(toolmux.__file__), 'examples'))\"\n```\n\n- `q-cli-simple.json` - Minimal configuration to get started\n- `q-cli-agent.json` - Complete configuration with all features\n- `example_agent_config.json` - Legacy example (updated for v1.2.1)\n\n### Other AI Clients\nInclude the agent instructions from the installed package to ensure proper meta-tool usage:\n\n```bash\n# After installing with uvx/uv, find the instructions at:\npython -c \"import toolmux; import os; print(os.path.join(os.path.dirname(toolmux.__file__), 'Prompt', 'AGENT_INSTRUCTIONS.md'))\"\n```\n\n## Files Included\n\n### Core Package\n- `toolmux/main.py` - Main multiplexer server\n- `toolmux/examples/` - Configuration examples and templates\n- `toolmux/Prompt/AGENT_INSTRUCTIONS.md` - Agent behavior guide\n- `toolmux/scripts/toolmux_hook.sh` - Q CLI agent hook\n\n### Configuration Files\n- `mcp.json` - Default server configuration (created on first run)\n- Example configurations in `toolmux/examples/`:\n - `q-cli-simple.json` - Minimal Q CLI setup\n - `q-cli-agent.json` - Complete Q CLI configuration\n - `example_agent_config.json` - Legacy example (updated for v1.2.1)\n\n## Benefits\n\n\u2705 **98.65% token reduction** - Only 4 tools vs hundreds of schemas \n\u2705 **On-demand loading** - Servers start when needed \n\u2705 **Standard config** - Uses familiar `mcp.json` format \n\u2705 **Zero breaking changes** - Works with any MCP server \n\u2705 **Full functionality** - Access all tools through meta-tools \n\n## Use Cases\n\nPerfect for:\n- **AI Assistants** with multiple MCP servers\n- **Token-constrained environments** \n- **Large MCP deployments** (10+ servers)\n- **Development workflows** with many tools\n\n## Architecture\n\n### System Overview\n\n```mermaid\ngraph TB\n subgraph \"AI Client Layer\"\n QCli[\"Q CLI Agent\"]\n Claude[\"Claude Desktop\"]\n Custom[\"Custom AI Client\"]\n end\n \n subgraph \"ToolMux Core\"\n TM[\"ToolMux Server<br/>(4 Meta-Tools)\"]\n Cache[\"Tool Cache\"]\n Router[\"Protocol Router\"]\n end\n \n subgraph \"MCP Server Layer\"\n subgraph \"Stdio Servers\"\n FS[\"Filesystem<br/>Server\"]\n SQLite[\"SQLite<br/>Server\"]\n Git[\"Git<br/>Server\"]\n end\n \n subgraph \"HTTP/SSE Servers\"\n API1[\"Remote API<br/>Server\"]\n Search[\"Search<br/>Service\"]\n Cloud[\"Cloud<br/>Service\"]\n end\n end\n \n QCli -.->|stdio| TM\n Claude -.->|stdio| TM\n Custom -.->|stdio| TM\n \n TM --> Cache\n TM --> Router\n \n Router -->|stdio| FS\n Router -->|stdio| SQLite\n Router -->|stdio| Git\n Router -->|HTTP/SSE| API1\n Router -->|HTTP/SSE| Search\n Router -->|HTTP/SSE| Cloud\n \n style TM fill:#e1f5fe\n style Router fill:#f3e5f5\n style Cache fill:#e8f5e8\n```\n\n### Token Usage Comparison\n\n```mermaid\npie title Token Usage: Traditional vs ToolMux\n \"Traditional: Schema Loading\" : 18.65\n \"Traditional: Actual Work\" : 81.35\n \"ToolMux: Meta-Tools\" : 1.35\n \"ToolMux: Actual Work\" : 98.65\n```\n\n### Mixed Transport Architecture\n\n```mermaid\ngraph LR\n subgraph \"Client\"\n Agent[\"AI Agent<br/>(Q CLI)\"]\n end\n \n subgraph \"ToolMux\"\n Core[\"ToolMux Core<br/>stdio interface\"]\n HTTP[\"HTTP Client\"]\n Stdio[\"Stdio Manager\"]\n end\n \n subgraph \"MCP Servers\"\n S1[\"Local Server 1<br/>(stdio)\"]\n S2[\"Local Server 2<br/>(stdio)\"]\n S3[\"Remote Server 1<br/>(HTTP)\"]\n S4[\"Remote Server 2<br/>(SSE)\"]\n end\n \n Agent -->|stdio| Core\n Core --> HTTP\n Core --> Stdio\n \n Stdio -->|subprocess| S1\n Stdio -->|subprocess| S2\n HTTP -->|HTTPS| S3\n HTTP -->|WebSocket/SSE| S4\n \n style Core fill:#e1f5fe\n style HTTP fill:#fff3e0\n style Stdio fill:#e8f5e8\n```\n\n## Interaction Flow\n\n### Tool Discovery and Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant TM as ToolMux\n participant Cache as Tool Cache\n participant Server as MCP Server\n \n Note over Agent,Server: 1. Discovery Phase\n Agent->>TM: catalog_tools()\n TM->>Cache: Check cached tools\n alt Cache Miss\n TM->>Server: Start server (on-demand)\n Server-->>TM: Server ready\n TM->>Server: List tools\n Server-->>TM: Tool list\n TM->>Cache: Cache tools\n else Cache Hit\n Cache-->>TM: Return cached tools\n end\n TM-->>Agent: All available tools\n \n Note over Agent,Server: 2. Schema Retrieval\n Agent->>TM: get_tool_schema({\"name\": \"read_file\"})\n TM->>Cache: Check schema cache\n alt Schema Cached\n Cache-->>TM: Return schema\n else Schema Not Cached\n TM->>Server: Get tool schema\n Server-->>TM: Tool schema\n TM->>Cache: Cache schema\n end\n TM-->>Agent: Tool schema\n \n Note over Agent,Server: 3. Tool Execution\n Agent->>TM: invoke({\"name\": \"read_file\", \"args\": {...}})\n TM->>Server: Execute tool\n Server-->>TM: Tool result\n TM-->>Agent: Execution result\n```\n\n### HTTP vs Stdio Server Handling\n\n```mermaid\nflowchart TD\n Start([Tool Request]) --> Check{Server Type?}\n \n Check -->|stdio| StdioFlow[Stdio Flow]\n Check -->|HTTP| HTTPFlow[HTTP Flow]\n \n subgraph \"Stdio Processing\"\n StdioFlow --> StartProc[Start subprocess]\n StartProc --> SendJSON[Send JSON-RPC]\n SendJSON --> ReadResp[Read response]\n ReadResp --> StdioResult[Return result]\n end\n \n subgraph \"HTTP Processing\"\n HTTPFlow --> HTTPReq[HTTP Request]\n HTTPReq --> Auth[Add authentication]\n Auth --> SendHTTP[Send to endpoint]\n SendHTTP --> ParseHTTP[Parse response]\n ParseHTTP --> HTTPResult[Return result]\n end\n \n StdioResult --> End([Result to Agent])\n HTTPResult --> End\n \n style StdioFlow fill:#e8f5e8\n style HTTPFlow fill:#fff3e0\n```\n\n### On-Demand Server Loading\n\n```mermaid\nstateDiagram-v2\n [*] --> Idle: ToolMux starts\n \n Idle --> CheckCache: Tool request received\n CheckCache --> ServerRunning: Server already running\n CheckCache --> StartServer: Server not running\n \n StartServer --> Initializing: Launch server process\n Initializing --> Ready: Server responds\n Initializing --> Failed: Server fails to start\n \n Ready --> ServerRunning: Server available\n ServerRunning --> ExecuteTool: Forward request\n ExecuteTool --> ServerRunning: Tool executed\n \n ServerRunning --> Idle: Request complete\n Failed --> [*]: Error returned\n \n note right of StartServer\n Only starts when\n tool is requested\n end note\n \n note right of ServerRunning\n Server stays running\n for subsequent requests\n end note\n```\n\n### Error Handling Flow\n\n```mermaid\nflowchart TD\n Request[Tool Request] --> Validate{Valid Request?}\n \n Validate -->|No| ValidationError[Return validation error]\n Validate -->|Yes| FindServer{Server exists?}\n \n FindServer -->|No| ServerError[Return server not found]\n FindServer -->|Yes| CheckRunning{Server running?}\n \n CheckRunning -->|No| StartServer[Start server]\n CheckRunning -->|Yes| ExecuteTool[Execute tool]\n \n StartServer --> StartSuccess{Start successful?}\n StartSuccess -->|No| StartError[Return startup error]\n StartSuccess -->|Yes| ExecuteTool\n \n ExecuteTool --> ToolSuccess{Tool executed?}\n ToolSuccess -->|No| ToolError[Return execution error]\n ToolSuccess -->|Yes| Success[Return result]\n \n ValidationError --> ErrorResponse[Format error response]\n ServerError --> ErrorResponse\n StartError --> ErrorResponse\n ToolError --> ErrorResponse\n \n ErrorResponse --> End[Return to agent]\n Success --> End\n \n style ValidationError fill:#ffebee\n style ServerError fill:#ffebee\n style StartError fill:#ffebee\n style ToolError fill:#ffebee\n style Success fill:#e8f5e8\n```\n\n## License\n\nMIT License - see LICENSE file for details\n\n---\n\n*Built for the MCP community to make AI assistants more efficient* \ud83e\udd16\n",
"bugtrack_url": null,
"license": null,
"summary": "Efficient MCP server aggregation with HTTP/SSE support and 98% schema token reduction",
"version": "1.2.1",
"project_urls": {
"Homepage": "https://github.com/subnetangel/ToolMux",
"Issues": "https://github.com/subnetangel/ToolMux/issues",
"Repository": "https://github.com/subnetangel/ToolMux"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" multiplexer",
" aggregation",
" toolmux",
" ai",
" agents",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fc0d9ec05918124db9a3332a33215916fd549bc9f479fae2823a8823b363278b",
"md5": "8723f7608a3335de3c5ff5cc6ceaebaa",
"sha256": "9ccdb9aa8cb802842dd9a8247662966665b810072248f56f63bdd8aee46bc196"
},
"downloads": -1,
"filename": "toolmux-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8723f7608a3335de3c5ff5cc6ceaebaa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22456,
"upload_time": "2025-09-02T16:35:37",
"upload_time_iso_8601": "2025-09-02T16:35:37.726696Z",
"url": "https://files.pythonhosted.org/packages/fc/0d/9ec05918124db9a3332a33215916fd549bc9f479fae2823a8823b363278b/toolmux-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c2876bb88358c1c91f90264ca6dc045ece3de07e844ee2b9f2a6893f516ba7b4",
"md5": "faea04ea63b87905ad1f85ab112a6db3",
"sha256": "eb5629506160aaac8a3d322df8f474d80f3b48997277751f54561918506a8a46"
},
"downloads": -1,
"filename": "toolmux-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "faea04ea63b87905ad1f85ab112a6db3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 36403,
"upload_time": "2025-09-02T16:35:38",
"upload_time_iso_8601": "2025-09-02T16:35:38.907506Z",
"url": "https://files.pythonhosted.org/packages/c2/87/6bb88358c1c91f90264ca6dc045ece3de07e844ee2b9f2a6893f516ba7b4/toolmux-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 16:35:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "subnetangel",
"github_project": "ToolMux",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "fastmcp",
"specs": [
[
">=",
"0.2.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.6.0"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.24.0"
]
]
},
{
"name": "websockets",
"specs": [
[
">=",
"11.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.1"
]
]
},
{
"name": "fastapi",
"specs": [
[
">=",
"0.104.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
">=",
"0.24.0"
]
]
}
],
"lcname": "toolmux"
}
JSON
